Added optional check for missing @covers annotation when the usage …

…of `@covers` annotations is forced

ChangeLog-3.2.md

@@ -0,0 +1,12 @@
+# Changes in PHP_CodeCoverage 3.2
+
+All notable changes of the PHP_CodeCoverage 3.2 release series are documented in this file using the [Keep a CHANGELOG](http://keepachangelog.com/) principles.
+
+## [3.2.0] - 2016-MM-DD
+
+### Added
+
+* Added optional check for missing `@covers` annotation when the usage of `@covers` annotations is forced
+
+[3.2.0]: https://github.com/sebastianbergmann/php-code-coverage/compare/3.1...3.2.0
+

composer.json

@@ -44,7 +44,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "3.1.x-dev"
+            "dev-master": "3.2.x-dev"
         }
     }
 }

src/CodeCoverage.php

@@ -47,6 +47,11 @@ class PHP_CodeCoverage
      */
     private $checkForUnexecutedCoveredCode = false;
 
+    /**
+     * @var bool
+     */
+    private $checkForMissingCoversAnnotation = false;
+
     /**
      * @var bool
      */
@@ -427,6 +432,23 @@ public function setForceCoversAnnotation($flag)
         $this->forceCoversAnnotation = $flag;
     }
 
+    /**
+     * @param  bool                                      $flag
+     * @throws PHP_CodeCoverage_InvalidArgumentException
+     * @since  Method available since Release 3.2.0
+     */
+    public function setCheckForMissingCoversAnnotation($flag)
+    {
+        if (!is_bool($flag)) {
+            throw PHP_CodeCoverage_InvalidArgumentException::create(
+                1,
+                'boolean'
+            );
+        }
+
+        $this->checkForMissingCoversAnnotation = $flag;
+    }
+
     /**
      * @param  bool                                      $flag
      * @throws PHP_CodeCoverage_InvalidArgumentException
@@ -523,12 +545,17 @@ public function setIgnoreDeprecatedCode($flag)
      * @param  array                                                $data
      * @param  mixed                                                $linesToBeCovered
      * @param  array                                                $linesToBeUsed
+     * @throws PHP_CodeCoverage_MissingCoversAnnotationException
      * @throws PHP_CodeCoverage_UnintentionallyCoveredCodeException
      */
     private function applyCoversAnnotationFilter(array &$data, $linesToBeCovered, array $linesToBeUsed)
     {
         if ($linesToBeCovered === false ||
             ($this->forceCoversAnnotation && empty($linesToBeCovered))) {
+            if ($this->checkForMissingCoversAnnotation) {
+                throw new PHP_CodeCoverage_MissingCoversAnnotationException;
+            }
+
             $data = [];
 
             return;

src/CodeCoverage/Exception/MissingCoversAnnotationException.php

@@ -0,0 +1,18 @@
+<?php
+/*
+ * This file is part of the PHP_CodeCoverage package.
+ *
+ * (c) Sebastian Bergmann <sebastian@phpunit.de>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * Exception that is raised when @covers must be used but is not.
+ *
+ * @since Class available since Release 3.2.0
+ */
+class PHP_CodeCoverage_MissingCoversAnnotationException extends PHP_CodeCoverage_RuntimeException
+{
+}

tests/PHP/CodeCoverageTest.php

@@ -149,6 +149,28 @@ public function testSetForceCoversAnnotationThrowsExceptionForInvalidArgument()
         $this->coverage->setForceCoversAnnotation(null);
     }
 
+    /**
+     * @covers PHP_CodeCoverage::setCheckForMissingCoversAnnotation
+     */
+    public function testSetCheckForMissingCoversAnnotation()
+    {
+        $this->coverage->setCheckForMissingCoversAnnotation(true);
+        $this->assertAttributeEquals(
+            true,
+            'checkForMissingCoversAnnotation',
+            $this->coverage
+        );
+    }
+
+    /**
+     * @covers            PHP_CodeCoverage::setCheckForMissingCoversAnnotation
+     * @expectedException PHP_CodeCoverage_Exception
+     */
+    public function testSetCheckForMissingCoversAnnotationThrowsExceptionForInvalidArgument()
+    {
+        $this->coverage->setCheckForMissingCoversAnnotation(null);
+    }
+
     /**
      * @covers PHP_CodeCoverage::setForceCoversAnnotation
      */