Merge pull request #492 from danilopolani/feat/covers-attribute

[2.x] Add `covers` attribute

src/Factories/Annotations/CoversNothing.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Factories\Annotations;
+
+use Pest\Factories\Covers\CoversNothing as CoversNothingFactory;
+use Pest\Factories\TestCaseMethodFactory;
+
+/**
+ * @internal
+ */
+final class CoversNothing
+{
+    /**
+     * Adds annotations regarding the "depends" feature.
+     *
+     * @param array<int, string> $annotations
+     *
+     * @return array<int, string>
+     */
+    public function __invoke(TestCaseMethodFactory $method, array $annotations): array
+    {
+        if (($method->covers[0] ?? null) instanceof CoversNothingFactory) {
+            $annotations[] = '@coversNothing';
+        }
+
+        return $annotations;
+    }
+}

src/Factories/Attributes/Attribute.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Factories\Attributes;
+
+/**
+ * @internal
+ */
+abstract class Attribute
+{
+    /**
+     * Determine if the attribute should be placed above the class instead of above the method.
+     *
+     * @var bool
+     */
+    public const ABOVE_CLASS = false;
+}

src/Factories/Attributes/Covers.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Factories\Attributes;
+
+use Pest\Factories\Covers\CoversClass;
+use Pest\Factories\Covers\CoversFunction;
+use Pest\Factories\TestCaseMethodFactory;
+
+/**
+ * @internal
+ */
+final class Covers extends Attribute
+{
+    /**
+     * Determine if the attribute should be placed above the classe instead of above the method.
+     *
+     * @var bool
+     */
+    public const ABOVE_CLASS = true;
+
+    /**
+     * Adds attributes regarding the "covers" feature.
+     *
+     * @param array<int, string> $attributes
+     *
+     * @return array<int, string>
+     */
+    public function __invoke(TestCaseMethodFactory $method, array $attributes): array
+    {
+        foreach ($method->covers as $covering) {
+            if ($covering instanceof CoversClass) {
+                // Prepend a backslash for FQN classes
+                if (str_contains($covering->class, '\\')) {
+                    $covering->class = '\\' . $covering->class;
+                }
+
+                $attributes[] = "#[\PHPUnit\Framework\Attributes\CoversClass({$covering->class}::class)]";
+            } elseif ($covering instanceof CoversFunction) {
+                $attributes[] = "#[\PHPUnit\Framework\Attributes\CoversFunction('{$covering->function}')]";
+            }
+        }
+
+        return $attributes;
+    }
+}

src/Factories/Covers/CoversClass.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Factories\Covers;
+
+/**
+ * @internal
+ */
+final class CoversClass
+{
+    public function __construct(public string $class)
+    {
+    }
+}

src/Factories/Covers/CoversFunction.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Factories\Covers;
+
+/**
+ * @internal
+ */
+final class CoversFunction
+{
+    public function __construct(public string $function)
+    {
+    }
+}

src/Factories/Covers/CoversNothing.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pest\Factories\Covers;
+
+/**
+ * @internal
+ */
+final class CoversNothing
+{
+}

src/Factories/TestCaseFactory.php

@@ -33,6 +33,16 @@ final class TestCaseFactory
     private static array $annotations = [
         Annotations\Depends::class,
         Annotations\Groups::class,
+        Annotations\CoversNothing::class,
+    ];
+
+    /**
+     * The list of attributes.
+     *
+     * @var array<int, class-string<\Pest\Factories\Attributes\Attribute>>
+     */
+    private static array $attributes = [
+        Attributes\Covers::class,
     ];
 
     /**
@@ -141,11 +151,33 @@ final class TestCaseFactory
             $classFQN .= $className;
         }
 
+        $classAvailableAttributes  = array_filter(self::$attributes, fn (string $attribute) => $attribute::ABOVE_CLASS);
+        $methodAvailableAttributes = array_filter(self::$attributes, fn (string $attribute) => !$attribute::ABOVE_CLASS);
+
+        $classAttributes = [];
+
+        foreach ($classAvailableAttributes as $attribute) {
+            $classAttributes = array_reduce(
+                $methods,
+                fn (array $carry, TestCaseMethodFactory $methodFactory) => (new $attribute())->__invoke($methodFactory, $carry),
+                $classAttributes
+            );
+        }
+
         $methodsCode = implode('', array_map(
-            fn (TestCaseMethodFactory $methodFactory) => $methodFactory->buildForEvaluation($classFQN, self::$annotations),
+            fn (TestCaseMethodFactory $methodFactory) => $methodFactory->buildForEvaluation(
+                $classFQN,
+                self::$annotations,
+                $methodAvailableAttributes
+            ),
             $methods
         ));
 
+        $classAttributesCode = implode('', array_map(
+            static fn (string $attribute) => sprintf("\n                    %s", $attribute),
+            array_unique($classAttributes),
+        ));
+
         try {
             eval("
                 namespace $namespace;
@@ -153,6 +185,7 @@ final class TestCaseFactory
                 use Pest\Repositories\DatasetsRepository as __PestDatasets;
                 use Pest\TestSuite as __PestTestSuite;
 
+                $classAttributesCode
                 final class $className extends $baseClass implements $hasPrintableTestCaseClassFQN {
                     $traitsCode
 

src/Factories/TestCaseMethodFactory.php

@@ -47,6 +47,13 @@ final class TestCaseMethodFactory
      */
     public array $groups = [];
 
+    /**
+     * The covered classes and functions, if any.
+     *
+     * @var array<int, \Pest\Factories\Covers\CoversClass|\Pest\Factories\Covers\CoversFunction|\Pest\Factories\Covers\CoversNothing>
+     */
+    public array $covers = [];
+
     /**
      * Creates a new Factory instance.
      */
@@ -107,8 +114,9 @@ final class TestCaseMethodFactory
      * Creates a PHPUnit method as a string ready for evaluation.
      *
      * @param array<int, class-string>                                       $annotationsToUse
+     * @param array<int, class-string<\Pest\Factories\Attributes\Attribute>> $attributesToUse
      */
-    public function buildForEvaluation(string $classFQN, array $annotationsToUse): string
+    public function buildForEvaluation(string $classFQN, array $annotationsToUse, array $attributesToUse): string
     {
         if ($this->description === null) {
             throw ShouldNotHappen::fromMessage('The test description may not be empty.');
@@ -122,12 +130,18 @@ final class TestCaseMethodFactory
 
         $datasetsCode = '';
         $annotations  = ['@test'];
+        $attributes   = [];
 
         foreach ($annotationsToUse as $annotation) {
             /** @phpstan-ignore-next-line */
             $annotations = (new $annotation())->__invoke($this, $annotations);
         }
 
+        foreach ($attributesToUse as $attribute) {
+            /** @phpstan-ignore-next-line */
+            $attributes = (new $attribute())->__invoke($this, $attributes);
+        }
+
         if (count($this->datasets) > 0) {
             $dataProviderName = $methodName . '_dataset';
             $annotations[]    = "@dataProvider $dataProviderName";
@@ -138,10 +152,15 @@ final class TestCaseMethodFactory
             static fn ($annotation) => sprintf("\n                 * %s", $annotation), $annotations,
         ));
 
+        $attributes = implode('', array_map(
+            static fn ($attribute) => sprintf("\n        %s", $attribute), $attributes,
+        ));
+
         return <<<EOF
 
                 /**$annotations
                  */
+                $attributes
                 public function $methodName()
                 {
                     return \$this->__runTest(

src/PendingCalls/TestCall.php

@@ -5,6 +5,10 @@ declare(strict_types=1);
 namespace Pest\PendingCalls;
 
 use Closure;
+use InvalidArgumentException;
+use Pest\Factories\Covers\CoversClass;
+use Pest\Factories\Covers\CoversFunction;
+use Pest\Factories\Covers\CoversNothing;
 use Pest\Factories\TestCaseMethodFactory;
 use Pest\Support\Backtrace;
 use Pest\Support\HigherOrderCallables;
@@ -168,6 +172,63 @@ final class TestCall
         return $this;
     }
 
+    /**
+     * Sets the covered classes or methods.
+     */
+    public function covers(string ...$classesOrFunctions): TestCall
+    {
+        foreach ($classesOrFunctions as $classOrFunction) {
+            $isClass  = class_exists($classOrFunction);
+            $isMethod = function_exists($classOrFunction);
+
+            if (!$isClass && !$isMethod) {
+                throw new InvalidArgumentException(sprintf('No class or method named "%s" has been found.', $classOrFunction));
+            }
+
+            if ($isClass) {
+                $this->coversClass($classOrFunction);
+            } else {
+                $this->coversFunction($classOrFunction);
+            }
+        }
+
+        return $this;
+    }
+
+    /**
+     * Sets the covered classes.
+     */
+    public function coversClass(string ...$classes): TestCall
+    {
+        foreach ($classes as $class) {
+            $this->testCaseMethod->covers[] = new CoversClass($class);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Sets the covered functions.
+     */
+    public function coversFunction(string ...$functions): TestCall
+    {
+        foreach ($functions as $function) {
+            $this->testCaseMethod->covers[] = new CoversFunction($function);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Sets that the current test covers nothing.
+     */
+    public function coversNothing(): TestCall
+    {
+        $this->testCaseMethod->covers = [new CoversNothing()];
+
+        return $this;
+    }
+
     /**
      * Saves the property accessors to be used on the target.
      */

tests/Features/Covers.php

@@ -0,0 +1,78 @@
+<?php
+
+use Pest\Factories\Attributes\Covers;
+use Pest\PendingCalls\TestCall;
+use Pest\TestSuite;
+
+$runCounter = 0;
+
+class TestCoversClass1
+{
+}
+class TestCoversClass2
+{
+}
+
+class TestCoversClass3
+{
+}
+
+function testCoversFunction()
+{
+}
+
+it('uses the correct PHPUnit attribute for class', function () {
+    $attributes = (new ReflectionClass($this))->getAttributes();
+
+    expect($attributes[0]->getName())->toBe('PHPUnit\Framework\Attributes\CoversClass');
+    expect($attributes[0]->getArguments()[0])->toBe('P\Tests\Features\TestCoversClass1');
+})->coversClass(TestCoversClass1::class);
+
+it('uses the correct PHPUnit attribute for function', function () {
+    $attributes = (new ReflectionClass($this))->getAttributes();
+
+    expect($attributes[1]->getName())->toBe('PHPUnit\Framework\Attributes\CoversFunction');
+    expect($attributes[1]->getArguments()[0])->toBe('foo');
+})->coversFunction('foo');
+
+it('removes duplicated attributes', function () {
+    $attributes = (new ReflectionClass($this))->getAttributes();
+
+    expect($attributes[2]->getName())->toBe('PHPUnit\Framework\Attributes\CoversClass');
+    expect($attributes[2]->getArguments()[0])->toBe('P\Tests\Features\TestCoversClass2');
+    expect($attributes[3]->getName())->toBe('PHPUnit\Framework\Attributes\CoversClass');
+    expect($attributes[3]->getArguments()[0])->toBe('Pest\Factories\Attributes\Covers');
+    expect($attributes[4]->getName())->toBe('PHPUnit\Framework\Attributes\CoversFunction');
+    expect($attributes[4]->getArguments()[0])->toBe('bar');
+    expect($attributes[5]->getName())->toBe('PHPUnit\Framework\Attributes\CoversFunction');
+    expect($attributes[5]->getArguments()[0])->toBe('baz');
+})
+    ->coversClass(TestCoversClass2::class, TestCoversClass1::class, Covers::class)
+    ->coversFunction('bar', 'foo', 'baz');
+
+it('guesses if the given argument is a class or function', function () {
+    $attributes = (new ReflectionClass($this))->getAttributes();
+
+    expect($attributes[6]->getName())->toBe('PHPUnit\Framework\Attributes\CoversClass');
+    expect($attributes[6]->getArguments()[0])->toBe('P\Tests\Features\TestCoversClass3');
+    expect($attributes[7]->getName())->toBe('PHPUnit\Framework\Attributes\CoversFunction');
+    expect($attributes[7]->getArguments()[0])->toBe('testCoversFunction');
+})->covers(TestCoversClass3::class, 'testCoversFunction');
+
+it('appends CoversNothing to method attributes', function () {
+    $phpDoc = (new ReflectionClass($this))->getMethod($this->getName());
+
+    expect(str_contains($phpDoc->getDocComment(), '* @coversNothing'))->toBeTrue();
+})->coversNothing();
+
+it('does not append CoversNothing to other methods', function () {
+    $phpDoc = (new ReflectionClass($this))->getMethod($this->getName());
+
+    expect(str_contains($phpDoc->getDocComment(), '* @coversNothing'))->toBeFalse();
+});
+
+it('throws exception if no class nor method has been found', function () {
+    $testCall = new TestCall(TestSuite::getInstance(), 'filename', 'description', fn () => 'closure');
+
+    $testCall->covers('fakeName');
+})->throws(InvalidArgumentException::class, 'No class or method named "fakeName" has been found.');