Closes sebastianbergmann#5175

jrfnl · Feb 27, 2024 · 3efde16 · 3efde16
1 parent 90fb197
commit 3efde16
Show file tree

Hide file tree

Showing 18 changed files with 683 additions and 12 deletions.
diff --git a/ChangeLog-11.1.md b/ChangeLog-11.1.md
@@ -6,6 +6,7 @@ All notable changes of the PHPUnit 11.1 release series are documented in this fi
 
 ### Added
 
+* [#5175](https://github.com/sebastianbergmann/phpunit/issues/5175): `#[CoversMethod]` and `#[UsesMethod]` attributes for more fine-grained code coverage targeting
 * [#5696](https://github.com/sebastianbergmann/phpunit/pull/5696): `#[DisableReturnValueGenerationForTestDoubles]` attribute for disabling return value generation for test doubles created using `createMock()`, `createMockForIntersectionOfInterfaces()`, `createPartialMock()`, `createStub()`, and `createStubForIntersectionOfInterfaces()`
 
 ### Changed

diff --git a/src/Framework/Attributes/CoversMethod.php b/src/Framework/Attributes/CoversMethod.php
@@ -0,0 +1,57 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Framework\Attributes;
+
+use Attribute;
+
+/**
+ * @psalm-immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final readonly class CoversMethod
+{
+    /**
+     * @psalm-var class-string
+     */
+    private string $className;
+
+    /**
+     * @psalm-var non-empty-string
+     */
+    private string $methodName;
+
+    /**
+     * @psalm-param class-string $className
+     * @psalm-param non-empty-string $methodName
+     */
+    public function __construct(string $className, $methodName)
+    {
+        $this->className  = $className;
+        $this->methodName = $methodName;
+    }
+
+    /**
+     * @psalm-return class-string
+     */
+    public function className(): string
+    {
+        return $this->className;
+    }
+
+    /**
+     * @psalm-return non-empty-string
+     */
+    public function methodName(): string
+    {
+        return $this->methodName;
+    }
+}
diff --git a/src/Framework/Attributes/UsesMethod.php b/src/Framework/Attributes/UsesMethod.php
@@ -0,0 +1,57 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Framework\Attributes;
+
+use Attribute;
+
+/**
+ * @psalm-immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
+final readonly class UsesMethod
+{
+    /**
+     * @psalm-var class-string
+     */
+    private string $className;
+
+    /**
+     * @psalm-var non-empty-string
+     */
+    private string $methodName;
+
+    /**
+     * @psalm-param class-string $className
+     * @psalm-param non-empty-string $methodName
+     */
+    public function __construct(string $className, $methodName)
+    {
+        $this->className  = $className;
+        $this->methodName = $methodName;
+    }
+
+    /**
+     * @psalm-return class-string
+     */
+    public function className(): string
+    {
+        return $this->className;
+    }
+
+    /**
+     * @psalm-return non-empty-string
+     */
+    public function methodName(): string
+    {
+        return $this->methodName;
+    }
+}
diff --git a/src/Metadata/Api/CodeCoverage.php b/src/Metadata/Api/CodeCoverage.php
@@ -20,11 +20,13 @@
 use PHPUnit\Metadata\CoversClass;
 use PHPUnit\Metadata\CoversDefaultClass;
 use PHPUnit\Metadata\CoversFunction;
+use PHPUnit\Metadata\CoversMethod;
 use PHPUnit\Metadata\Parser\Registry;
 use PHPUnit\Metadata\Uses;
 use PHPUnit\Metadata\UsesClass;
 use PHPUnit\Metadata\UsesDefaultClass;
 use PHPUnit\Metadata\UsesFunction;
+use PHPUnit\Metadata\UsesMethod;
 use SebastianBergmann\CodeUnit\CodeUnitCollection;
 use SebastianBergmann\CodeUnit\Exception as CodeUnitException;
 use SebastianBergmann\CodeUnit\InvalidCodeUnitException;
@@ -73,13 +75,13 @@ public function linesToBeCovered(string $className, string $methodName): array|f
         $mapper    = new Mapper;
 
         foreach (Registry::parser()->forClassAndMethod($className, $methodName) as $metadata) {
-            if (!$metadata->isCoversClass() && !$metadata->isCoversFunction() && !$metadata->isCovers()) {
+            if (!$metadata->isCoversClass() && !$metadata->isCoversMethod() && !$metadata->isCoversFunction() && !$metadata->isCovers()) {
                 continue;
             }
 
-            assert($metadata instanceof CoversClass || $metadata instanceof CoversFunction || $metadata instanceof Covers);
+            assert($metadata instanceof CoversClass || $metadata instanceof CoversMethod || $metadata instanceof CoversFunction || $metadata instanceof Covers);
 
-            if ($metadata->isCoversClass() || $metadata->isCoversFunction()) {
+            if ($metadata->isCoversClass() || $metadata->isCoversMethod() || $metadata->isCoversFunction()) {
                 $codeUnits = $codeUnits->mergeWith($this->mapToCodeUnits($metadata));
             } elseif ($metadata->isCovers()) {
                 assert($metadata instanceof Covers);
@@ -151,13 +153,13 @@ public function linesToBeUsed(string $className, string $methodName): array
         $mapper    = new Mapper;
 
         foreach (Registry::parser()->forClassAndMethod($className, $methodName) as $metadata) {
-            if (!$metadata->isUsesClass() && !$metadata->isUsesFunction() && !$metadata->isUses()) {
+            if (!$metadata->isUsesClass() && !$metadata->isUsesMethod() && !$metadata->isUsesFunction() && !$metadata->isUses()) {
                 continue;
             }
 
-            assert($metadata instanceof UsesClass || $metadata instanceof UsesFunction || $metadata instanceof Uses);
+            assert($metadata instanceof UsesClass || $metadata instanceof UsesMethod || $metadata instanceof UsesFunction || $metadata instanceof Uses);
 
-            if ($metadata->isUsesClass() || $metadata->isUsesFunction()) {
+            if ($metadata->isUsesClass() || $metadata->isUsesMethod() || $metadata->isUsesFunction()) {
                 $codeUnits = $codeUnits->mergeWith($this->mapToCodeUnits($metadata));
             } elseif ($metadata->isUses()) {
                 assert($metadata instanceof Uses);
@@ -215,7 +217,7 @@ public function shouldCodeCoverageBeCollectedFor(string $className, string $meth
     /**
      * @throws InvalidCoversTargetException
      */
-    private function mapToCodeUnits(CoversClass|CoversFunction|UsesClass|UsesFunction $metadata): CodeUnitCollection
+    private function mapToCodeUnits(CoversClass|CoversFunction|CoversMethod|UsesClass|UsesFunction|UsesMethod $metadata): CodeUnitCollection
     {
         $mapper = new Mapper;
 

diff --git a/src/Metadata/CoversMethod.php b/src/Metadata/CoversMethod.php
@@ -0,0 +1,75 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of PHPUnit.
+ *
+ * (c) Sebastian Bergmann <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+namespace PHPUnit\Metadata;
+
+/**
+ * @psalm-immutable
+ *
+ * @no-named-arguments Parameter names are not covered by the backward compatibility promise for PHPUnit
+ */
+final readonly class CoversMethod extends Metadata
+{
+    /**
+     * @psalm-var class-string
+     */
+    private string $className;
+
+    /**
+     * @psalm-var non-empty-string
+     */
+    private string $methodName;
+
+    /**
+     * @psalm-param 0|1 $level
+     * @psalm-param class-string $className
+     * @psalm-param non-empty-string $methodName
+     */
+    protected function __construct(int $level, string $className, string $methodName)
+    {
+        parent::__construct($level);
+
+        $this->className  = $className;
+        $this->methodName = $methodName;
+    }
+
+    /**
+     * @psalm-assert-if-true CoversMethod $this
+     */
+    public function isCoversMethod(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @psalm-return class-string
+     */
+    public function className(): string
+    {
+        return $this->className;
+    }
+
+    /**
+     * @psalm-return non-empty-string
+     */
+    public function methodName(): string
+    {
+        return $this->methodName;
+    }
+
+    /**
+     * @psalm-return non-empty-string
+     *
+     * @internal This method is not covered by the backward compatibility promise for PHPUnit
+     */
+    public function asStringForCodeUnitMapper(): string
+    {
+        return $this->className . '::' . $this->methodName;
+    }
+}
diff --git a/src/Metadata/Metadata.php b/src/Metadata/Metadata.php
@@ -74,6 +74,15 @@ public static function coversClass(string $className): CoversClass
         return new CoversClass(self::CLASS_LEVEL, $className);
     }
 
+    /**
+     * @psalm-param class-string $className
+     * @psalm-param non-empty-string $methodName
+     */
+    public static function coversMethod(string $className, string $methodName): CoversMethod
+    {
+        return new CoversMethod(self::CLASS_LEVEL, $className, $methodName);
+    }
+
     /**
      * @psalm-param non-empty-string $functionName
      */
@@ -433,6 +442,15 @@ public static function usesFunction(string $functionName): UsesFunction
         return new UsesFunction(self::CLASS_LEVEL, $functionName);
     }
 
+    /**
+     * @psalm-param class-string $className
+     * @psalm-param non-empty-string $methodName
+     */
+    public static function usesMethod(string $className, string $methodName): UsesMethod
+    {
+        return new UsesMethod(self::CLASS_LEVEL, $className, $methodName);
+    }
+
     /**
      * @psalm-param non-empty-string $target
      */
@@ -560,6 +578,14 @@ public function isCoversFunction(): bool
         return false;
     }
 
+    /**
+     * @psalm-assert-if-true CoversMethod $this
+     */
+    public function isCoversMethod(): bool
+    {
+        return false;
+    }
+
     /**
      * @psalm-assert-if-true CoversNothing $this
      */
@@ -818,6 +844,14 @@ public function isUsesFunction(): bool
         return false;
     }
 
+    /**
+     * @psalm-assert-if-true UsesMethod $this
+     */
+    public function isUsesMethod(): bool
+    {
+        return false;
+    }
+
     /**
      * @psalm-assert-if-true WithoutErrorHandler $this
      */

diff --git a/src/Metadata/MetadataCollection.php b/src/Metadata/MetadataCollection.php
@@ -200,6 +200,16 @@ public function isCoversFunction(): self
         );
     }
 
+    public function isCoversMethod(): self
+    {
+        return new self(
+            ...array_filter(
+                $this->metadata,
+                static fn (Metadata $metadata): bool => $metadata->isCoversMethod(),
+            ),
+        );
+    }
+
     public function isExcludeGlobalVariableFromBackup(): self
     {
         return new self(
@@ -533,6 +543,16 @@ public function isUsesFunction(): self
         );
     }
 
+    public function isUsesMethod(): self
+    {
+        return new self(
+            ...array_filter(
+                $this->metadata,
+                static fn (Metadata $metadata): bool => $metadata->isUsesMethod(),
+            ),
+        );
+    }
+
     public function isWithoutErrorHandler(): self
     {
         return new self(