feat(error-handler): add ErrorHandlerInterceptor plugin

[rossaddison]

Closes #73

Summary

• New plugin/error-handler/ package (testo/error-handler)
• ErrorHandlerPlugin — the PluginConfigurator users add to their ApplicationConfig
• ErrorHandlerInterceptor — wraps each test in set_error_handler() / restore_error_handler() at ORDER_CLOSE_TO_TEST priority
• CapturedError — value object for a single PHP error (severity, message, file, line)
• CapturedErrors — collection stored as a TestResult attribute under CapturedErrors::class

Behaviour

Mode	What happens
failOnError: false (default)	Errors are captured; test status is unchanged; renderers can inspect the CapturedErrors attribute
failOnError: true	A captured error upgrades a passing test to Status::Failed, wrapping the first error in an ErrorException; already-failed/errored tests are not overridden

In both modes:

• restore_error_handler() is called in a finally block, so the previous handler is always restored even when the test throws
• All errors raised during the test are accumulated (not just the first)

Tests (10, all passing)

Test	Covers
noErrorsPassesResultThrough	No errors → result returned unmodified, no attribute attached
capturedErrorIsStoredAsAttribute	Single error stored with correct message and severity
multipleErrorsAreAllCaptured	All triggered errors appear in the list in order
collectModePreservesPassingStatus	Default mode does not change Status::Passed
failModeUpgradesPassingTestToFailed	failOnError: true sets Status::Failed + ErrorException failure
failModeUsesFirstErrorAsFailure	First error is the one wrapped, not the last
failModeDoesNotOverrideAlreadyFailedTest	Pre-existing Status::Failed + original throwable are preserved
failModeDoesNotOverrideErrorStatus	Pre-existing Status::Error is preserved
handlerIsRestoredAfterTestCompletes	Outer handler is active again after a normal test run
handlerIsRestoredEvenWhenTestThrows	Outer handler is active again even when the test pipeline throws

Monorepo wiring

• composer.json — require, autoload-dev, path-repository version entry
• testo.php — src exclusion + suites.php include
• .github/workflows/split-publish.yml — error-handler-[0-9]* tag for subtree split

Note on set_error_handler callback signatures

The two outer-handler closures in the test use zero parameters (static function () use (&$count)) rather than (int $errno, string $errstr). PHP silently discards extra arguments when a callable declares fewer params than the caller passes — this is standard PHP behaviour. The zero-param form avoids SonarQube S1172 (unused parameter) without needing @SuppressWarnings or the $_-prefix convention.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[rossaddison]

Implementation summary — testo/error-handler plugin

What this adds

A new plugin/error-handler/ package that wraps every test in set_error_handler() / restore_error_handler(), accumulating any PHP errors triggered during the test into a CapturedErrors attribute on the returned TestResult.

Files

File	Purpose
src/CapturedError.php	Value object — severity, message, file, line for one PHP error
src/Internal/CapturedErrors.php	Collection stored as a TestResult attribute under CapturedErrors::class
src/Internal/ErrorHandlerInterceptor.php	TestRunInterceptor at ORDER_CLOSE_TO_TEST priority — installs/restores handler, attaches attribute, optionally fails the test
src/ErrorHandlerPlugin.php	PluginConfigurator users add to their ApplicationConfig
tests/Unit/ErrorHandlerInterceptorTest.php	10 unit tests (all passing)

Behaviour

Mode	Result
new ErrorHandlerPlugin() (default)	Errors collected; test status unchanged; renderers may inspect CapturedErrors attribute
new ErrorHandlerPlugin(failOnError: true)	First captured error upgrades a passing test to Status::Failed with an ErrorException; pre-existing Failed/Error results are not overridden

restore_error_handler() is always called in a finally block — the previous handler is restored even when the test pipeline throws.

Test coverage

Test	What it verifies
noErrorsPassesResultThrough	No errors → result unmodified, no attribute
capturedErrorIsStoredAsAttribute	Single error → correct message and severity
multipleErrorsAreAllCaptured	All triggered errors appear in order
collectModePreservesPassingStatus	Default mode keeps Status::Passed
failModeUpgradesPassingTestToFailed	failOnError: true → Status::Failed + ErrorException
failModeUsesFirstErrorAsFailure	First error wins as the failure, not the last
failModeDoesNotOverrideAlreadyFailedTest	Pre-existing Status::Failed + original throwable preserved
failModeDoesNotOverrideErrorStatus	Pre-existing Status::Error preserved
handlerIsRestoredAfterTestCompletes	Outer handler is active again after a normal run
handlerIsRestoredEvenWhenTestThrows	Outer handler is active again even when the pipeline throws

Note on zero-param closures in tests

The outer-handler closures in the restoration tests use static function () use (&$count) with no declared parameters. PHP silently discards extra arguments when a callable declares fewer params than the caller passes — standard PHP behaviour — and the zero-param form avoids SonarQube S1172 (unused parameter) without needing suppress annotations or $_-prefix workarounds.

Monorepo wiring

• composer.json — require, autoload-dev, path-repository version entry
• testo.php — src exclusion + suites.php include
• .github/workflows/split-publish.yml — error-handler-[0-9]* tag for subtree split on release

[Copilot]

Pull request overview

Adds a new testo/error-handler plugin package that intercepts PHP errors during test execution, records them on TestResult, and optionally turns captured errors into test failures—integrating it into the monorepo (Composer wiring, suite registration, and split-publish tagging).

Changes:

• Introduces ErrorHandlerInterceptor + value objects (CapturedError, CapturedErrors) to capture and persist PHP errors raised during a test run.
• Adds an ErrorHandlerPlugin configurator to register the interceptor (with a failOnError option).
• Wires the new plugin into the monorepo: root Composer requirement + path version mapping, Testo suites inclusion, Infection config tweak, and split-publish tag pattern.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/Application/Stub/EmptyRun/.placeholder.php	Adds an empty fixture file to ensure the stub directory exists in mirrored test layouts.
testo.php	Registers the new plugin test suite location and includes its suites.php.
plugin/error-handler/tests/Unit/ErrorHandlerInterceptorTest.php	Adds unit tests for capturing/accumulating errors and handler restoration behavior.
plugin/error-handler/tests/suites.php	Declares the ErrorHandler unit test suite for Testo’s suite discovery.
plugin/error-handler/src/Internal/ErrorHandlerInterceptor.php	Implements the interceptor that installs/restores an error handler and records errors on the result.
plugin/error-handler/src/Internal/CapturedErrors.php	Adds the collection type used to store captured errors on TestResult.
plugin/error-handler/src/ErrorHandlerPlugin.php	Adds the public plugin configurator that registers the interceptor.
plugin/error-handler/src/CapturedError.php	Adds the value object representing a single captured PHP error.
plugin/error-handler/composer.json	Introduces the standalone package metadata and autoloading for the new plugin.
infection.json	Updates Infection mutator configuration to ignore inline-test source patterns.
composer.json	Adds the new plugin to root dependencies and monorepo package version mapping/autoload-dev.
.github/workflows/split-publish.yml	Extends subtree split publishing to recognize error-handler-* tags.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[roxblnfk]

Thanks for the time you're putting in.
I see you're leaning on AI heavily. So am I — but opening raw AI output as a PR without a human review pass is dismissive of the reviewer's time.

This PR has the same defect as #254: process-global state that isn't fiber-safe. The error-handler stack is process-global and tests can run inside fibers — when a test suspends, its handler stays on the stack while another runs, so errors leak into the wrong test's CapturedErrors, and interleaved resume makes restore_error_handler() pop the wrong frame. The fix is the scope-swap already in MockeryInterceptor::run() / MessengerHub::scope(): inside a fiber, restore the previous handler on suspend and re-install the test's on resume.

A second, open question: a test may change the error handler itself during the run. The interceptor should notice that and react — but the right behavior isn't obvious, so it's worth researching and discussing before implementing.

If you want to contribute to the project, I ask you to:

• carry the fixes from earlier reviews of your PRs into future ones;
• understand the issue first, and ask questions before implementing if you have any;
• validate the AI agent's output yourself. That part is the contributor's, not the reviewer's.

[rossaddison]

Thanks for the detailed review — addressed both points, and validated the AI-generated fix myself rather than just pasting it.

Fiber-safety fix

ErrorHandlerInterceptor::runTest() now wraps $next() in its own fiber and swaps the error handler on every suspend/resume — restoring whichever handler was active before this test installed its own (the native set_error_handler() stack does that for free) on suspend, and reinstalling this test's handler on resume. This mirrors the pattern already reviewed and merged in MockeryInterceptor::run() and MessengerHub::scope().

Added a regression test, restoresTheOuterHandlerWhileSuspendedAndReinstallsItsOwnOnResume. I checked it's actually discriminating, not just green by construction: reverted to the old code locally, confirmed the new test fails against it (an error fired while the test is suspended gets wrongly swallowed by the still-installed handler instead of reaching the outer one), then restored the fix and confirmed it passes.

The second question you raised — what should happen if a test changes the error handler itself mid-run — I've left alone. You flagged it as needing research/discussion before implementing, so I'm not guessing at behavior here; happy to pick it up separately once there's a direction.

Copilot's comments

• The internal-type-leak on ErrorHandlerPlugin's docblock: promoted Internal\CapturedErrors to a public Testo\ErrorHandler\CapturedErrors, matching its sibling CapturedError. The plugin's own docs already told consumers to read this attribute off TestResult, so it was never really internal — just not marked as such.
• The failOnError status-upgrade restriction to Status::Passed was already fixed in an earlier commit on this branch.

Also

Rebased onto current 1.x (this had drifted 26 commits behind) — one real conflict in composer.json (version bumps landed upstream since this PR opened), resolved by taking the newer versions and re-adding the testo/error-handler require line.

Verification

• composer rector:ci — clean, 0 files
• Full Testo suite — 1682 passed, 6 failed/7 error (same pre-existing Bench/Self baseline as the other PRs in the current series, unrelated)
• ErrorHandlerInterceptorTest — 11/11 passed, including the new fiber-safety test
• Psalm — confirmed this repo's Psalm CI only covers core/ (via psalm.xml and psalm.yml's trigger paths); plugin/error-handler/ was never in scope, before or after this change