The PHPUnit Bridge
The PHPUnit Bridge¶
The PHPUnit Bridge provides utilities to report legacy tests and usage of deprecated code.
It comes with the following features:
- Forces the tests to use a consistent locale (
class_existsto 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;
New in version 2.7: The PHPUnit Bridge was introduced in Symfony 2.7. It is however possible to install the bridge in any Symfony application (even 2.3).
$ composer require --dev "symfony/phpunit-bridge:*"
Alternatively, you can clone the https://github.com/symfony/phpunit-bridge repository.
If you install this component outside of a Symfony application, you must
vendor/autoload.php file in your code to enable the class
autoloading mechanism provided by Composer. Read
this article for more details.
The PHPUnit bridge is designed to work with all maintained versions of Symfony components, even across different major versions of them. You should always use its very latest stable major version to get the most accurate deprecation report.
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:
$ cd my-project/ $ ./vendor/bin/simple-phpunit
After running your PHPUnit tests, you will get a report similar to this one:
The summary includes:
- Reports deprecation notices that were triggered without the recommended @-silencing operator.
- Deprecation notices denote tests that explicitly test some legacy features.
- Deprecation notices are all other (non-legacy) notices, grouped by message, test class and method.
If you don't want to use the
simple-phpunit script, register the following
PHPUnit event listener in your PHPUnit configuration file to get the same
report about deprecations (which is created by a PHP error handler
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:
@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 legacyannotation to its class or method;
- Make its class name start with the
- Make its method name start with
If your data provider calls code that would usually trigger a deprecation,
you can prefix its name with
getLegacy to silent
these deprecations. If your data provider does not execute deprecated
code, it is not required to choose a special naming just because the
test being fed by the data provider is marked as legacy.
Also be aware that choosing one of the two legacy prefixes will not mark tests as legacy that make use of this data provider. You still have to mark them as legacy tests explicitly.
In case you need to inspect the stack trace of a particular deprecation
triggered by your unit tests, you can set the
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
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
"weak" which will make the bridge ignore any deprecation notices.
This is useful to projects that must use deprecated interfaces for backward
This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.