| name | fetch-php-debug-failure |
| description | Diagnose a failing Fetch PHP test or unexpected behavior — reproduce it, classify the cause (environment, network, async/timing, platform, dependency, or implementation), minimize the failing case, fix the root cause, and add regression coverage. Use when a test fails locally or in CI. |
Debug a Fetch PHP failure
Follow AGENTS.md. For CI-matrix-specific failures use
fetch-php-ci-triage; for writing the regression test use
fetch-php-test-development.
When to use
A PHPUnit test fails, PHPStan reports an error, or runtime behavior is wrong and
you need to find and fix the root cause.
Workflow
-
Reproduce narrowly.
./vendor/bin/phpunit --filter=<method>
./vendor/bin/phpunit tests/Unit/<Some>Test.php
NO_NETWORK=1 composer test
-
Classify the cause before fixing:
- Environment — PHP version (
php -v; CI runs 8.3/8.4/8.5), missing ext
(pcntl), locale/timezone (phpunit.xml.dist pins UTC / C.UTF-8).
- Network — a test reaching real hosts; convert to
MockServer/Mockery.
- Async/timing — dependence on wall-clock, event-loop ordering, or
sleep(); make it deterministic.
- Platform — Windows/macOS path, EOL, or
pcntl/posix differences
(Windows ignores those extensions).
- Dependency — behavior differing under
prefer-lowest; check version
constraints in composer.json.
- Test isolation — leaked global state (
GlobalServices, MockServer,
fetch_client); confirm by running the test alone vs in suite.
- Implementation — a genuine bug in
src/Fetch.
-
Minimize to the smallest input/state that still fails; read the owning
class/trait (via CODE_MAP.md).
-
Fix the root cause, not the symptom. Don't loosen assertions or add
PHPStan ignores to make red go green.
-
Add a regression test that fails without the fix.
-
Re-run the focused test, then NO_NETWORK=1 composer check.
Verification
- The regression test fails on the unpatched code and passes after the fix.
- Full offline gate green; no new PHPStan ignores; no widened tolerances.
Red flags — stop
- "Fix" is deleting/skipping the assertion, adding
@group, or an ignore entry.
- Root cause is unknown but the test now passes (likely masked flake).
- The failure is a real BC break surfaced by a test — escalate via
fetch-php-public-api-review before changing the test's expectation.
