[PHPUnit bridge] Add documentation for the component #6273
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,114 @@ | ||
| .. index:: | ||
| single: PHPUnitBridge | ||
| single: Components; PHPUnitBridge | ||
|
|
||
| The PHPUnit Bridge Component | ||
| ============================= | ||
|
|
||
| The PHPUnit Bridge component provides utilities to report legacy tests and | ||
| usage of deprecated code. | ||
|
|
||
| It comes with the following features: | ||
|
|
||
| * Forces the application to use the default language locale for output (set the | ||
| locale to ``C``) | ||
|
There was a problem hiding this comment. What about changing this to: "Forces the tests to use a consistent locale ( |
||
| * Auto-register ``class_exists`` to load Doctrine annotations (when used) | ||
| * It displays the whole list of deprecated features used in the application | ||
| * Display the stack trace of a deprecation on-demand. | ||
|
|
||
|
|
||
| Installation | ||
| ------------ | ||
|
|
||
| You can install the component in 2 different ways: | ||
|
|
||
| * :doc:`Install it via Composer </components/using_components>` | ||
| (``symfony/phpunit-bridge`` on `Packagist`_); as a dev dependency | ||
| * Use the official Git repository (https://github.com/symfony/phpunit-bridge) | ||
|
|
||
| .. include:: /components/require_autoload.rst.inc | ||
|
|
||
| Usage | ||
| ----- | ||
|
|
||
| Once the component installed, it automatically registers a | ||
|
There was a problem hiding this comment. Let's simplify this: by this: |
||
| `PHPUnit event listener`_ which in turn registers a `PHP error handler`_ | ||
| called ``DeprecationErrorHandler``. After running your PHPUnit tests again, you | ||
|
There was a problem hiding this comment. I think we can remove "again" here |
||
| will get a report similar to this one: | ||
|
|
||
| .. image:: /images/components/phpunit_bridge/report.png | ||
|
|
||
| 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 | ||
|
There was a problem hiding this comment. let's make this a definition list: **Unsilenced**
Reports deprecation notices that were triggered without
the recommended ``@``-silencing operator.
**Legacy**
Shows the number of deprecation notices triggered in
legacy tests.
**Remaining/Other**
Lists all deprecation 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: | ||
|
|
||
| * Make its class start with the ``Legacy`` prefix | ||
| * Make its method start with ``testLegacy`` | ||
| * Make its data provider start with ``provideLegacy`` or ``getLegacy`` | ||
| * Add the ``@group legacy`` annotation to its class or method | ||
|
There was a problem hiding this comment. this is the most recommended way, let's put it as the first item (and maybe add |
||
|
|
||
| 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, encapsed between ``/``. For example, with: | ||
|
|
||
|
|
||
| .. configuration-block:: | ||
|
There was a problem hiding this comment. YOu can remove this directive (it's only used when showing multiple formats of the same config, but PHPunit only supports XML) |
||
|
|
||
| .. code-block:: xml | ||
|
|
||
| <?xml version="1.0" encoding="UTF-8"?> | ||
|
|
||
| <!-- http://phpunit.de/manual/4.1/en/appendixes.configuration.html --> | ||
|
There was a problem hiding this comment. should be the very first line in the code block |
||
| <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
| xsi:noNamespaceSchemaLocation="http://schema.phpunit.de/4.1/phpunit.xsd" | ||
| backupGlobals="false" | ||
| colors="true" | ||
| bootstrap="app/autoload.php" | ||
|
There was a problem hiding this comment. these attributes can also be removed |
||
| > | ||
| <!-- ... --> | ||
|
|
||
| <php> | ||
| <server name="KERNEL_DIR" value="app/" /> | ||
| <env name="SYMFONY_DEPRECATIONS_HELPER" value="/foobar/" /> | ||
|
There was a problem hiding this comment. let's only show the PHP tag + env tag. There is no need to show the complete file |
||
| </php> | ||
| </phpunit> | ||
|
|
||
| PHPUnit_ will stop your test suite once a deprecation notice is triggered whose | ||
| message contains the ``"foobar"`` string. | ||
|
|
||
| By default, any non-legacy-tagged or any non-@-silenced deprecation notices will | ||
|
There was a problem hiding this comment. let's put this in a seperate (sub-)section. Making tests pass with deprecation notices is a very common question, so I want the answer to be easily findable on google. |
||
| make tests fail. Alternatively, setting ``SYMFONY_DEPRECATIONS_HELPER`` to the | ||
| value ``"weak"`` will make the bridge ignore any deprecation notices. This is | ||
| useful to projects that must use deprecated interfaces for backward compatibility | ||
|
There was a problem hiding this comment.
|
||
| reasons. | ||
|
|
||
| .. _PHPUnit: https://phpunit.de | ||
| .. _`PHPUnit event listener`: https://phpunit.de/manual/current/en/extending-phpunit.html#extending-phpunit.PHPUnit_Framework_TestListener | ||
| .. _`PHP error handler`: http://php.net/manual/en/book.errorfunc.php | ||
| .. _`environment variable`: https://phpunit.de/manual/current/en/appendixes.configuration.html#appendixes.configuration.php-ini-constants-variables | ||
| .. _Packagist: https://packagist.org/packages/symfony/phpunit-bridge | ||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would omit the component part here and below.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You seem to have forgotten to change this
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ha right, although maybe it would be better to keep it to me more consistent:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Well, this is a bridge and not a component. But we don't have a bridges section on the docs though, so the components section is the best place to put it now.