pest/CLAUDE.md

CLAUDE.md

Do not edit this file. Agents must never add, remove, or reword anything here. If a change seems needed, say so and let a human do it.

Ask before testing

When asked to review code or build a feature, do not run the test suite and do not write new tests. Make the change, report it, then ask the user whether tests should be added — describing the tests you have in mind — and wait for the user to confirm.

Two reasons this matters here: the suite takes minutes, and tests/.snapshots/success.txt plus the tally in tests/Visual/Parallel.php encode the whole suite's result, so a single added test breaks both.

Once the user confirms:

composer test:unit         # fast, excludes the visual group
composer test:integration  # visual and snapshot tests
composer test              # everything CI runs, in CI's order
composer update:snapshots  # only when a test was added or removed

TIA scenario tests

tests/Features/Tia/* scaffold a throwaway git project, run a real pest subprocess against it, and diff the TIA graph it wrote. They exist because TIA's contract is about what a run writes — replay, branch keys, and the COMPLETE / RESULTS-ONLY / HARD-SUPPRESSED tiers are invisible to ordinary assertions, and every case used to be measured by hand against a playground app.

Add one whenever a change touches branch resolution, replay, filtered mode, or the write tiers. How:

• Project::make('master') scaffolds; seed('master') writes a graph and sentinels every cached result (time=9.999, assertions=42) so any rewrite shows up.
• $project->pest('--tia', …) runs it; $project->delta() compares against that snapshot. writtenCount() is the discriminator — 0 means "replayed", not "wrote the same values". mutateGraph() bends one entry; overlays in tests/Fixtures/Tia/overlays/<name>/ supply a different tests/Pest.php.
• Keep expectations driver-independent: a cold recording run needs pcov/xdebug and behaves differently without one. Seed a graph instead of recording one.

Run them by file (a directory argument finds nothing) or by --filter:

php bin/pest tests/Features/Tia/PartialRunWriteTier.php