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.

Usage¶

Once the component installed, it automatically registers a PHPUnit event listener which in turn registers a PHP error handler called DeprecationErrorHandler. 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.

Trigger Deprecation Notices¶

Deprecation notices can be triggered by using:

@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/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"
>

    <!-- ... -->

    <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.

Time-sensitive Tests¶

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

use Symfony\Component\Stopwatch\Stopwatch;

class MyTest extends \PHPUnit_Framework_TestCase
{
    public function testSomething()
    {
        $stopwatch = new Stopwatch();

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

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

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

use Symfony\Component\Stopwatch\Stopwatch;

/**
 * @group time-sensitive
 */
class MyTest extends \PHPUnit_Framework_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

use Symfony\Component\Validator\Constraints\Email;

class MyTest extends \PHPUnit_Framework_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

use Symfony\Component\Validator\Constraints\Email;

/**
 * @group dns-sensitive
 */
class MyTest extends \PHPUnit_Framework_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>