feature #23149 [PhpUnitBridge] Added a CoverageListener to enhance the code coverage report (lyrixx)

This PR was squashed before being merged into the 3.4 branch (closes #23149).

Discussion
----------

[PhpUnitBridge] Added a CoverageListener to enhance the code coverage report

| Q             | A
| ------------- | ---
| Branch?       | 3.4
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | -
| License       | MIT
| Doc PR        | https://github.com/symfony/symfony-docs/pull/8416

---

The code coverage computed by PHPUnit is not very accurate by default as it marks a line as tested as soon as it has been executed.
For example, if you have two classes A and B where A is using B and you write test only for the class A then the class B will be marked as tested.

You can fix this issue by adding `@covers A` on top of the class ATest, but it's a bit boring.

This Listener add this annotation on each test if it's applicable:
* If an annotation already exists, we do nothing.
* We try to find the SUT thanks to the Test class name, if it does not exist, we do nothing

---

If you wan to see it in action: https://github.com/lyrixx/phpunit-auto-cover

---

The PR is not finished, I think we could add this listener to symfony itself.

What do you think?

Commits
-------

e17206debd [PhpUnitBridge] Added a CoverageListener to enhance the code coverage report

src/Symfony/Bridge/PhpUnit/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+3.4.0
+-----
+
+ * added a `CoverageListener` to enhance the code coverage report
+
 3.3.0
 -----
 

src/Symfony/Bridge/PhpUnit/CoverageListener.php

@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\PhpUnit;
+
+use PHPUnit\Framework\BaseTestListener;
+use PHPUnit\Framework\Test;
+use Symfony\Bridge\PhpUnit\Legacy\CoverageListenerTrait;
+
+if (class_exists('PHPUnit_Runner_Version') && version_compare(\PHPUnit_Runner_Version::id(), '6.0.0', '<')) {
+    class_alias('Symfony\Bridge\PhpUnit\Legacy\CoverageListener', 'Symfony\Bridge\PhpUnit\CoverageListener');
+// Using an early return instead of a else does not work when using the PHPUnit
+// phar due to some weird PHP behavior (the class gets defined without executing
+// the code before it and so the definition is not properly conditional)
+} else {
+    /**
+     * CoverageListener adds `@covers <className>` on each test suite when possible
+     * to make the code coverage more accurate.
+     *
+     * @author Grégoire Pineau <lyrixx@lyrixx.info>
+     */
+    class CoverageListener extends BaseTestListener
+    {
+        private $trait;
+
+        public function __construct(callable $sutFqcnResolver = null, $warningOnSutNotFound = false)
+        {
+            $this->trait = new CoverageListenerTrait($sutFqcnResolver, $warningOnSutNotFound);
+        }
+
+        public function startTest(Test $test)
+        {
+            $this->trait->startTest($test);
+        }
+    }
+}

src/Symfony/Bridge/PhpUnit/Legacy/CoverageListener.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\PhpUnit\Legacy;
+
+/**
+ * CoverageListener adds `@covers <className>` on each test suite when possible
+ * to make the code coverage more accurate.
+ *
+ * @author Grégoire Pineau <lyrixx@lyrixx.info>
+ *
+ * @internal
+ */
+class CoverageListener extends \PHPUnit_Framework_BaseTestListener
+{
+    private $trait;
+
+    public function __construct(callable $sutFqcnResolver = null, $warningOnSutNotFound = false)
+    {
+        $this->trait = new CoverageListenerTrait($sutFqcnResolver, $warningOnSutNotFound);
+    }
+
+    public function startTest(\PHPUnit_Framework_Test $test)
+    {
+        $this->trait->startTest($test);
+    }
+}

src/Symfony/Bridge/PhpUnit/Legacy/CoverageListenerTrait.php

@@ -0,0 +1,113 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Bridge\PhpUnit\Legacy;
+
+use PHPUnit\Framework\Test;
+use PHPUnit\Framework\Warning;
+
+/**
+ * PHP 5.3 compatible trait-like shared implementation.
+ *
+ * @author Grégoire Pineau <lyrixx@lyrixx.info>
+ *
+ * @internal
+ */
+class CoverageListenerTrait
+{
+    private $sutFqcnResolver;
+    private $warningOnSutNotFound;
+    private $warnings;
+
+    public function __construct(callable $sutFqcnResolver = null, $warningOnSutNotFound = false)
+    {
+        $this->sutFqcnResolver = $sutFqcnResolver;
+        $this->warningOnSutNotFound = $warningOnSutNotFound;
+        $this->warnings = array();
+    }
+
+    public function startTest($test)
+    {
+        $annotations = $test->getAnnotations();
+
+        $ignoredAnnotations = array('covers', 'coversDefaultClass', 'coversNothing');
+
+        foreach ($ignoredAnnotations as $annotation) {
+            if (isset($annotations['class'][$annotation]) || isset($annotations['method'][$annotation])) {
+                return;
+            }
+        }
+
+        $sutFqcn = $this->findSutFqcn($test);
+        if (!$sutFqcn) {
+            if ($this->warningOnSutNotFound) {
+                $message = 'Could not find the tested class.';
+                // addWarning does not exist on old PHPUnit version
+                if (method_exists($test->getTestResultObject(), 'addWarning') && class_exists(Warning::class)) {
+                    $test->getTestResultObject()->addWarning($test, new Warning($message), 0);
+                } else {
+                    $this->warnings[] = sprintf("%s::%s\n%s", get_class($test), $test->getName(), $message);
+                }
+            }
+
+            return;
+        }
+
+        $testClass = \PHPUnit\Util\Test::class;
+        if (!class_exists($testClass, false)) {
+            $testClass = \PHPUnit_Util_Test::class;
+        }
+
+        $r = new \ReflectionProperty($testClass, 'annotationCache');
+        $r->setAccessible(true);
+
+        $cache = $r->getValue();
+        $cache = array_replace_recursive($cache, array(
+            get_class($test) => array(
+                'covers' => array($sutFqcn),
+            ),
+        ));
+        $r->setValue($testClass, $cache);
+    }
+
+    private function findSutFqcn($test)
+    {
+        if ($this->sutFqcnResolver) {
+            $resolver = $this->sutFqcnResolver;
+
+            return $resolver($test);
+        }
+
+        $class = get_class($test);
+
+        $sutFqcn = str_replace('\\Tests\\', '\\', $class);
+        $sutFqcn = preg_replace('{Test$}', '', $sutFqcn);
+
+        if (!class_exists($sutFqcn)) {
+            return;
+        }
+
+        return $sutFqcn;
+    }
+
+    public function __destruct()
+    {
+        if (!$this->warnings) {
+            return;
+        }
+
+        echo "\n";
+
+        foreach ($this->warnings as $key => $warning) {
+            echo sprintf("%d) %s\n", ++$key, $warning);
+        }
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/CoverageListenerTest.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Symfony\Bridge\PhpUnit\Tests;
+
+use PHPUnit\Framework\TestCase;
+
+class CoverageListenerTest extends TestCase
+{
+    public function test()
+    {
+        if ("\n" !== PHP_EOL) {
+            $this->markTestSkipped('This test cannot be run on Windows.');
+        }
+
+        if (defined('HHVM_VERSION')) {
+            $this->markTestSkipped('This test cannot be run on HHVM.');
+        }
+
+        $dir = __DIR__.'/../Tests/Fixtures/coverage';
+        $php = PHP_BINARY;
+        $phpunit = $_SERVER['argv'][0];
+
+        exec("$php -d zend_extension=xdebug.so $phpunit -c $dir/phpunit-without-listener.xml.dist $dir/tests/ --coverage-text", $output);
+        $output = implode("\n", $output);
+        $this->assertContains('Foo', $output);
+
+        exec("$php -d zend_extension=xdebug.so $phpunit -c $dir/phpunit-with-listener.xml.dist $dir/tests/ --coverage-text", $output);
+        $output = implode("\n", $output);
+        $this->assertNotContains('Foo', $output);
+        $this->assertContains("SutNotFoundTest::test\nCould not find the tested class.", $output);
+        $this->assertNotContains("CoversTest::test\nCould not find the tested class.", $output);
+        $this->assertNotContains("CoversDefaultClassTest::test\nCould not find the tested class.", $output);
+        $this->assertNotContains("CoversNothingTest::test\nCould not find the tested class.", $output);
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/phpunit-with-listener.xml.dist

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<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="tests/bootstrap.php"
+         failOnRisky="true"
+         failOnWarning="true"
+>
+
+    <testsuites>
+        <testsuite name="Fixtures/coverage Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory>src</directory>
+        </whitelist>
+    </filter>
+
+    <listeners>
+        <listener class="Symfony\Bridge\PhpUnit\CoverageListener">
+            <arguments>
+                <null/>
+                <boolean>true</boolean>
+            </arguments>
+        </listener>
+    </listeners>
+</phpunit>

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/phpunit-without-listener.xml.dist

@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<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="tests/bootstrap.php"
+         failOnRisky="true"
+         failOnWarning="true"
+>
+
+    <testsuites>
+        <testsuite name="Fixtures/coverage Test Suite">
+            <directory>tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory>src</directory>
+        </whitelist>
+    </filter>
+</phpunit>

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/src/Bar.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace PhpUnitCoverageTest;
+
+class Bar
+{
+    private $foo;
+
+    public function __construct(Foo $foo)
+    {
+        $this->foo = $foo;
+    }
+
+    public function barZ()
+    {
+        $this->foo->fooZ();
+
+        return 'bar';
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/src/Foo.php

@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace PhpUnitCoverageTest;
+
+class Foo
+{
+    public function fooZ()
+    {
+        return 'foo';
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/tests/BarTest.php

@@ -0,0 +1,29 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace PhpUnitCoverageTest\Tests;
+
+use PHPUnit\Framework\TestCase;
+
+class BarTest extends TestCase
+{
+    public function testBar()
+    {
+        if (!class_exists('PhpUnitCoverageTest\Foo')) {
+            $this->markTestSkipped('This test is not part of the main Symfony test suite. It\'s here to test the CoverageListener.');
+        }
+
+        $foo = new \PhpUnitCoverageTest\Foo();
+        $bar = new \PhpUnitCoverageTest\Bar($foo);
+
+        $this->assertSame('bar', $bar->barZ());
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/tests/CoversDefaultClassTest.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversDefaultClass \DateTime
+ */
+class CoversDefaultClassTest extends TestCase
+{
+    public function test()
+    {
+        $this->assertTrue(true);
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/tests/CoversNothingTest.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @coversNothing
+ */
+class CoversNothingTest extends TestCase
+{
+    public function test()
+    {
+        $this->assertTrue(true);
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/tests/CoversTest.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use PHPUnit\Framework\TestCase;
+
+class CoversTest extends TestCase
+{
+    /**
+     * @covers \DateTime
+     */
+    public function test()
+    {
+        $this->assertTrue(true);
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/tests/SutNotFindTest.php

@@ -0,0 +1,20 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use PHPUnit\Framework\TestCase;
+
+class SutNotFoundTest extends TestCase
+{
+    public function test()
+    {
+        $this->assertTrue(true);
+    }
+}

src/Symfony/Bridge/PhpUnit/Tests/Fixtures/coverage/tests/bootstrap.php

@@ -0,0 +1,19 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require __DIR__.'/../src/Bar.php';
+require __DIR__.'/../src/Foo.php';
+
+require __DIR__.'/../../../../Legacy/CoverageListenerTrait.php';
+if (class_exists('PHPUnit_Runner_Version') && version_compare(\PHPUnit_Runner_Version::id(), '6.0.0', '<')) {
+    require __DIR__.'/../../../../Legacy/CoverageListener.php';
+}
+require __DIR__.'/../../../../CoverageListener.php';