How to Upgrade deprecated PHPUnit withConsecutive()

2024-10-10

What does withConsecutive() method actually do?

$mock = $this->createMock(MyClass::class);
$mock->expects($this->exactly(2))
    ->method('someMethod')
    ->withConsecutive(
        ['first'],
        ['second']
    );

It defines what arguments are on the input once the method mock is called. E.g. here:

• on 1st call, it expects ['first']
• on 2nd call, it expects ['second']

To be honest, I've never written such code myself, but so far, we've found it in every code base we've upgraded. It's been available since 2006 and only removed after 16 years in 2022.

So how can we replace it? It would be very convenient if there would some kind of withNthCall() method:

$mock = $this->createMock(MyClass::class);
$mock->expects($this->exactly(2))
    ->method('someMethod')
    ->withNthCall(1, ['first'])
    ->withNthCall(2, ['second']);

But it's not.

willReturnCallback() to the Rescue

Instead, we use the willReturnCallback() trick. This method accepts the called parameters, which we can assert inside.

$mock = $this->createMock(MyClass::class);
$mock->expects($this->exactly(2))
    ->method('someMethod')
    ->willReturnCallback(function ($parameters) {
        // check the parameters here
    });

But how do we detect if it's the first or second call? The $this->exactly(2) expression actually returns a value object PHPUnit\Framework\MockObject\Rule\InvokedCount that we can work with.

$invokedCount = $this->exactly(2);

$mock = $this->createMock(MyClass::class);
$mock->expects($invokedCount)
    ->method('someMethod')
    ->willReturnCallback(function ($parameters) use ($invokedCount) {
        // check the parameters here
    });

On every mock invoke method, the number of invokes in $invokedCount will increase.

We can use it to detect the 1st or 2nd call:

$invokedCount = $this->exactly(2);

$mock = $this->createMock(MyClass::class);
$mock->expects($invokedCount)
    ->method('someMethod')
    ->willReturnCallback(function ($parameters) use ($invokedCount) {
        if ($invokedCount->getInvocationCount() === 1) {
            // check the 1st round here
        }

        if ($invokedCount->getInvocationCount() === 2) {
            // check the 2nd round here
        }
    });

Now we include the original parameters we needed:

// ...

    ->willReturnCallback(function ($parameters) use ($invokedCount) {
        if ($invokedCount->getInvocationCount() === 1) {
            $this->assertSame(['first'], $parameters);
        }

        if ($invokedCount->getInvocationCount() === 2) {
            $this->assertSame(['second'], $parameters);
        }
    });

Now, this is where this deprecation becomes useful. What if one of the parameters is a product object?

We could create a $product object and do assertSame(). But what if we only care about its price?

// ...
    ->willReturnCallback(function ($parameters) use ($invokedCount) {
        if ($invokedCount->getInvocationCount() === 1) {
            $product = $parameter[0];
            $this->assertInstanceof(Product::class, $product);
            $this->assertSame(100, $product->getPrice());
        }

        // ...
    });

Using withConsecutive() would turn this into a single-line mess. Now, it's more readable and flexible.

Why if over match?

Originally, we used the match() expression over ifs() in the Rector rule, but it created a couple of new problems:

• PHPUnit 9.x requires PHP 7.3+. Using match() would mean you have to do the upgrade to PHP 8 and to PHPUnit 10 at the same time. This is not always possible and can be risky
• The call count is already checked by $this->exactly(2). There is no need to add another layer of complexity to check the same thing again
• With match(), there is only a single line of expression. Assert above would be a single line:

=> $product = $parameters[0] && $this->assertInstanceof(Product::class, $product) && $this->assertSame(100, $product->getPrice())

This code is not readable and maintainable. There is also one more reason why if() is the king.

Return value

More often than not, the method not only accepts parameters but also returns some value. That's where willReturn*() methods come into play:

$mock = $this->createMock(MyClass::class);
$mock->expects($this->exactly(2))
    ->method('someMethod')
    ->withConsecutive(
        ['first'],
        ['second']
    )
    ->willReturnOnConsecutiveCalls([1, 2]);

How do we upgrade any returned value? We just return it:

// ...

    ->willReturnCallback(function ($parameters) use ($invokedCount) {
        if ($invokedCount->getInvocationCount() === 1) {
            $this->assertSame(['first'], $parameters);
            return 1;
        }

        if ($invokedCount->getInvocationCount() === 2) {
            $this->assertSame(['second'], $parameters);
            return 2;
        }
    });

That's it! How about other return methods?

->willReturnArgument(0);
// or
->willReturnSelf();
// or
->willThrowException(new \Exception('Never happens'));

We can just write plain PHP code:

// ...

    ->willReturnCallback(function ($parameters) use ($invokedCount) {
        if ($invokedCount->getInvocationCount() === 1) {
            return $parameters[0];
            // or
            return $this->userServiceMock;
            // or
            throw new Exception('Never happens');
        }
    });

More Readable and Easier to Maintain

• We don't have to learn special PHPUnit mock method naming and can understand the code.
• This vanilla PHP also opens up the next step - refactoring away from mocks to anonymous typed classes
• We can easily add a new assertion line
• We can return values we need

What if upcoming PHPUnit 12, 13... versions, removes or changes more mocking methods? This code will work, as it's just plain PHP.

This is how we can upgrade the withConsecutive() method in PHPUnit 9 or earlier. I hope it's clearer now why this change was needed and how it can help you write better tests.

Last but not least, here is the Rector rule that automated this process.

Happy coding!

---

Do you learn from my contents or use open-souce packages like Rector every day?
Consider supporting it on GitHub Sponsors. I'd really appreciate it!