feat(test): add #[Skip] attribute to skip tests declaratively PR-1.

.github/.release-please-config.json

@@ -41,6 +41,12 @@
             "include-component-in-tag": true,
             "changelog-path": "CHANGELOG.md"
         },
+        "plugin/skip": {
+            "package-name": "testo/skip",
+            "component": "skip",
+            "include-component-in-tag": true,
+            "changelog-path": "CHANGELOG.md"
+        },
         "plugin/test": {
             "package-name": "testo/test",
             "component": "test",

.github/workflows/split-publish.yml

@@ -34,6 +34,7 @@ on:  # yamllint disable-line rule:truthy
       - 'lifecycle-[0-9]*'
       - 'repeat-[0-9]*'
       - 'retry-[0-9]*'
+      - 'skip-[0-9]*'
       - 'test-[0-9]*'
 
 name: 📦 Split publish

composer.json

@@ -50,6 +50,7 @@
         "testo/lifecycle": "^0.1.6",
         "testo/repeat": "^0.1.9",
         "testo/retry": "^0.1.5",
+        "testo/skip": "0.1 - 1",
         "testo/test": "^0.1.7",
         "yiisoft/injector": "^1.2"
     },
@@ -104,6 +105,7 @@
             "Tests\\Lifecycle\\": "plugin/lifecycle/tests/",
             "Tests\\Repeat\\": "plugin/repeat/tests/",
             "Tests\\Retry\\": "plugin/retry/tests/",
+            "Tests\\Skip\\": "plugin/skip/tests/",
             "Tests\\Test\\": "plugin/test/tests/"
         },
         "files": [
@@ -129,6 +131,7 @@
                     "testo/lifecycle": "0.1.x-dev",
                     "testo/repeat": "0.1.x-dev",
                     "testo/retry": "0.1.x-dev",
+                    "testo/skip": "0.1.x-dev",
                     "testo/test": "0.1.x-dev"
                 }
             }

core/Pipeline/Attribute/CaseInterceptable.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\Pipeline\Attribute;
+
+/**
+ * An {@see Interceptable} attribute whose case-level interceptors are wired even when the attribute
+ * is placed on a test method or function, not only on the case class.
+ *
+ * By default a test-level attribute reaches only the per-test pipeline
+ * ({@see \Testo\Pipeline\Middleware\TestRunInterceptor}); the case pipeline
+ * ({@see \Testo\Pipeline\Middleware\TestCaseRunInterceptor}) is built from class attributes alone.
+ * Implement this interface when the attribute has to act on the whole case from a single test —
+ * e.g. to take that test out of the case before any lifecycle hook runs. The interceptor is
+ * instantiated once per attribute occurrence; use {@see InterceptorOptions::$onConflict} to
+ * collapse the duplicates when several tests carry the attribute.
+ *
+ * @api
+ */
+interface CaseInterceptable extends Interceptable {}

core/Pipeline/Internal/AttributesInterceptor.php

@@ -9,6 +9,7 @@
 use Testo\Core\Context\CaseResult;
 use Testo\Core\Context\TestInfo;
 use Testo\Core\Context\TestResult;
+use Testo\Pipeline\Attribute\CaseInterceptable;
 use Testo\Pipeline\Attribute\Interceptable;
 use Testo\Pipeline\Attribute\InterceptorOptions;
 use Testo\Pipeline\InterceptorProvider;
@@ -21,6 +22,9 @@
  * Reads {@see Interceptable} attributes and integrates them into the pipeline.
  * Also maps the found attributes into the info DTO attributes.
  *
+ * At the case level the class attributes are read; a test-level attribute joins the case pipeline
+ * only when it is a {@see CaseInterceptable}.
+ *
  * @internal
  * @psalm-internal Testo\Pipeline
  */
@@ -84,30 +88,47 @@ static function (\ReflectionAttribute $a): Interceptable {
     #[\Override]
     public function runTestCase(CaseInfo $info, callable $next): CaseResult
     {
-        $attrs = $info->definition->reflection === null
+        $classAttributes = $info->definition->reflection === null
             ? []
             : Reflection::fetchClassAttributes(
                 class: $info->definition->reflection,
                 attributeClass: Interceptable::class,
                 flags: \ReflectionAttribute::IS_INSTANCEOF,
             );
 
-        if ($attrs === []) {
+        # Test-level attributes join the case pipeline only when they ask for it explicitly.
+        $testAttributes = [];
+        foreach ($info->definition->tests->getTests() as $definition) {
+            $testAttributes = [...$testAttributes, ...Reflection::fetchFunctionAttributes(
+                function: $definition->reflection,
+                attributeClass: CaseInterceptable::class,
+                flags: \ReflectionAttribute::IS_INSTANCEOF,
+            )];
+        }
+
+        if ($classAttributes === [] && $testAttributes === []) {
             # No attributes, continue to next interceptor
             return $next($info);
         }
 
-        $attrs = \array_map(
+        $instantiate = static fn(array $attrs): array => \array_values(\array_map(
             static function (\ReflectionAttribute $a): Interceptable {
                 /** @var Interceptable */
                 return $a->newInstance();
             },
             $attrs,
-        );
+        ));
+        $classAttributes = $instantiate($classAttributes);
+        $testAttributes = $instantiate($testAttributes);
 
         # Merge and instantiate attributes
-        $interceptors = $this->interceptorProvider->fromAttributes(TestCaseRunInterceptor::class, ...$attrs);
-        $info = $info->withAttributes(self::groupAttributes($attrs));
+        $interceptors = $this->interceptorProvider->fromAttributes(
+            TestCaseRunInterceptor::class,
+            ...$classAttributes,
+            ...$testAttributes,
+        );
+        # Only class attributes describe the case itself; test attributes stay on their tests.
+        $classAttributes === [] or $info = $info->withAttributes(self::groupAttributes($classAttributes));
 
         /** @var callable(CaseInfo): CaseResult $pipeline */
         $pipeline = $next instanceof Pipeline

plugin/lifecycle/tests/Feature/FullySkippedCaseFeatureTest.php

@@ -0,0 +1,82 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Lifecycle\Feature;
+
+use Testo\Assert;
+use Testo\Codecov\Covers;
+use Testo\Core\Value\Status;
+use Testo\Lifecycle\Internal\LifecycleInterceptor;
+use Testo\Test;
+use Testo\Testing\Attribute\TestingSuite;
+use Testo\Testing\Helper\TestRunner;
+use Tests\Lifecycle\Stub\FullySkipped\FullySkippedClassStub;
+use Tests\Lifecycle\Stub\FullySkipped\FullySkippedFunctionState;
+
+/**
+ * End-to-end regression test for {@see LifecycleInterceptor}: the `#[BeforeClass]`/`#[AfterClass]` hooks
+ * of a case still run when an outer case interceptor — here `#[Skip]` from `testo/skip` — leaves
+ * the case without a single active test.
+ *
+ * The `#[Skip]` case interceptor deactivates the skipped tests before the {@see LifecycleInterceptor}
+ * collects the case's hooks, so hook discovery must not depend on the surviving tests. It does not:
+ * the hooks are the case's non-tests. Prefilling defines every member as a non-test,
+ * {@see LifecycleInterceptor} demotes back the lifecycle-annotated ones a finder took for tests
+ * (a class-level `#[Test]` promotes the hook methods of a class case first), and it then reads
+ * them all back with `filter(isTest: false)` — non-tests outlive the deactivation of the tests.
+ *
+ * Both case shapes are pinned here through the real pipeline. Their members are prefilled by
+ * {@see \Testo\Core\Definition\CaseDefinitions::define()} from the two sources it knows: the
+ * methods of {@see \Testo\Core\Definition\CaseDefinition::$reflection} for a class-based case,
+ * the file's free functions for a function-based one.
+ */
+#[Test]
+#[Covers(LifecycleInterceptor::class)]
+#[TestingSuite(path: __DIR__ . '/../Stub/FullySkipped')]
+final class FullySkippedCaseFeatureTest
+{
+    public function __construct()
+    {
+        # Functions are not autoloadable: load the stub so TestRunner::runTest() can resolve the
+        # function names below. The pipeline re-includes the same file (include_once) when it runs.
+        require_once __DIR__ . '/../Stub/FullySkipped/fully_skipped_functions.php';
+    }
+
+    /**
+     * The function-based case shape: class-level hooks fire exactly once per directory run even
+     * though no test of the case stays active; per-test hooks have nothing to wrap and stay silent.
+     */
+    public function classHooksRunForFullySkippedFunctionCase(): void
+    {
+        $beforeClass = FullySkippedFunctionState::$beforeClassCalls;
+        $afterClass = FullySkippedFunctionState::$afterClassCalls;
+        $beforeTest = FullySkippedFunctionState::$beforeTestCalls;
+        $afterTest = FullySkippedFunctionState::$afterTestCalls;
+
+        $result = TestRunner::runTest('Tests\Lifecycle\Stub\FullySkipped\skippedFnOne');
+
+        Assert::same($result->status, Status::Skipped);
+        Assert::same(FullySkippedFunctionState::$beforeClassCalls - $beforeClass, 1);
+        Assert::same(FullySkippedFunctionState::$afterClassCalls - $afterClass, 1);
+        # No test of the case ran, so the per-test hooks never fired.
+        Assert::same(FullySkippedFunctionState::$beforeTestCalls - $beforeTest, 0);
+        Assert::same(FullySkippedFunctionState::$afterTestCalls - $afterTest, 0);
+    }
+
+    /**
+     * The class-based analog: hooks are the non-tests prefilled from the case's class reflection
+     * and must keep firing for a fully skipped class exactly as before.
+     */
+    public function classHooksRunForFullySkippedClassCase(): void
+    {
+        $beforeClass = FullySkippedClassStub::$beforeClassCalls;
+        $afterClass = FullySkippedClassStub::$afterClassCalls;
+
+        $result = TestRunner::runTest([FullySkippedClassStub::class, 'skipped']);
+
+        Assert::same($result->status, Status::Skipped);
+        Assert::same(FullySkippedClassStub::$beforeClassCalls - $beforeClass, 1);
+        Assert::same(FullySkippedClassStub::$afterClassCalls - $afterClass, 1);
+    }
+}

plugin/lifecycle/tests/Stub/FullySkipped/FullySkippedClassStub.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Lifecycle\Stub\FullySkipped;
+
+use Testo\Lifecycle\AfterClass;
+use Testo\Lifecycle\BeforeClass;
+use Testo\Test;
+use Testo\Skip;
+
+/**
+ * Class-based analog of the fully skipped function case in `fully_skipped_functions.php`
+ * ({@see skippedFnOne()}): the hooks are the case's non-tests, so they never depended on the
+ * surviving tests — pinned here so both flavors stay in lockstep.
+ *
+ * Static hook counters accumulate across directory runs — feature tests assert deltas. The hooks
+ * are static so the fully skipped class is never instantiated.
+ */
+#[Test]
+final class FullySkippedClassStub
+{
+    public static int $beforeClassCalls = 0;
+    public static int $afterClassCalls = 0;
+
+    #[BeforeClass]
+    public static function bootCase(): void
+    {
+        ++self::$beforeClassCalls;
+    }
+
+    #[AfterClass]
+    public static function shutdownCase(): void
+    {
+        ++self::$afterClassCalls;
+    }
+
+    #[Skip('the whole class case is skipped')]
+    public function skipped(): void
+    {
+        throw new \LogicException('Must never run: the test is skipped.');
+    }
+}

plugin/lifecycle/tests/Stub/FullySkipped/fully_skipped_functions.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Lifecycle\Stub\FullySkipped;
+
+use Testo\Lifecycle\AfterClass;
+use Testo\Lifecycle\AfterTest;
+use Testo\Lifecycle\BeforeClass;
+use Testo\Lifecycle\BeforeTest;
+use Testo\Test;
+use Testo\Skip;
+
+/**
+ * A fully skipped function-based case: every `#[Test]` function is under `#[Skip]`. Mirrors
+ * {@see FullySkippedClassStub} for the function-based shape of the same scenario. Its two tests
+ * spell the attribute both ways — `skippedFnOne` with a reason, `skippedFnTwo` without — so neither
+ * form leaves the case with an active test.
+ *
+ * The `#[Skip]` case interceptor deactivates the skipped tests — they leave the case's active
+ * test set — before the {@see \Testo\Lifecycle\Internal\LifecycleInterceptor} runs, so hook
+ * discovery must not depend on the surviving tests: `#[BeforeClass]`/`#[AfterClass]` still run
+ * for the case (the `#[Skip]` contract), while the per-test hooks have nothing to wrap.
+ *
+ * Static hook counters accumulate across directory runs — feature tests assert deltas.
+ * State is shared through {@see FullySkippedFunctionState} because functions have no `$this`.
+ */
+#[BeforeClass]
+function skippedCaseSetUpClass(): void
+{
+    ++FullySkippedFunctionState::$beforeClassCalls;
+}
+
+#[AfterClass]
+function skippedCaseTearDownClass(): void
+{
+    ++FullySkippedFunctionState::$afterClassCalls;
+}
+
+#[BeforeTest]
+function skippedCaseSetUp(): void
+{
+    ++FullySkippedFunctionState::$beforeTestCalls;
+}
+
+#[AfterTest]
+function skippedCaseTearDown(): void
+{
+    ++FullySkippedFunctionState::$afterTestCalls;
+}
+
+#[Test]
+#[Skip('the whole functional case is skipped')]
+function skippedFnOne(): void
+{
+    throw new \LogicException('Must never run: the test is skipped.');
+}
+
+#[Test]
+#[Skip]
+function skippedFnTwo(): void
+{
+    throw new \LogicException('Must never run: the test is skipped.');
+}
+
+/**
+ * Call counters for the lifecycle functions above. Not autoloadable — the feature test
+ * `require_once`s this file before touching the counters.
+ */
+final class FullySkippedFunctionState
+{
+    public static int $beforeClassCalls = 0;
+    public static int $afterClassCalls = 0;
+    public static int $beforeTestCalls = 0;
+    public static int $afterTestCalls = 0;
+}

plugin/skip/.github/workflows/close-prs.yml

@@ -0,0 +1,14 @@
+name: Close PRs
+
+on:
+  pull_request_target:
+    types: [opened, reopened]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  close:
+    uses: php-testo/gh-actions/.github/workflows/close-foreign-prs.yml@v1
+    with:
+      upstream-url: https://github.com/php-testo/testo

plugin/skip/README.md

@@ -0,0 +1,41 @@
+<p align="center">
+    <a href="https://github.com/php-testo/testo"><img alt="TESTO"
+         src="https://github.com/php-testo/.github/blob/1.x/resources/logo-full.svg?raw=true"
+         style="width: 2in; display: block"
+    /></a>
+</p>
+
+<p align="center">Skip attribute plugin</p>
+
+<div align="center">
+
+[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&logo=gitbook&logoColor=white)](https://php-testo.github.io)
+[![Support on Boosty](https://img.shields.io/static/v1?style=for-the-badge&label=&message=Sponsorship&logo=Boosty&logoColor=white&color=%23F15F2C)](https://boosty.to/roxblnfk)
+
+</div>
+
+<br />
+
+> [!IMPORTANT]
+> ## 🪞 This is a read-only mirror.
+>
+> Active development of the Testo project lives in [**php-testo/testo**](https://github.com/php-testo/testo) under `plugin/skip/`. This repository is **automatically synchronized** from there on every release.
+>
+> File issues and pull requests in the [main monorepo](https://github.com/php-testo/testo/issues), not here.
+
+## About
+
+Marks a test, a test class or a test function as skipped without deleting or hiding it. The test is not executed, but stays in every report as Skipped with its reason, so parked tests remain visible until someone returns to them.
+
+The skip is declared ahead of time, next to the test; skipping at runtime from the test body is covered by the core `SkipTest` exception instead.
+
+## Install
+
+```bash
+composer require --dev testo/skip
+```
+
+[![PHP](https://img.shields.io/packagist/php-v/testo/skip.svg?style=flat-square&logo=php)](https://packagist.org/packages/testo/skip)
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/testo/skip.svg?style=flat-square&logo=packagist)](https://packagist.org/packages/testo/skip)
+[![License](https://img.shields.io/packagist/l/testo/skip.svg?style=flat-square)](https://github.com/php-testo/testo/blob/1.x/LICENSE.md)
+[![Total Downloads](https://img.shields.io/packagist/dt/testo/skip.svg?style=flat-square)](https://packagist.org/packages/testo/skip/stats)