Make it easy to mock services in a built container

Fund package maintenance!

Installs: 137 977

Dependents: 2

Suggesters: 0

Security: 0

Stars: 43

Watchers: 5

Forks: 7

Open Issues: 1


0.3.1 2022-07-07 05:29 UTC

This package is auto-updated.

Last update: 2024-06-07 09:32:19 UTC


Latest Version Total Downloads

You want your tests to run as quick as possible, so you build your container once and let all your tests run on that built container. That is great!

However, when your service container is built, it is immutable. This causes problems when you want to mock a service during a functional test. There is no way for you to change the object in the service container.

Using this bundle, you can mark some services as "mockable", that will allow you to define a new custom behavior for a method in that service. If no custom behavior is defined, the service works as normal.


composer require --dev happyr/service-mocking

Make sure to enable the bundle for your test environment only:

// config/bundles.php


return [
    // ...
    Happyr\ServiceMocking\HappyrServiceMockingBundle::class => ['test' => true],

Configure services

You need to tell the bundle what services you want to mock. That could be done with the "happyr_service_mock" service tag or by defining a list of service ids:

PHP config (Symfony 5.3)
// config/packages/test/happyr_service_mocking.php

use Symfony\Config\HappyrServiceMockingConfig;

return static function (HappyrServiceMockingConfig $config) {
Yaml config
# config/packages/test/happyr_service_mocking.yaml

        - 'App\AcmeApiClient'
        - 'App\Some\OtherService'


use App\AcmeApiClient;
use App\Some\OtherService;
use Happyr\ServiceMocking\ServiceMock;
use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

class MyTest extends WebTestCase
    public function testFoo()
        // ...

        $apiClient = self::getContainer()->get(AcmeApiClient::class);
        // On Symfony < 5.3
        // $apiClient = self::$container->get(AcmeApiClient::class);

        // For all calls to $apiClient->show()
        ServiceMock::all($apiClient, 'show', function ($id) {
            // $id here is the same that is passed to $apiClient->show('123')
            return ['id'=>$id, 'name'=>'Foobar'];

        // For only the next call to $apiClient->delete()
        ServiceMock::next($apiClient, 'delete', function () {
            return true;

        // This will queue a new callable for $apiClient->delete()
        ServiceMock::next($apiClient, 'delete', function () {
            throw new \InvalidArgument('Item cannot be deleted again');

        $mock = // create a PHPUnit mock or any other mock you want.
        ServiceMock::swap(self::getContainer()->get(OtherService::class), $mock);

        // ...

    protected function tearDown(): void
        // To make sure we don't affect other tests
        // You can include the RestoreServiceContainer trait to automatically reset services


So how is this magic working?

When the container is built a new proxy class is generated from your service definition. The proxy class acts and behaves just as the original. But on each method call it checks the ProxyDefinition if a custom behavior have been added.

With help from static properties, the ProxyDefinition will be remembered even if the Kernel is rebooted.


This trick will not work if you have two different PHP processes, i.e. you are running your tests with Panther, Selenium etc.

We can also not create a proxy if your service is final.

We are only able to mock direct access to a service. Indirect method calls are not mocked. Example:

class MyService {
    public function foo()
        return $this->bar();

    public function bar()
        return 'original';

If we mock MyService::bar() to return "mocked". You will still get "orignal" when you call MyService::foo(). The workaround is to mock MyService::foo() too.