Installation

You can install the component in 2 different ways:

• Install it via Composer (symfony/phpunit-bridge on Packagist); as a dev dependency;
• Use the official Git repository (https://github.com/symfony/phpunit-bridge).

Then, require the vendor/autoload.php file to enable the autoloading mechanism provided by Composer. Otherwise, your application won't be able to find the classes of this Symfony component.

If you plan to The PHPUnit Bridge 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

<!-- http://phpunit.de/manual/6.0/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://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:

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>

Trigger Deprecation Notices

Deprecation notices can be triggered by using:

1

@trigger_error('Your deprecation message', E_USER_DEPRECATED);

Without the @-silencing operator, users would need to opt-out from deprecation notices. Silencing by default swaps this behavior and allows users to opt-in when they are ready to cope with them (by adding a custom error handler like the one provided by this bridge). When not silenced, deprecation notices will appear in the Unsilenced section of the deprecation report.

Mark Tests as Legacy

There are four 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*();
• Make its data provider start with provideLegacy*() or getLegacy*().

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

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

    <!-- ... -->

    <php>
        <server name="KERNEL_DIR" value="app/" />
        <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.

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 @expectedDeprecation annotation 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 annotation several times (order matters):

1
2
3
4
5
6
7
8
9
10

/**
 * @group legacy
 * @expectedDeprecation This "%s" method is deprecated.
 * @expectedDeprecation The second argument of the "%s" method is deprecated.
 */
public function testDeprecatedCode()
{
    @trigger_error('This "Foo" method is deprecated.', E_USER_DEPRECATED);
    @trigger_error('The second argument of the "Bar" method is deprecated.', E_USER_DEPRECATED);
}

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()
    {
        $stopwatch = new Stopwatch();

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

        $this->assertEquals(10, $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()
    {
        $stopwatch = new Stopwatch();

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

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

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
14

use PHPUnit\Framework\TestCase;
use Symfony\Component\Validator\Constraints\Email;

class MyTest extends TestCase
{
    public function testEmail()
    {
        $validator = ...
        $constraint = new Email(array('checkMX' => true));

        $result = $validator->validate('foo@example.com', $constraint);

        // ...
}

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\Validator\Constraints\Email;

/**
 * @group dns-sensitive
 */
class MyTest extends TestCase
{
    public function testEmails()
    {
        DnsMock::withMockedHosts(array('example.com' => array(array('type' => 'MX'))));

        $validator = ...
        $constraint = new Email(array('checkMX' => true));

        $result = $validator->validate('foo@example.com', $constraint);

        // ...
}

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

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

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. that if the your test case 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

<!-- http://phpunit.de/manual/4.1/en/appendixes.configuration.html -->
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="http://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>

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:

• Does not embed symfony/yaml nor prophecy to prevent any conflicts with these dependencies;
• Uses PHPUnit 4.8 when run with PHP <=5.5 and PHPUnit 5.3 when run with PHP >=5.6;
• 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.

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

1

$ vendor/bin/simple-phpunit