diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index ae5e7b4da33..03b398a59a5 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -6,7 +6,7 @@ The PHPUnit Bridge ================== The PHPUnit Bridge provides utilities to report legacy tests and usage of - deprecated code and a helper for time-sensitive tests. + deprecated code. It comes with the following features: @@ -18,8 +18,6 @@ It comes with the following features: * Displays the stack trace of a deprecation on-demand; -* Provides a ``ClockMock`` helper class for time-sensitive tests. - .. versionadded:: 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). @@ -122,120 +120,6 @@ 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. -Time-sensitive Tests --------------------- - -Use Case -~~~~~~~~ - -If you have this kind of time-related tests:: - - 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 :doc:`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 :class:`Symfony\\Bridge\\PhpUnit\\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 guarenteed to work and is no longer a transient -test:: - - 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. - -Troubleshooting -~~~~~~~~~~~~~~~ - -The ``@group time-sensitive`` works "by convention" and assumes 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 FQCN is ``App\Watch\DummyWatch``. - -If this convention doesn't work for your application, you can also configure -the mocked namespaces in the ``phpunit.xml`` file, as done for example in the -:doc:`HttpKernel Component `: - -.. code-block:: xml - - - - - - - - - - - Symfony\Component\HttpFoundation - - - - - - .. _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 @@ -243,4 +127,3 @@ the mocked namespaces in the ``phpunit.xml`` file, as done for example in the .. _Packagist: https://packagist.org/packages/symfony/phpunit-bridge .. _`@-silencing operator`: http://php.net/manual/en/language.operators.errorcontrol.php .. _`@-silenced`: http://php.net/manual/en/language.operators.errorcontrol.php -.. _`Travis CI`: https://travis-ci.com/