feat(error-handler): add ErrorHandlerInterceptor plugin

[rossaddison]

🔍 What was changed

New testo/error-handler plugin (plugin/error-handler). ErrorHandlerPlugin wraps every test in an error handler and records what PHP raised while the test ran.

• Captured errors land on the TestResult as a CapturedErrors attribute (severity, message, file, line, handled). Errors nobody handled are also written to the stderr message channel in PHP's own wording, and PHP's own printing is suppressed so nothing appears twice.
• new ErrorHandlerPlugin(failOnError: true) turns the first captured error into an ErrorException failure of a passing test. Errors silenced with @ or excluded by error_reporting() are neither captured nor failed.
• A handler installed before the test (bootstrap, framework) still runs first for every error, sees the real error_reporting() level, and an exception it throws stays the test's own control flow with nothing captured. E_USER_ERROR is thrown as an ErrorException in every mode instead of being swallowed.
• The handler stack is put back as the test found it. A passing test that left its own handler installed, or removed ours, is Risky with the reason in the error-handler message channel. #[ExpectErrorHandlerChange] (class, method or function) declares such a test intentional; a marked test that leaves the stack unchanged fails with ErrorHandlerUnchanged.

How it works

• The test's slice of the process-global handler stack (our handler plus anything the test installed above it) leaves the stack on every fiber suspension and comes back in the same order on resumption, so a suspended test's handler never sees a sibling's errors and the test finds its own handler in place after await.
• Inside the handler: forward to the previous handler, then throw for E_USER_ERROR, then record unless the reporting mask excludes the severity, and return true.

Review notes

• PHPUnit 13 masks error_reporting() down to fatal levels while a test runs, so the mirrored plugin tests see every error as silenced. tools/phpunit/phpunit.xml excludes tests/PhpUnit/ErrorHandler from the mirror run.
• The behaviour of the previous-handler chain follows PHPUnit's resolution of Issue is reported even when previously registered error handler turns the error into an exception sebastianbergmann/phpunit#6817 and #6818: forward first, and never touch the reporting level the previous handler observes.

Checklist

• Closes Error handler interceptor #73
• How was this tested:
  • Unit tests added (ErrorHandler/Unit, 32 tests)
  • Full self-suite run locally without new failures; composer phpunit mirror green after the exclusion
  • cs, rector and psalm clean over plugin/error-handler
• Before merge:
  • php-testo/error-handler repository, .github/.release-please-config.json entry and Packagist registration, otherwise the root composer.json requirement is unresolvable outside the monorepo
  • Plugin README.md and CHANGELOG.md

Documentation

• skills/testo-php-errors/SKILL.md documents the plugin, the error table and #[ExpectErrorHandlerChange]; docs/spec/skills-regrouping.md schedules folding it into a direction skill.

[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

[roxblnfk]

Please remove all unrelated changes from other PRs

[rossaddison]

Rebased onto current 1.x (was 21 commits behind) and cleaned up scope, per the two open points from review:

• Fiber-safety fix already landed back on Aug 13 (e8a70084) — wraps $next() in its own fiber and swaps set_error_handler()/restore_error_handler() on every suspend/resume boundary, mirroring MockeryInterceptor::run() exactly. Added a regression test (restoresTheOuterHandlerWhileSuspendedAndReinstallsItsOwnOnResume) that fails against the old naive install-before/restore-after code and passes against the fix.
• Dropped the unrelated infection.json changes (the #[TestInline] mutator-skip commits) — confirmed they're not on 1.x, so this rebase drops them from this PR's diff entirely rather than carrying them forward.
• The rebase's own automatic merge briefly produced duplicate composer.json keys (stale version constraints from this branch's older commit alongside 1.x's current ones) — caught and fixed before pushing; verified no duplicate keys remain and composer install succeeds.

Current diff is 11 files, no infection.json, ErrorHandler/Unit suite passes 11/11 including the fiber-safety regression test.

The open question from review (what should happen if a test changes the error handler itself mid-run) is still intentionally unaddressed — agreed it needs discussion first, not a quick fix.

Ready for another look whenever you have time.