From 81365f387552a826873365539c64ace0353f0102 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9goire=20Pineau?= Date: Fri, 22 Sep 2017 13:08:23 +0200 Subject: [PATCH 1/3] [PHPUnitBridge] Added docs for the CoverageListener --- components/phpunit_bridge.rst | 112 +++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 2 deletions(-) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 137062093ad..aec93dffb06 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -415,7 +415,7 @@ Modified PHPUnit script ----------------------- .. versionadded:: 3.2 - This modified PHPUnit script was introduced in the 3.2 version of + This modified PHPUnit script was introduced in the 3.2 version of this component. This bridge provides a modified version of PHPUnit that you can call by using @@ -448,9 +448,117 @@ If you have installed the bridge through Composer, you can run it by calling e.g .. tip:: - If you still need to use ``prophecy`` (but not ``symfony/yaml``), + If you still need to use ``prophecy`` (but not ``symfony/yaml``), then set the ``SYMFONY_PHPUNIT_REMOVE`` env var to ``symfony/yaml``. + +Code coverage listener +---------------------- + +Use case +~~~~~~~~ + +By default the code coverage is computed with the following rule: If a line of +code is executed then it is marked as covered. And the test who executes a line +of code is therefore marked as "covering the line of code". + +This can be misleading. Considering the following example:: + + class Bar + { + public function barZ() + { + return 'bar'; + } + } + + class Foo + { + private $bar; + + public function __construct(Bar $bar) + { + $this->bar = $bar; + } + + public function fooZ() + { + $this->bar->barZ(); + + return 'bar'; + } + } + + class FooTest extends PHPUnit\Framework\TestCase + { + public function test() + { + $bar = new Bar(); + $foo = new Foo($bar); + + $this->assertSame('bar', $foo->barZ()); + } + } + + +Here the ``FooTest::test`` will execute every lines of code so the code coverage +will be 100%. But the ``Bar`` class is not tested. + +The ``CoverageListener`` aim to fix this behavior by adding the ``@covers`` +annotation on the test class. If an annotation already exist then the listener +do nothing. + +By default the listener try to find the tested class by removing the ``Test`` part +of the classname: ``My\Namespace\Tests\FooTest`` -> ``My\Namespace\Foo``. + + +Installation +~~~~~~~~~~~~ + +Add the following configuration to the ``phpunit.xml.dist`` file + +.. code-block:: xml + + + + + + + + + + + +You can also configure a new System Under Test solver: + + .. code-block:: xml + + + + + My\Namespace\SutSolver::solve + + + + +The ``My\Namespace\SutSolver::solve`` should be a callable and will receive the +current test classname as first argument. + +Finally the listener can add warning when the SUT solver does not find the SUT: + + .. code-block:: xml + + + + + + true + + + + .. _PHPUnit: https://phpunit.de .. _`PHPUnit event listener`: https://phpunit.de/manual/current/en/extending-phpunit.html#extending-phpunit.PHPUnit_Framework_TestListener .. _`PHPUnit's assertStringMatchesFormat()`: https://phpunit.de/manual/current/en/appendixes.assertions.html#appendixes.assertions.assertStringMatchesFormat From e78804b5a6d882ba7423c17d51247a47a3ab6096 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Oct 2017 16:32:19 +0200 Subject: [PATCH 2/3] Minor rewords --- components/phpunit_bridge.rst | 45 ++++++++++++++++++----------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index aec93dffb06..50bca21ff7d 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -451,22 +451,22 @@ If you have installed the bridge through Composer, you can run it by calling e.g If you still need to use ``prophecy`` (but not ``symfony/yaml``), then set the ``SYMFONY_PHPUNIT_REMOVE`` env var to ``symfony/yaml``. - Code coverage listener ---------------------- Use case ~~~~~~~~ -By default the code coverage is computed with the following rule: If a line of -code is executed then it is marked as covered. And the test who executes a line -of code is therefore marked as "covering the line of code". +By default the code coverage is computed with the following rule: if a line of +code is executed, then it is marked as covered. And the test which executes a +line of code is therefore marked as "covering the line of code". This can be +misleading. -This can be misleading. Considering the following example:: +Consider the following example:: class Bar { - public function barZ() + public function barMethod() { return 'bar'; } @@ -481,9 +481,9 @@ This can be misleading. Considering the following example:: $this->bar = $bar; } - public function fooZ() + public function fooMethod() { - $this->bar->barZ(); + $this->bar->barMethod(); return 'bar'; } @@ -496,21 +496,20 @@ This can be misleading. Considering the following example:: $bar = new Bar(); $foo = new Foo($bar); - $this->assertSame('bar', $foo->barZ()); + $this->assertSame('bar', $foo->fooMethod()); } } -Here the ``FooTest::test`` will execute every lines of code so the code coverage -will be 100%. But the ``Bar`` class is not tested. - -The ``CoverageListener`` aim to fix this behavior by adding the ``@covers`` -annotation on the test class. If an annotation already exist then the listener -do nothing. - -By default the listener try to find the tested class by removing the ``Test`` part -of the classname: ``My\Namespace\Tests\FooTest`` -> ``My\Namespace\Foo``. +The ``FooTest::test`` method executes every single line of code of both ``Foo`` +and ``Bar`` classes, but ``Bar`` is not truly tested. The ``CoverageListener`` +aims to fix this behavior by adding the appropriate ``@covers`` annotation on +each test class. +If a test class already defines the ``@covers`` annotation, this listener does +nothing. Otherwise, it tries to find the code related to the test by removing +the ``Test`` part of the classname: ``My\Namespace\Tests\FooTest`` -> +``My\Namespace\Foo``. Installation ~~~~~~~~~~~~ @@ -531,7 +530,8 @@ Add the following configuration to the ``phpunit.xml.dist`` file -You can also configure a new System Under Test solver: +If the logic followed to find the related code is too simple or doesn't work for +your application, you can use your own SUT (System Under Test) solver: .. code-block:: xml @@ -543,10 +543,11 @@ You can also configure a new System Under Test solver: -The ``My\Namespace\SutSolver::solve`` should be a callable and will receive the -current test classname as first argument. +The ``My\Namespace\SutSolver::solve`` can be any PHP callable and receives the +current test classname as its first argument. -Finally the listener can add warning when the SUT solver does not find the SUT: +Finally, the listener can also display warning messages when the SUT solver does +not find the SUT: .. code-block:: xml From c21ab16fd8ba9c0df2c468c4d681f6c5dff730aa Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 Oct 2017 16:33:24 +0200 Subject: [PATCH 3/3] Fixed code indentation --- components/phpunit_bridge.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/phpunit_bridge.rst b/components/phpunit_bridge.rst index 50bca21ff7d..0c868ae1e27 100644 --- a/components/phpunit_bridge.rst +++ b/components/phpunit_bridge.rst @@ -533,7 +533,7 @@ Add the following configuration to the ``phpunit.xml.dist`` file If the logic followed to find the related code is too simple or doesn't work for your application, you can use your own SUT (System Under Test) solver: - .. code-block:: xml +.. code-block:: xml @@ -549,7 +549,7 @@ current test classname as its first argument. Finally, the listener can also display warning messages when the SUT solver does not find the SUT: - .. code-block:: xml +.. code-block:: xml