feat(error-handler): add ErrorHandlerInterceptor plugin

.github/workflows/split-publish.yml

@@ -29,6 +29,7 @@ on:  # yamllint disable-line rule:truthy
       - 'convention-[0-9]*'
       - 'data-[0-9]*'
       - 'facade-[0-9]*'
+      - 'error-handler-[0-9]*'
       - 'filter-[0-9]*'
       - 'inline-[0-9]*'
       - 'lifecycle-[0-9]*'

composer.json

@@ -43,7 +43,8 @@
         "testo/bridge-symfony-console": "^0.1.11",
         "testo/codecov": "^0.2.1",
         "testo/convention": "^0.1.4",
-        "testo/data": "^0.1.9",
+        "testo/data": "^0.1.7",
+        "testo/error-handler": "^0.1",
         "testo/filter": "^0.1.6",
         "testo/inline": "^0.1.8",
         "testo/lifecycle": "^0.1.5",
@@ -103,6 +104,7 @@
             "Tests\\Convention\\": "plugin/convention/tests/",
             "Tests\\Data\\": "plugin/data/tests/",
             "Tests\\Facade\\": "plugin/facade/tests/",
+            "Tests\\ErrorHandler\\": "plugin/error-handler/tests/",
             "Tests\\Filter\\": "plugin/filter/tests/",
             "Tests\\Lifecycle\\": "plugin/lifecycle/tests/",
             "Tests\\Repeat\\": "plugin/repeat/tests/",
@@ -127,6 +129,7 @@
                     "testo/convention": "0.1.x-dev",
                     "testo/data": "0.1.x-dev",
                     "testo/facade": "0.1.x-dev",
+                    "testo/error-handler": "0.1.x-dev",
                     "testo/filter": "0.1.x-dev",
                     "testo/inline": "0.1.x-dev",
                     "testo/lifecycle": "0.1.x-dev",

infection.json

@@ -17,5 +17,11 @@
         "stryker": {
             "report": "1.x"
         }
+    },
+    "mutators": {
+        "@default": true,
+        "global-ignoreSourceCodeByRegex": [
+            "#\\[TestInline"
+        ]
     }
 }

plugin/error-handler/composer.json

@@ -0,0 +1,39 @@
+{
+    "name": "testo/error-handler",
+    "description": "Error handler interceptor plugin for the Testo testing framework.",
+    "license": "BSD-3-Clause",
+    "type": "library",
+    "keywords": [
+        "testo",
+        "error-handler",
+        "test"
+    ],
+    "authors": [
+        {
+            "name": "Aleksei Gagarin (roxblnfk)",
+            "homepage": "https://github.com/roxblnfk"
+        }
+    ],
+    "funding": [
+        {
+            "type": "boosty",
+            "url": "https://boosty.to/roxblnfk"
+        }
+    ],
+    "require": {
+        "php": ">=8.2",
+        "testo/testo": "0.10.34 - 1"
+    },
+    "autoload": {
+        "psr-4": {
+            "Testo\\ErrorHandler\\": "src/"
+        }
+    },
+    "minimum-stability": "dev",
+    "prefer-stable": true,
+    "extra": {
+        "branch-alias": {
+            "dev-1.x": "1.x-dev"
+        }
+    }
+}

plugin/error-handler/src/CapturedError.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\ErrorHandler;
+
+/**
+ * A single PHP error captured during test execution.
+ *
+ * @api
+ */
+final readonly class CapturedError
+{
+    public function __construct(
+        public int $severity,
+        public string $message,
+        public string $file,
+        public int $line,
+    ) {}
+}

plugin/error-handler/src/CapturedErrors.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\ErrorHandler;
+
+/**
+ * Collection of PHP errors accumulated during test execution.
+ *
+ * Stored as a {@see \Testo\Core\Context\TestResult} attribute under the key {@see CapturedErrors::class}.
+ * Renderers that wish to display collected errors should retrieve it from the result.
+ *
+ * @api
+ */
+final readonly class CapturedErrors
+{
+    /** @param list<CapturedError> $errors */
+    public function __construct(
+        public array $errors,
+    ) {}
+
+    public function isEmpty(): bool
+    {
+        return $this->errors === [];
+    }
+}

plugin/error-handler/src/ErrorHandlerPlugin.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\ErrorHandler;
+
+use Internal\Container\Container;
+use Testo\Common\PluginConfigurator;
+use Testo\ErrorHandler\Internal\ErrorHandlerInterceptor;
+use Testo\Pipeline\InterceptorCollector;
+
+/**
+ * Plugin that captures PHP errors raised during test execution.
+ *
+ * By default errors are collected and stored as a {@see CapturedErrors} attribute
+ * on the {@see \Testo\Core\Context\TestResult}, but the test still passes. Pass
+ * {@see $failOnError}: true to make any captured error fail the test instead.
+ *
+ * @api
+ */
+final readonly class ErrorHandlerPlugin implements PluginConfigurator
+{
+    /**
+     * @param bool $failOnError When true, a captured PHP error fails the test. When false
+     *                          (default) errors are collected but the test result is unchanged.
+     */
+    public function __construct(
+        private bool $failOnError = false,
+    ) {}
+
+    #[\Override]
+    public function configure(Container $container): void
+    {
+        $container->get(InterceptorCollector::class)
+            ->addInterceptor(new ErrorHandlerInterceptor($this->failOnError));
+    }
+}

plugin/error-handler/src/Internal/ErrorHandlerInterceptor.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Testo\ErrorHandler\Internal;
+
+use Testo\Core\Context\TestInfo;
+use Testo\Core\Context\TestResult;
+use Testo\Core\Value\Status;
+use Testo\ErrorHandler\CapturedError;
+use Testo\ErrorHandler\CapturedErrors;
+use Testo\Pipeline\Attribute\InterceptorOptions;
+use Testo\Pipeline\Middleware\TestRunInterceptor;
+
+/**
+ * Intercepts PHP errors raised during test execution.
+ *
+ * Registers a custom error handler via {@see \set_error_handler()} before the test runs and
+ * restores the previous handler afterward via {@see \restore_error_handler()}. Accumulated
+ * errors are stored in the returned {@see TestResult} as a {@see CapturedErrors} attribute.
+ *
+ * @internal
+ * @psalm-internal Testo\ErrorHandler
+ */
+#[InterceptorOptions(order: InterceptorOptions::ORDER_CLOSE_TO_TEST)]
+final readonly class ErrorHandlerInterceptor implements TestRunInterceptor
+{
+    /**
+     * @param bool $failOnError When true, any captured error upgrades a passing test to
+     *                          {@see Status::Failed} with the first error wrapped in an
+     *                          {@see \ErrorException} as the failure.
+     */
+    public function __construct(
+        private bool $failOnError = false,
+    ) {}
+
+    #[\Override]
+    public function runTest(TestInfo $info, callable $next): TestResult
+    {
+        /** @var list<CapturedError> $errors */
+        $errors = [];
+
+        $handler = static function (int $severity, string $message, string $file, int $line) use (&$errors): bool {
+            $errors[] = new CapturedError($severity, $message, $file, $line);
+            return true;
+        };
+
+        $result = $this->run($info, $next, $handler);
+
+        if ($errors === []) {
+            return $result;
+        }
+
+        $result = $result->withAttribute(CapturedErrors::class, new CapturedErrors($errors));
+
+        if ($this->failOnError && $result->status === Status::Passed) {
+            $first = $errors[0];
+            $result = $result
+                ->with(status: Status::Failed)
+                ->withFailure(new \ErrorException($first->message, 0, $first->severity, $first->file, $first->line));
+        }
+
+        return $result;
+    }
+
+    /**
+     * Runs the test with {@see $handler} installed via {@see \set_error_handler()}, keeping it
+     * bound to this test across fiber suspensions.
+     *
+     * set_error_handler()/restore_error_handler() operate on one process-global stack, so under
+     * concurrent (fiber-based) execution — where sibling tests interleave with this one — a plain
+     * install-before/restore-after around $next() would leak errors into the wrong test's
+     * CapturedErrors, and an interleaved resume could pop a sibling's handler instead of ours. On
+     * every suspension we restore whichever handler was active before this test installed its own
+     * (the native stack does that for free); on resumption we re-install this test's handler.
+     * Mirrors {@see \Testo\Bridge\Mockery\Internal\MockeryInterceptor::run()} and
+     * {@see \Testo\Application\Internal\MessengerHub::scope()}.
+     *
+     * @param callable(TestInfo): TestResult $next
+     */
+    private function run(TestInfo $info, callable $next, \Closure $handler): TestResult
+    {
+        \set_error_handler($handler);
+        try {
+            if (\Fiber::getCurrent() === null) {
+                return $next($info);
+            }
+
+            $fiber = new \Fiber(static fn(): TestResult => $next($info));
+            $value = $fiber->start();
+            while (!$fiber->isTerminated()) {
+                \restore_error_handler();
+                try {
+                    $resume = \Fiber::suspend($value);
+                } catch (\Throwable $e) {
+                    \set_error_handler($handler);
+                    $value = $fiber->throw($e);
+                    continue;
+                }
+
+                \set_error_handler($handler);
+                $value = $fiber->resume($resume);
+            }
+
+            /** @var TestResult $result */
+            $result = $fiber->getReturn();
+            return $result;
+        } finally {
+            \restore_error_handler();
+        }
+    }
+}