PHP: Should I mock or should I go?

Mocks in short

Mocks aim to test the behavior of real objects.

They simulate dependencies, so you don't have to call external resources that could slow down unit tests significantly.

You can define expectations and verify them.

For example, you may ensure that a method is called a specific number of times and/or with certain parameters:

use PHPUnit\Framework\TestCase;

class MyTest extends TestCase
{
    public function testMockExample(): void
    {
        $depencencyMock = $this->createMock(MyDependency::class);

        $dependencyMock->expects($this->exactly(2))
              ->method('someMethod')
              ->with('some parameter');

        $classToTest = new ClassToTest($dependencyMock);
   }
}

Return values

willReturn() ensures compatibility with return types:

// In code
class MyClass {
    public function getNum(): int {
    }
}

// In tests
$myClassMock = $this->createMock(MyClass::class);
$myClassMock->expects($this->once())
            ->method('getNum')
            ->willReturn(2);

You can also use willReturnCallback if you want to test dynamic behavior based on input parameters.

Bad practices to avoid

As mocks only mimic real behaviors, it's easy to miss the point. Let's discuss common bad practices:

Returning values without expectations

❌ Don't do that:

$colorServiceMock = $this->createMock(ColorService::class);
$colorServiceMock->method('hexToName')
     ->willReturn('red');

$color = (new MyClass($colorServiceMock))->getColorName('ff0000');

✅ Instead, add some expectations:

$colorServiceMock->expects($this->once())
     ->method('hexToName')
     ->with('00f00')
     ->willReturn('green');

$color = (new MyClass($colorServiceMock))->getColorName('00f00');

Remember mocks aim to verify interactions.

Mocking real objects instead of interfaces

Let's test MyClass that implements SomeInterface.

❌ Don't do that:

$myclassMock = $this->createMock(MyClass::class);

✅ Instead, mock the interface:

$myclassMock = $this->createMock(SomeInterface::class);

Mocks focus on behaviors. Interfaces usually don't change, as you're supposed to modify implementations, not contracts.

Overmocking tests

Tomas Votruba explains this problem beautifully: 5 Ways to Extract Value from Overmocked Tests

Using mocks to mask bad design practices

It's easy to ignore a tight coupling between components:

$productRepositoryMock = $this->createMock(ProductRepository::class);
$invoiceRepositoryMock = $this->createMock(InvoiceRepository::class);
$emailServiceMock = $this->createMock(EmailService::class);

$overComplexService = new OverComplexService($productRepositoryMock, $invoiceRepositoryMock, $emailServiceMock);

The above example breaks the separation of concerns, and mocks are perpetuating that bad practice.

Relying on mocks exclusively

Mocks are powerful tools, but unit tests are not sufficient. You need various other types of tests (e.g, integration, e2e).

How to spot bad use of mocks

In addition to the bad practices, there are other signs that could indicate that mocks are misused or overused in the project:

• the tests do not reflect real-world scenarios, overlooking critical issues in production
• there's a tight couple between tests and implementations, resulting in frequent updates of the associated mocks
• the tests are too complex, making them harder to read and maintain

Mocks and stubs

Martin Fowler wrote a fantastic post that explains why Mocks Aren't Stubs.

Let's see concrete situations where you might use them:

When to use mocks

Here are a few test cases where mocks make more sense:

• you need to test how your class interacts with its dependencies
• you need to check complex sequences where a specific method is called multiple times with different parameters

When to use stubs

You can create stubs with PHPUnit quite conveniently:

$myDependencyStub = $this->createStub(MyDependency::class);

Here are a few test cases where stubs make more sense:

• you want to test the output or state of your code without needing to verify interactions
• you need to test some calculations without needing to interact with the actual database

In a nutshell, stubs are not meant to check the behavior of real objects but states.

Fine tuning

The main purpose of unit tests is to ensure each unit/component work as expected, but you will have to maintain those tests in addition to the actual code.

Stubs can simplify test setup and are very efficient for simple scenarios where you don't need to track method calls and interactions.

It can prevent unnecessary complexity by keeping some of your tests focused.

Wrap up

Mocks can track method calls and their parameters.

Don't forget to return values that are representative of real behaviors. Otherwise, you might end up with a false sense of security.

Mocks should be used sparingly to avoid unnecessary complexity for maintenance.

Comments

[david duymelinck]

A nice post!

Don't forget to return values that are representative of real behaviors. Otherwise, you might end up with a false sense of security.

This is why I rather write an integration test where the dependency is instantiated. With mocks you need to check all the individual tests, when the dependency behavior changes. If there are no mocks you can run your testsuite and see the fails.

Of course there are times when I do use mocks:

• When the dependency is a dependency hell on its own
• When instantiating or calling the dependency method required a lot of setup.

I think mocks and stubs always give a false sense of security, because they are an assumption of what the code is going to do.
It is like measuring ingredients of a dish with cups and spoons, instead of weighing.
It is a tool that can help you, but certainly for critical parts of your code you need to be sure.

[spO0q]

The use cases you give make sense. It does simplify test setup, but it can be tricky.

I think the main problem is when mocks are overused.

In those situations, your tests may be misleading and unrealistic.

If I had to teach mocks, I would start with use cases and the "why" to ensure it's used when it's necessary.