Skip to content

Commit 869f904

Browse files
theofidrytheofidry
committed
Add doc for the PHPUnit bridge component
1 parent ef7976b commit 869f904

File tree

4 files changed

+192
-0
lines changed

4 files changed

+192
-0
lines changed

‎components/deprecation/index.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
EventDispatcher
2+
===============
3+
4+
.. toctree::
5+
:maxdepth: 2
6+
7+
introduction
8+
container_aware_dispatcher
9+
generic_event
10+
immutable_dispatcher
11+
traceable_dispatcher

‎components/deprecation/traceable_dispatcher.rst

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
.. index::
2+
single: EventDispatcher; Debug
3+
single: EventDispatcher; Traceable
4+
5+
The Traceable Event Dispatcher
6+
==============================
7+
8+
The :class:`Symfony\\Component\\HttpKernel\\Debug\\TraceableEventDispatcher`
9+
is an event dispatcher that wraps any other event dispatcher and can then
10+
be used to determine which event listeners have been called by the dispatcher.
11+
Pass the event dispatcher to be wrapped and an instance of the
12+
:class:`Symfony\\Component\\Stopwatch\\Stopwatch` to its constructor::
13+
14+
use Symfony\Component\HttpKernel\Debug\TraceableEventDispatcher;
15+
use Symfony\Component\Stopwatch\Stopwatch;
16+
17+
// the event dispatcher to debug
18+
$eventDispatcher = ...;
19+
20+
$traceableEventDispatcher = new TraceableEventDispatcher(
21+
$eventDispatcher,
22+
new Stopwatch()
23+
);
24+
25+
Now, the ``TraceableEventDispatcher`` can be used like any other event dispatcher
26+
to register event listeners and dispatch events::
27+
28+
// ...
29+
30+
// register an event listener
31+
$eventListener = ...;
32+
$priority = ...;
33+
$traceableEventDispatcher->addListener(
34+
'event.the_name',
35+
$eventListener,
36+
$priority
37+
);
38+
39+
// dispatch an event
40+
$event = ...;
41+
$traceableEventDispatcher->dispatch('event.the_name', $event);
42+
43+
After your application has been processed, you can use the
44+
:method:`Symfony\\Component\\EventDispatcher\\Debug\\TraceableEventDispatcherInterface::getCalledListeners`
45+
method to retrieve an array of event listeners that have been called in
46+
your application. Similarly, the
47+
:method:`Symfony\\Component\\EventDispatcher\\Debug\\TraceableEventDispatcherInterface::getNotCalledListeners`
48+
method returns an array of event listeners that have not been called::
49+
50+
// ...
51+
52+
$calledListeners = $traceableEventDispatcher->getCalledListeners();
53+
$notCalledListeners = $traceableEventDispatcher->getNotCalledListeners();

‎components/phpunit_bridge.rst

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
The PHPUnit Bridge Component
2+
=============================
3+
4+
The PHPUnit Bridge component provides utilities to report trigerred errors,
5+
legacy tests and usage of deprecated code.
6+
7+
It comes with the following features:
8+
9+
* Enforce a consistent `C` locale (It forces applications to use the default
10+
language for output)
11+
* Auto-register `class_exists` to load Doctrine annotations (when used);
12+
* Print a user deprecation notices summary at the end of the test suite;
13+
* Display the stack trace of a deprecation on-demand.
14+
15+
Installation
16+
------------
17+
18+
You can install the component in 2 different ways:
19+
20+
* :doc:`Install it via Composer </components/using_components>`
21+
(``symfony/phpunit-bridge`` on `Packagist`_); as a dev dependency
22+
* Use the official Git repository (https://github.com/symfony/phpunit-bridge).
23+
24+
.. include:: /components/require_autoload.rst.inc
25+
26+
Usage
27+
-----
28+
29+
Once the component installed, it automatically registers a
30+
`PHPUnit event listener`_. This listener simply registers a `PHP error handler`_
31+
called `DeprecationErrorHandler`. After running your PHPUnit tests again, you
32+
will have a similar report:
33+
34+
.. image:: /images/components/phpunit_bridge/report.png
35+
36+
The summary includes:
37+
38+
* **Unsilenced** reports deprecation notices that were triggered without the
39+
recommended @-silencing operator;
40+
* **Legacy** deprecation notices denote tests that explicitly test some legacy
41+
interfaces.
42+
* **Remaining/Other** deprecation notices are all other (non-legacy) notices,
43+
grouped by message, test class and method.
44+
45+
Trigger deprecation notices
46+
---------------------------
47+
48+
Deprecation notices can be triggered by using:
49+
50+
@trigger_error('Your deprecation message', E_USER_DEPRECATED);
51+
52+
Without the @-silencing operator, users would need to opt-out from deprecation
53+
notices. Silencing by default swaps this behavior and allows users to opt-in
54+
when they are ready to cope with them (by adding a custom error handler like the
55+
one provided by this bridge.) When not silenced, deprecation notices will appear
56+
in the **Unsilenced** section of the deprecation report.
57+
58+
Mark tests as legacy
59+
--------------------
60+
61+
There are four ways to mark a test as legacy:
62+
63+
* Make its class start with the `Legacy` prefix
64+
* Make its method start with `testLegacy`
65+
* Make its data provider start with `provideLegacy` or `getLegacy`
66+
* Add the `@group legacy` annotation to its class or method
67+
68+
Configuration
69+
-------------
70+
71+
In case you need to inspect the stack trace of a particular deprecation
72+
triggered by your unit tests, you can set the `SYMFONY_DEPRECATIONS_HELPER`
73+
`environment variable`_ to a regular expression that matches this deprecation's
74+
message, encapsed between `/`. For example, with:
75+
76+
.. configuration-block::
77+
78+
.. code-block:: xml
79+
80+
<?xml version="1.0" encoding="UTF-8"?>
81+
82+
<!-- http://phpunit.de/manual/4.1/en/appendixes.configuration.html -->
83+
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
84+
xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.1/phpunit.xsd"
85+
backupGlobals="false"
86+
colors="true"
87+
bootstrap="app/autoload.php"
88+
>
89+
<php>
90+
<ini name="error_reporting" value="-1" />
91+
</php>
92+
93+
<testsuites>
94+
<testsuite name="Project Test Suite">
95+
<directory>tests</directory>
96+
</testsuite>
97+
</testsuites>
98+
99+
<php>
100+
<server name="KERNEL_DIR" value="app/" />
101+
<env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/" />
102+
</php>
103+
104+
<filter>
105+
<whitelist>
106+
<directory>src</directory>
107+
<exclude>
108+
<directory>src/*Bundle/Resources</directory>
109+
<directory>src/*/*Bundle/Resources</directory>
110+
<directory>src/*/Bundle/*Bundle/Resources</directory>
111+
</exclude>
112+
</whitelist>
113+
</filter>
114+
</phpunit>
115+
116+
PHPUnit_ will stop your test suite once a deprecation notice is triggered whose
117+
message contains the `"foobar"` string.
118+
119+
By default, any non-legacy-tagged or any non-@-silenced deprecation notices will
120+
make tests fail. Alternatively, setting `SYMFONY_DEPRECATIONS_HELPER` to the
121+
value `"weak"` will make the bridge ignore any deprecation notices. This is
122+
useful to projects that must use deprecated interfaces for backward compatibility
123+
reasons.
124+
125+
.. _PHPUnit: https://phpunit.de
126+
.. _`PHPUnit event listener`: https://phpunit.de/manual/current/en/extending-phpunit.html#extending-phpunit.PHPUnit_Framework_TestListener
127+
.. _`PHP error handler`: http://php.net/manual/en/book.errorfunc.php
128+
.. _`environment variable`: https://phpunit.de/manual/current/en/appendixes.configuration.html#appendixes.configuration.php-ini-constants-variables

‎images/components/phpunit_bridge/report.png

46.6 KB
Loading

0 commit comments

Comments
 (0)