The PHPUnit Bridge

Installation

1

$ composer require --dev "symfony/phpunit-bridge:*"

Alternatively, you can clone the https://github.com/symfony/phpunit-bridge repository.

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

$ phpunit -c app
  PHPUnit by Sebastian Bergmann.

  Configuration read from <your-project>/app/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 AppBundle\Tests\Controller
    1x in BlogControllerTest::testIndex from AppBundle\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>

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

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

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

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(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()
    {
        $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

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

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

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

use App\MyClass;
use PHPUnit\Framework\TestCase;

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

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

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

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>