Technical Implementation of Mocking Method Multiple Calls with Different Arguments in PHPUnit

In unit testing practice, mock objects are essential for isolating dependencies of the component under test. When multiple behaviors need to be configured for the same mock method based on different input parameters, PHPUnit offers various mechanisms, each with specific use cases and considerations.

Fundamental Principles of PHPUnit Mocking Mechanism

PHPUnit's mocking library sets invocation expectations through the expects() method, specifies target methods via method(), and adds parameter constraints with with(). However, when configuring multiple expectations for the same method that differ only in parameters, matching conflicts arise. This occurs because PHPUnit treats all expectations for the same method as mutually exclusive by default. When multiple with() constraints can match the same invocation, only the first configured expectation is verified, causing test failures.

Callback Function Solution

Using returnCallback() provides the most flexible parameterized mocking approach. By dynamically determining return values based on input parameters within the callback function, precise control over behaviors corresponding to different parameters is achieved.

<?php
class DB {
    public function Query($sSql) {
        return "";
    }
}

class DatabaseTest extends PHPUnit\Framework\TestCase {
    public function testQueryWithDifferentParameters() {
        $mock = $this->createMock(DB::class);
        
        $mock->method('Query')
            ->willReturnCallback(function($query) {
                switch($query) {
                    case 'select * from users':
                        return ['fred', 'wilma', 'barney'];
                    case 'select * from roles':
                        return ['admin', 'user'];
                    default:
                        return [];
                }
            });
        
        $this->assertEquals(['fred', 'wilma', 'barney'], 
                          $mock->Query("select * from users"));
        $this->assertEquals(['admin', 'user'], 
                          $mock->Query("select * from roles"));
    }
}

This approach offers clear logic and easy maintenance, particularly suitable for scenarios with complex mappings between parameters and return values. Callback functions can contain arbitrary logic, even throwing exceptions or executing other side effects based on parameter values.

Invocation Order Matcher at()

The at() matcher implements parameterized mocking by specifying sequential indices of method invocations. Each expectation is configured with a distinct at() call, ensuring matching occurs in the expected order.

<?php
class OrderTest extends PHPUnit\Framework\TestCase {
    public function testWithAtMatcher() {
        $mock = $this->createMock(DB::class);
        
        $mock->expects($this->at(0))
            ->method('Query')
            ->with('select * from users')
            ->willReturn(['fred', 'wilma', 'barney']);
            
        $mock->expects($this->at(1))
            ->method('Query')
            ->with('select * from roles')
            ->willReturn(['admin', 'user']);
        
        // Must be called in configured order
        $mock->Query('select * from users');
        $mock->Query('select * from roles');
    }
}

It's important to note that PHPUnit documentation warns that at() can lead to brittle tests, as tests become tightly coupled to specific invocation orders. Any changes in implementation details may break tests, so it should be used cautiously.

withConsecutive() Method

PHPUnit 4.1 introduced the withConsecutive() method specifically designed for handling consecutive calls with different parameters. The method accepts multiple parameter arrays, each corresponding to parameter constraints for one invocation.

<?php
class ConsecutiveTest extends PHPUnit\Framework\TestCase {
    public function testWithConsecutive() {
        $mock = $this->createMock(DB::class);
        
        $mock->expects($this->exactly(2))
            ->method('Query')
            ->withConsecutive(
                [$this->equalTo('select * from users')],
                [$this->equalTo('select * from roles')]
            )
            ->willReturnOnConsecutiveCalls(
                ['fred', 'wilma', 'barney'],
                ['admin', 'user']
            );
        
        $this->assertEquals(['fred', 'wilma', 'barney'], 
                          $mock->Query('select * from users'));
        $this->assertEquals(['admin', 'user'], 
                          $mock->Query('select * from roles'));
    }
}

willReturnOnConsecutiveCalls() works in conjunction with withConsecutive() to provide corresponding return values for each invocation. This combination offers a declarative configuration approach with clear code intent.

Modern Alternatives in PHPUnit 10

PHPUnit 10 removed the withConsecutive() method, recommending willReturnCallback() combined with PHP 8's match expressions for similar functionality.

<?php
class ModernTest extends PHPUnit\Framework\TestCase {
    public function testWithReturnCallbackAndMatch() {
        $mock = $this->createMock(DB::class);
        
        $mock->method('Query')
            ->willReturnCallback(fn(string $query) => match($query) {
                'select * from users' => ['fred', 'wilma', 'barney'],
                'select * from roles' => ['admin', 'user'],
                default => throw new \InvalidArgumentException("Unexpected query: $query")
            });
        
        $this->assertEquals(['fred', 'wilma', 'barney'], 
                          $mock->Query('select * from users'));
        $this->assertEquals(['admin', 'user'], 
                          $mock->Query('select * from roles'));
    }
}

While this modern syntax is less intuitive than withConsecutive(), it provides stronger type safety and more concise expressions. Match expressions ensure all cases are explicitly handled, with default branches capable of throwing exceptions or returning default values.

Solution Comparison and Selection Guidelines

Different solutions have distinct advantages and disadvantages: returnCallback() offers maximum flexibility but may contain complex logic; at() provides clear ordering but creates brittle tests; withConsecutive() is declarative but has been removed; modern match expressions offer type safety but require PHP 8+.

Selection should consider: PHPUnit version compatibility, PHP version constraints, test stability requirements, and code readability needs. For new projects, willReturnCallback() with match expressions is recommended; for maintaining legacy projects, appropriate solutions must be chosen based on existing PHPUnit versions.

Regardless of the chosen approach, clear test documentation should be written to explain parameter-return value mappings, ensuring test maintainability and readability. Parameterized mocking is crucial for improving test coverage and quality, and proper usage can significantly enhance test suite effectiveness.