Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • SensioLabs Professional services to help you with Symfony
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by
  1. Home
  2. Documentation
  3. Components
  4. The PHPUnit Bridge
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Installation
  • Usage
  • Trigger Deprecation Notices
  • Mark Tests as Legacy
  • Configuration
    • Making Tests Fail
    • Disabling the Deprecation Helper
  • Time-sensitive Tests
    • Use Case
    • Clock Mocking
  • DNS-sensitive Tests
    • Use Case
  • Troubleshooting

The PHPUnit Bridge

Edit this page

Warning: You are browsing the documentation for Symfony 3.1, which is no longer maintained.

Read the updated version of this page for Symfony 6.3 (the current stable version).

The PHPUnit Bridge

The PHPUnit Bridge provides utilities to report legacy tests and usage of deprecated code and a helper for time-sensitive tests.

It comes with the following features:

  • Forces the tests to use a consistent locale (C);
  • Auto-register class_exists to load Doctrine annotations (when used);
  • It displays the whole list of deprecated features used in the application;
  • Displays the stack trace of a deprecation on-demand;
  • Provides a ClockMock helper class for time-sensitive tests.

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:

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

Making Tests Fail

By default, any non-legacy-tagged or any non-`@-silenced`_ deprecation notices will make tests fail. Alternatively, setting SYMFONY_DEPRECATIONS_HELPER to an arbitrary value (ex: 320) will make the tests fails only if a higher number of deprecation notices is reached (0 is the default value). You can also set the value "weak" which will make the bridge ignore any deprecation notices. This is useful to projects that must use deprecated interfaces for backward compatibility reasons.

Disabling the Deprecation Helper

3.1

The ability to disable the deprecation helper was introduced in the 3.1
version of this component.

Set the SYMFONY_DEPRECATIONS_HELPER environment variable to disabled to completely disable the deprecation helper. This is useful to make use of the rest of features provided by this component without getting errors or messages related to deprecations.

Time-sensitive Tests

Use Case

If you have this kind of time-related 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);
    }
}

You used the Symfony Stopwatch Component to calculate the duration time of your process, here 10 seconds. However, depending on the load of the server your the processes running on your local machine, the $duration could for example be `10.000023s` instead of `10s`.

This kind of tests are called transient tests: they are failing randomly depending on spurious and external circumstances. They are often cause trouble when using public continuous integration services like Travis CI.

Clock Mocking

The ClockMock class provided by this bridge allows you to mock the PHP's built-in time functions time(), microtime(), sleep() and usleep().

To use the ClockMock class in your test, you can:

  • (Recommended) Add the @group time-sensitive annotation to its class or method;
  • Register it manually by calling ClockMock::register(__CLASS__) and ClockMock::withClockMock(true) before the test and ClockMock::withClockMock(false) after the test.

As a result, the following is guaranteed to work and is no longer a transient test:

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);
    }
}

And that's all!

Tip

An added bonus of using the ClockMock class is that time passes instantly. Using PHP's sleep(10) will make your test wait for 10 actual seconds (more or less). In contrast, the ClockMock class advances the internal clock the given number of seconds without actually waiting that time, so your test will execute 10 seconds faster.

DNS-sensitive Tests

3.1

The mocks for DNS related functions were introduced in the 3.1 version of this component.

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

Use Case

Consider the following example that uses the checkMX option of the Email constraint to test the validity of the email domain:

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);

        // ...
}

In order to avoid making a real network connection, add the @dns-sensitive annotation to the class and use the DnsMock::withMockedHosts() to configure the data you expect to get for the given hosts:

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);

        // ...
}

The withMockedHosts() method configuration is defined as an array. The keys are the mocked hosts and the values are arrays of DNS records in the same format returned by dns_get_record, so you can simulate diverse network conditions:

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>
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    Version:
    Check Code Performance in Dev, Test, Staging & Production

    Check Code Performance in Dev, Test, Staging & Production

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Symfony footer

    Avatar of Radek Wionczek, a Symfony contributor

    Thanks Radek Wionczek (@rwionczek) for being a Symfony contributor

    1 commit • 10 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony