rewrite-tests-pest

Constraints

• Apply @rules/php/core-standards.mdc
• Apply @rules/code-testing/general.mdc
• If the current project uses Laravel, also apply @rules/laravel/laravel.mdc, @rules/laravel/architecture.mdc, @rules/laravel/filament.mdc, and @rules/laravel/livewire.mdc
• Do not generate covers()

Use when

• Existing tests are written in PHPUnit-style syntax and should be rewritten to Pest
• You want to modernize tests without changing their intended behavior

Required approach

• Preserve test intent and coverage of the rewritten behavior
• Keep tests deterministic and non-flaky
• Prefer simple, readable Pest syntax
• Use helper methods or datasets when they clearly reduce duplication
• Avoid reflection; prefer mocks or partial mocks when readable and effective
• Avoid branching in tests; prefer separate test cases or datasets instead

Read, Map & Verify before rewriting (mandatory pre-flight)

Reading, mapping, and verifying come first; rewriting comes last. This pre-flight is blocking — do not rewrite a single line until all three steps pass, and never act on an assumption you have not confirmed by reading the code.

1. Read — open and read the actual tests being rewritten and the code they exercise (the system under test, shared setup, helpers, datasets). Confirm what each test asserts by reading it, not by guessing from its name.
2. Map — map the change's blast radius: every assertion and covered code path that must survive the rewrite, the shared setup/helpers to reuse, and the project's existing Pest conventions.
3. Verify — run the existing tests first and confirm they pass, so you rewrite from a known-green baseline. If the original behavior or coverage is unclear, stop and clarify instead of rewriting on a wrong premise.

Only after Read, Map, and Verify are complete may the rewrite begin.

Execution

1. Identify existing tests that should be rewritten to Pest syntax.
2. Analyze repeated setup and assertions before rewriting.
3. Rewrite tests to Pest syntax without changing covered behavior.
4. Use datasets/data providers where they simplify similar test cases.
5. Move broadly shared lightweight test helpers to Pest.php when it improves clarity and reuse.
6. If a Pest test needs to call a helper method defined on the test case for abstract-class scenarios, use test()->methodName().
7. Keep tests structured and easy to read, preferably with clear arrange / act / assert flow.
8. Separate success and failure scenarios into distinct test cases where practical.
9. Run the rewritten tests and confirm they pass consistently.
10. Simplify nearby similar tests only when the cleanup is small, safe, and clearly improves maintainability.