Merge branch '4.x' into fix/sibling-describe-blocks

src/PendingCalls/DescribeCall.php

@@ -79,7 +79,7 @@ final class DescribeCall
             $this->currentBeforeEachCall->describing[] = $this->description;
         }
 
-        $this->currentBeforeEachCall->{$name}(...$arguments); // @phpstan-ignore-line
+        $this->currentBeforeEachCall->{$name}(...$arguments);
 
         return $this;
     }

src/PendingCalls/TestCall.php

@@ -12,6 +12,7 @@ use Pest\Factories\Attribute;
 use Pest\Factories\TestCaseMethodFactory;
 use Pest\Mutate\Repositories\ConfigurationRepository;
 use Pest\PendingCalls\Concerns\Describable;
+use Pest\Plugins\Environment;
 use Pest\Plugins\Only;
 use Pest\Support\Backtrace;
 use Pest\Support\Container;
@@ -178,10 +179,9 @@ final class TestCall // @phpstan-ignore-line
     }
 
     /**
-     * Runs the current test multiple times with
-     * each item of the given `iterable`.
+     * Runs the current test multiple times with each item of the given `iterable`.
      *
-     * @param  array<\Closure|iterable<int|string, mixed>|string>  $data
+     * @param  Closure|iterable<array-key, mixed>|string  $data
      */
     public function with(Closure|iterable|string ...$data): self
     {
@@ -224,7 +224,7 @@ final class TestCall // @phpstan-ignore-line
      */
     public function only(): self
     {
-        Only::enable($this, ...func_get_args()); // @phpstan-ignore-line
+        Only::enable($this, ...func_get_args());
 
         return $this;
     }
@@ -315,6 +315,61 @@ final class TestCall // @phpstan-ignore-line
             : $this;
     }
 
+    /**
+     * Weather the current test is running on a CI environment.
+     */
+    private function runningOnCI(): bool
+    {
+        foreach ([
+            'CI',
+            'GITHUB_ACTIONS',
+            'GITLAB_CI',
+            'CIRCLECI',
+            'TRAVIS',
+            'APPVEYOR',
+            'BITBUCKET_BUILD_NUMBER',
+            'BUILDKITE',
+            'TEAMCITY_VERSION',
+            'JENKINS_URL',
+            'SYSTEM_COLLECTIONURI',
+            'CI_NAME',
+            'TASKCLUSTER_ROOT_URL',
+            'DRONE',
+            'WERCKER',
+            'NEVERCODE',
+            'SEMAPHORE',
+            'NETLIFY',
+            'NOW_BUILDER',
+        ] as $env) {
+            if (getenv($env) !== false) {
+                return true;
+            }
+        }
+
+        return Environment::name() === Environment::CI;
+    }
+
+    /**
+     * Skips the current test when running on a CI environments.
+     */
+    public function skipOnCI(): self
+    {
+        if ($this->runningOnCI()) {
+            return $this->skip('This test is skipped on [CI].');
+        }
+
+        return $this;
+    }
+
+    public function skipLocally(): self
+    {
+        if ($this->runningOnCI() === false) {
+            return $this->skip('This test is skipped [locally].');
+        }
+
+        return $this;
+    }
+
     /**
      * Skips the current test unless the given test is running on Windows.
      */
@@ -616,6 +671,30 @@ final class TestCall // @phpstan-ignore-line
         return $this;
     }
 
+    /**
+     * Adds one or more references to the tested method or class. This helps
+     * to link test cases to the source code for easier navigation.
+     *
+     * @param  array<class-string|string>|class-string  ...$classes
+     */
+    public function references(string|array ...$classes): self
+    {
+        assert($classes !== []);
+
+        return $this;
+    }
+
+    /**
+     * Adds one or more references to the tested method or class. This helps
+     * to link test cases to the source code for easier navigation.
+     *
+     * @param  array<class-string|string>|class-string  ...$classes
+     */
+    public function see(string|array ...$classes): self
+    {
+        return $this->references(...$classes);
+    }
+
     /**
      * Informs the test runner that no expectations happen in this test,
      * and its purpose is simply to check whether the given code can