laravel-pest
Use when a Laravel project already runs Pest and the task goes past plain tests: architecture tests, datasets, mutation testing, type coverage, parallel runs and sharding, and picking a named assertio
SKILL.mdskills/laravel-pest/SKILL.md
GitHublaravel-pest
Step 5 (tdd) of the pipeline (WORKFLOW.md), the Pest-specific half of skills/laravel-conventions §9
(tests and static analysis). It assumes the project already uses Pest: the choice of runner is a project
decision (some houses are PHPUnit-only, and then this block does not apply).
Special status. New block, 🟡: never run on real work in house. Re-checked on 2026-10-20 against the
documentation repository's 5.x branch (its default branch). Pest majors move fast (Pest 5 is dated 2026-07-28
in its support policy); confirm against the installed major (skills/source-freshness).
When
A tests/Pest.php, an arch() expectation, a ->with(...) dataset, a --mutate or --type-coverage run,
CI sharding, or a test suite that is slow or order-dependent.
Steps
- Check the major against PHP. The support policy ties each major to a minimum PHP (at the reading: Pest 5 needs 8.4, Pest 4 needs 8.3, Pest 3 needs 8.2) and gives bug fixes for the previous major for twelve months after the latest release (support policy page, 5.x branch; the older 3.x-era branch said two years, so read the branch that matches the installed major). A project below the line upgrades the runner or stays on its major; it does not mix.
- Architecture tests state conventions as code.
arch()->expect('App\Models')->toExtend(...),->not->toUse(['die', 'dd', 'dump']),->toOnlyBeUsedIn(...),toUseStrictTypes(),toBeFinal(),toHaveSuffix(),toHaveLineCountLessThan(). This is howskills/code-baseline§8's "name the enforcing line" is done for a layering rule: a direction that must hold (a low layer never importing a higher one,skills/laravel-conventions§10) becomes a failing test, not a sentence. Wildcards (App\*\Traits) arrived in 3.8. - Presets are a starting set, not the rule.
php,security,laravel,strict,relaxedand a custom preset a team defines. Read what a preset enforces before enabling it (thestrictpreset makes classes final, which conflicts with a house that extends); useignoring()for a named exception with a reason (own guidance: the reason). Thelaravelpreset expects controllers to expose only the seven conventional resource methods as public methods and to carry theControllersuffix. - Datasets replace copy-pasted tests. Key a dataset so the test name says which case failed; use named
keys so parameters bind by name regardless of order; closures in datasets need typed test arguments;
shared datasets live in the datasets directory; a dataset that needs the database is a bound dataset
(closures resolved after
beforeEach), with a typed parameter. One test per behaviour, many rows: not one row per test. - Mutation testing measures whether tests would notice a change. Declare what a test covers with
covers()ormutates(), run--mutate(add--parallel), read eachUNTESTEDdiff, and write the assertion that kills it (a status check that never looked at the body is the typical survivor). Needs Xdebug 3 or PCOV. Gate with--min=<score>; exclude lines that are noise with the ignore annotation rather than lowering the bar. It is a review tool for the tests the diff added, not a number to chase across a legacy suite (skills/code-baseline§0). - Type coverage checks declarations, not tests. The plugin's
--type-coveragewith--minfinds parameters, returns and properties missing a type; the ignore annotation is for a line the language cannot type. It complements the static analyser (skills/laravel-larastan), it does not replace it. - Parallel and sharded runs need independent tests. Each process gets no shared database state and no
order guarantee; a test that depends on another test's data fails only in parallel.
--profilenames the slowest tests before anyone parallelises. In CI, time-balanced--sharduses a committed timing file that--update-shardsregenerates; a stale file still runs every test, with a warning. - Pick the assertion for the subject. A response gets a named response assertion (
assertNotFound(), notassertStatus(404)), a database fact a database assertion, a model's existenceassertModelExists, a plain value anexpect()chain; one chain per subject; the expected value is written in the test, never computed with the code under test. A write is asserted completely: response, stored state, dispatched jobs and events, sent mail and notifications, and on the failure path that none of them happened. Confirm an expectation exists in the documentation before using it. - A skipped or todo test is a visible debt, never a way to turn a build green (a check that runs on every edit can refuse them).
Output / checkpoint
New tests use named assertions and datasets where rows repeat; a layering rule that matters is an arch()
expectation; the diff's new behaviour survives --mutate on its own tests when the project runs mutation
testing. Checked at gate (7).
Guardrails
No comments in the code produced. Never edit a mutation or coverage threshold as a side effect. Do not add
Pest, a plugin or a preset to a project that did not choose it; name the dependency and stop
(CONVENTIONS.md).
Origin
Rewritten from the Pest documentation repository (pestphp/docs, MIT, LICENSE read 2026-10-20, 5.x branch):
architecture testing (expectations, presets, ignoring(), wildcards since 3.8), datasets (keys, parameter
binding by name, typed closure arguments, tests/Datasets, bound datasets), mutation testing (covers() and
mutates(), --mutate, --parallel, --min, @pest-mutate-ignore, Xdebug 3 or PCOV), type coverage (a
separate plugin; --type-coverage, --min, @pest-ignore-type), optimizing tests (--parallel, --profile,
--shard, tests/.pest/shards.json, --update-shards) and the support policy table; and the
testing-best-practices rule files of Laravel Boost (laravel/boost, MIT, LICENSE read 2026-10-20) for named
assertions, known-value assertions and complete-result assertions. Every figure in steps 1 to 8 was re-opened
and matched on 2026-10-20. Own guidance, not a documentation statement: step 6's "complements the static
analyser", step 9 (skipped and todo tests, absent from both sources), and the advice to confine mutation runs
to the diff's tests. Mechanisms only, rewritten in our words.
Independent verification 2026-10-21: 16 checked, 16 matched, 0 corrected, 0 unverified.