The PHPUnit Bridge

Installation

1

$ composer require --dev symfony/phpunit-bridge

If you plan to write assertions about deprecations and use the regular PHPUnit script (not the modified PHPUnit script provided by Symfony), you have to register a new test listener called SymfonyTestsListener:

1
2
3
4
5
6
7
8
9
10
11

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
    </listeners>
</phpunit>

Usage

Once the component is installed, a simple-phpunit script is created in the vendor/ directory to run tests. This script wraps the original PHPUnit binary to provide more features:

1
2

$ cd my-project/
$ ./vendor/bin/simple-phpunit

After running your PHPUnit tests, you will get a report similar to this one:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$ ./vendor/bin/simple-phpunit
  PHPUnit by Sebastian Bergmann.

  Configuration read from <your-project>/phpunit.xml.dist
  .................

  Time: 1.77 seconds, Memory: 5.75Mb

  OK (17 tests, 21 assertions)

  Remaining deprecation notices (2)

  getEntityManager is deprecated since Symfony 2.1. Use getManager instead: 2x
    1x in DefaultControllerTest::testPublicUrls from App\Tests\Controller
    1x in BlogControllerTest::testIndex from App\Tests\Controller

The summary includes:

Unsilenced

Reports deprecation notices that were triggered without the recommended @-silencing operator.

Legacy

Deprecation notices denote tests that explicitly test some legacy features.

Remaining/Other

Deprecation notices are all other (non-legacy) notices, grouped by message, test class and method.

1
2
3
4
5

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
</listeners>

Running Tests in Parallel

The modified PHPUnit script allows running tests in parallel by providing a directory containing multiple test suites with their own phpunit.xml.dist.

1
2
3
4
5
6
7

├── tests/
│   ├── Functional/
│   │   ├── ...
│   │   └── phpunit.xml.dist
│   ├── Unit/
│   │   ├── ...
│   │   └── phpunit.xml.dist

1

$ ./vendor/bin/simple-phpunit tests/

The modified PHPUnit script will recursively go through the provided directory, up to a depth of 3 subdirectories or the value specified by the environment variable SYMFONY_PHPUNIT_MAX_DEPTH, looking for phpunit.xml.dist files and then running each suite it finds in parallel, collecting their output and displaying each test suite's results in their own section.

Trigger Deprecation Notices

Deprecation notices can be triggered by using trigger_deprecation from the symfony/deprecation-contracts package:

1
2
3
4
5

// indicates something is deprecated since version 1.3 of vendor-name/packagename
trigger_deprecation('vendor-name/package-name', '1.3', 'Your deprecation message');

// you can also use printf format (all arguments after the message will be used)
trigger_deprecation('...', '1.3', 'Value "%s" is deprecated, use ...  instead.', $value);

Mark Tests as Legacy

There are three ways to mark a test as legacy:

• (Recommended) Add the @group legacy annotation to its class or method;
• Make its class name start with the Legacy prefix;
• Make its method name start with testLegacy*() instead of test*().

Configuration

In case you need to inspect the stack trace of a particular deprecation triggered by your unit tests, you can set the SYMFONY_DEPRECATIONS_HELPER environment variable to a regular expression that matches this deprecation's message, enclosed with /. For example, with:

1
2
3
4
5
6
7
8
9
10
11
12

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <php>
        <server name="KERNEL_CLASS" value="App\Kernel"/>
        <env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/"/>
    </php>
</phpunit>

PHPUnit will stop your test suite once a deprecation notice is triggered whose message contains the "foobar" string.

1
2
3
4
5

# This file contains patterns to be ignored while testing for use of
# deprecated code.

%The "Symfony\\Component\\Validator\\Context\\ExecutionContextInterface::.*\(\)" method is considered internal Used by the validator engine\. (Should not be called by user\W+code\. )?It may change without further notice\. You should not extend it from "[^"]+"\.%
%The "PHPUnit\\Framework\\TestCase::addWarning\(\)" method is considered internal%

1

$ SYMFONY_DEPRECATIONS_HELPER='ignoreFile=./tests/baseline-ignore' ./vendor/bin/simple-phpunit

1

$ SYMFONY_DEPRECATIONS_HELPER='generateBaseline=true&baselineFile=./tests/allowed.json' ./vendor/bin/simple-phpunit

1

$ SYMFONY_DEPRECATIONS_HELPER='baselineFile=./tests/allowed.json' ./vendor/bin/simple-phpunit

1
2
3
4
5
6
7
8
9
10
11
12

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
        <arguments>
            <array>
                <!-- set this option to 0 to disable the DebugClassLoader integration -->
                <element key="debug-class-loader"><integer>0</integer></element>
            </array>
        </arguments>
    </listener>
</listeners>

1

$ php bin/console debug:container --deprecations

1
2

# .env.test
SYMFONY_PHPUNIT_LOCALE="fr_FR"

1
2
3
4
5
6
7
8
9
10
11
12

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <php>
        <!-- ... -->
        <env name="SYMFONY_PHPUNIT_LOCALE" value="fr_FR"/>
    </php>
</phpunit>

Write Assertions about Deprecations

When adding deprecations to your code, you might like writing tests that verify that they are triggered as required. To do so, the bridge provides the expectDeprecation() method that you can use on your test methods. It requires you to pass the expected message, given in the same format as for the PHPUnit's assertStringMatchesFormat() method. If you expect more than one deprecation message for a given test method, you can use the method several times (order matters):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

use PHPUnit\Framework\TestCase;
use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;

class MyTest extends TestCase
{
    use ExpectDeprecationTrait;

    /**
     * @group legacy
     */
    public function testDeprecatedCode(): void
    {
        // test some code that triggers the following deprecation:
        // trigger_deprecation('vendor-name/package-name', '5.1', 'This "Foo" method is deprecated.');
        $this->expectDeprecation('Since vendor-name/package-name 5.1: This "%s" method is deprecated');

        // ...

        // test some code that triggers the following deprecation:
        // trigger_deprecation('vendor-name/package-name', '4.4', 'The second argument of the "Bar" method is deprecated.');
        $this->expectDeprecation('Since vendor-name/package-name 4.4: The second argument of the "%s" method is deprecated.');
    }
}

Display the Full Stack Trace

By default, the PHPUnit Bridge displays only deprecation messages. To show the full stack trace related to a deprecation, set the value of SYMFONY_DEPRECATIONS_HELPER to a regular expression matching the deprecation message.

For example, if the following deprecation notice is thrown:

1
2

1x: Doctrine\Common\ClassLoader is deprecated.
  1x in EntityTypeTest::setUp from Symfony\Bridge\Doctrine\Tests\Form\Type

Running the following command will display the full stack trace:

1

$ SYMFONY_DEPRECATIONS_HELPER='/Doctrine\\Common\\ClassLoader is deprecated\./' ./vendor/bin/simple-phpunit

Testing with Multiple PHPUnit Versions

When testing a library that has to be compatible with several versions of PHP, the test suite cannot use the latest versions of PHPUnit because:

• PHPUnit 8 deprecated several methods in favor of other methods which are not available in older versions (e.g. PHPUnit 4);
• PHPUnit 8 added the void return type to the setUp() method, which is not compatible with PHP 5.5;
• PHPUnit switched to namespaced classes starting from PHPUnit 6, so tests must work with and without namespaces.

Time-sensitive Tests

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

use PHPUnit\Framework\TestCase;
use Symfony\Component\Stopwatch\Stopwatch;

class MyTest extends TestCase
{
    public function testSomething(): void
    {
        $stopwatch = new Stopwatch();

        $stopwatch->start('event_name');
        sleep(10);
        $duration = $stopwatch->stop('event_name')->getDuration();

        $this->assertEquals(10000, $duration);
    }
}

1
2
3
4
5

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="\Symfony\Bridge\PhpUnit\SymfonyTestsListener"/>
</listeners>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use PHPUnit\Framework\TestCase;
use Symfony\Component\Stopwatch\Stopwatch;

/**
 * @group time-sensitive
 */
class MyTest extends TestCase
{
    public function testSomething(): void
    {
        $stopwatch = new Stopwatch();

        $stopwatch->start('event_name');
        sleep(10);
        $duration = $stopwatch->stop('event_name')->getDuration();

        $this->assertEquals(10000, $duration);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// the class that uses the time() function to be mocked
namespace App;

class MyClass
{
    public function getTimeInHours(): void
    {
        return time() / 3600;
    }
}

// the test that mocks the external time() function explicitly
namespace App\Tests;

use App\MyClass;
use PHPUnit\Framework\TestCase;
use Symfony\Bridge\PhpUnit\ClockMock;

/**
 * @group time-sensitive
 */
class MyTest extends TestCase
{
    public function testGetTimeInHours(): void
    {
        ClockMock::register(MyClass::class);

        $my = new MyClass();
        $result = $my->getTimeInHours();

        $this->assertEquals(time() / 3600, $result);
    }
}

DNS-sensitive Tests

Tests that make network connections, for example to check the validity of a DNS record, can be slow to execute and unreliable due to the conditions of the network. For that reason, this component also provides mocks for these PHP functions:

• checkdnsrr
• dns_check_record
• getmxrr
• dns_get_mx
• gethostbyaddr
• gethostbyname
• gethostbynamel
• dns_get_record

1
2
3
4
5
6
7
8
9
10
11
12
13

use App\Validator\DomainValidator;
use PHPUnit\Framework\TestCase;

class MyTest extends TestCase
{
    public function testEmail(): void
    {
        $validator = new DomainValidator(['checkDnsRecord' => true]);
        $isValid = $validator->validate('example.com');

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

use App\Validator\DomainValidator;
use PHPUnit\Framework\TestCase;
use Symfony\Bridge\PhpUnit\DnsMock;

/**
 * @group dns-sensitive
 */
class DomainValidatorTest extends TestCase
{
    public function testEmails(): void
    {
        DnsMock::withMockedHosts([
            'example.com' => [['type' => 'A', 'ip' => '1.2.3.4']],
        ]);

        $validator = new DomainValidator(['checkDnsRecord' => true]);
        $isValid = $validator->validate('example.com');

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12

DnsMock::withMockedHosts([
    'example.com' => [
        [
            'type' => 'A',
            'ip' => '1.2.3.4',
        ],
        [
            'type' => 'AAAA',
            'ipv6' => '::12',
        ],
    ],
]);

Class Existence Based Tests

Tests that behave differently depending on existing classes, for example Composer's development dependencies, are often hard to test for the alternate case. For that reason, this component also provides mocks for these PHP functions:

• class_exists
• interface_exists
• trait_exists
• enum_exists

1
2
3
4
5
6
7
8
9
10
11
12
13

use Vendor\DependencyClass;

class MyClass
{
    public function hello(): string
    {
        if (class_exists(DependencyClass::class)) {
            return 'The dependency behavior.';
        }

        return 'The default behavior.';
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13

use MyClass;
use PHPUnit\Framework\TestCase;

class MyClassTest extends TestCase
{
    public function testHello(): void
    {
        $class = new MyClass();
        $result = $class->hello(); // "The dependency behavior."

        // ...
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

use MyClass;
use PHPUnit\Framework\TestCase;
use Vendor\DependencyClass;

class MyClassTest extends TestCase
{
    // ...

    public function testHelloDefault(): void
    {
        ClassExistsMock::register(MyClass::class);
        ClassExistsMock::withMockedClasses([DependencyClass::class => false]);

        $class = new MyClass();
        $result = $class->hello(); // "The default behavior."

        // ...
    }
}

Troubleshooting

The @group time-sensitive and @group dns-sensitive annotations work "by convention" and assume that the namespace of the tested class can be obtained just by removing the Tests\ part from the test namespace. I.e. if your test cases fully-qualified class name (FQCN) is App\Tests\Watch\DummyWatchTest, it assumes the tested class namespace is App\Watch.

If this convention doesn't work for your application, configure the mocked namespaces in the phpunit.xml file, as done for example in the HttpKernel Component:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<!-- https://phpunit.de/manual/4.1/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/4.1/phpunit.xsd"
>

    <!-- ... -->

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
            <arguments>
                <array>
                    <element key="time-sensitive"><string>Symfony\Component\HttpFoundation</string></element>
                </array>
            </arguments>
        </listener>
    </listeners>
</phpunit>

Under the hood, a PHPUnit listener injects the mocked functions in the tested classes' namespace. In order to work as expected, the listener has to run before the tested class ever runs.

By default, the mocked functions are created when the annotation are found and the corresponding tests are run. Depending on how your tests are constructed, this might be too late.

You can either:

• Declare the namespaces of the tested classes in your phpunit.xml.dist;
• Register the namespaces at the end of the config/bootstrap.php file.

1
2
3
4
5
6
7
8
9
10
11

<!-- phpunit.xml.dist -->
<!-- ... -->
<listeners>
    <listener class="Symfony\Bridge\PhpUnit\SymfonyTestsListener">
            <arguments>
                <array>
                    <element key="time-sensitive"><string>Acme\MyClassTest</string></element>
                </array>
            </arguments>
        </listener>
</listeners>

1
2
3
4
5
6
7

// config/bootstrap.php
use Symfony\Bridge\PhpUnit\ClockMock;

// ...
if ('test' === $_SERVER['APP_ENV']) {
    ClockMock::register('Acme\\MyClassTest\\');
}

Modified PHPUnit script

This bridge provides a modified version of PHPUnit that you can call by using its bin/simple-phpunit command. It has the following features:

• Works with a standalone vendor directory that doesn't conflict with yours;
• Does not embed prophecy to prevent any conflicts with its dependencies;
• Collects and replays skipped tests when the SYMFONY_PHPUNIT_SKIPPED_TESTS env var is defined: the env var should specify a file name that will be used for storing skipped tests on a first run, and replay them on the second run;
• Parallelizes test suites execution when given a directory as argument, scanning this directory for phpunit.xml.dist files up to SYMFONY_PHPUNIT_MAX_DEPTH levels (specified as an env var, defaults to 3);

The script writes the modified PHPUnit it builds in a directory that can be configured by the SYMFONY_PHPUNIT_DIR env var, or in the same directory as the simple-phpunit if it is not provided. It's also possible to set this env var in the phpunit.xml.dist file.

If you have installed the bridge through Composer, you can run it by calling e.g.:

1

$ vendor/bin/simple-phpunit

1
2
3
4
5

<!-- phpunit.xml.dist -->
<!-- ... -->
<php>
    <env name="SYMFONY_PHPUNIT_REQUIRE" value="vendor/name:^1.2 vendor/name2:^3"/>
</php>

Code Coverage Listener

By default, the code coverage is computed with the following rule: if a line of code is executed, then it is marked as covered. The test which executes a line of code is therefore marked as "covering the line of code". This can be misleading.

Consider the following example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

class Bar
{
    public function barMethod(): string
    {
        return 'bar';
    }
}

class Foo
{
    public function __construct(
        private Bar $bar,
    ) {
    }

    public function fooMethod(): string
    {
        $this->bar->barMethod();

        return 'bar';
    }
}

class FooTest extends PHPUnit\Framework\TestCase
{
    public function test(): void
    {
        $bar = new Bar();
        $foo = new Foo($bar);

        $this->assertSame('bar', $foo->fooMethod());
    }
}

The FooTest::test method executes every single line of code of both Foo and Bar classes, but Bar is not truly tested. The CoverageListener aims to fix this behavior by adding the appropriate @covers annotation on each test class.

If a test class already defines the @covers annotation, this listener does nothing. Otherwise, it tries to find the code related to the test by removing the Test part of the classname: My\Namespace\Tests\FooTest -> My\Namespace\Foo.

1
2
3
4
5
6
7
8
9
10
11

<!-- https://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/6.0/phpunit.xsd"
>

    <!-- ... -->

    <listeners>
        <listener class="Symfony\Bridge\PhpUnit\CoverageListener"/>
    </listeners>
</phpunit>

1
2
3
4
5
6
7

<listeners>
    <listener class="Symfony\Bridge\PhpUnit\CoverageListener">
        <arguments>
            <string>My\Namespace\SutSolver::solve</string>
        </arguments>
    </listener>
</listeners>

1
2
3
4
5
6
7
8

<listeners>
    <listener class="Symfony\Bridge\PhpUnit\CoverageListener">
        <arguments>
            <null/>
            <boolean>true</boolean>
        </arguments>
    </listener>
</listeners>