| name | mutation-testing |
| description | Run and interpret Stryker mutation testing results. Use ONLY when the developer explicitly asks for mutation testing or when a plan phase includes it. Do NOT use proactively. |
Run Stryker mutation tests and interpret survived mutants to improve real test
coverage — without adding shallow structure-pinning tests.
Purpose: Validate that unit tests exercise module logic after extract/refactor,
or compare integration coverage vs mutation kill rate on pure/narrow modules.
Output: Mutation run results + interpretation + summary ending with
## MUTATION TEST COMPLETE.
**Use only when:** the developer explicitly asks for mutation testing, or a
plan phase includes it. **Do not use proactively.**
Current scope: cli/ only. Later: reuse in frontend/, mcp-server/.
Git does not use the Nix prefix. All other repo tooling does:
CURSOR_DEV=true nix develop -c …
Policy on survived mutants: A survived mutant means no test executes that
branch — or the code is dead/unreachable. Do not automatically add
tests. First consider delete dead path, merge redundant logic, or prove the
code is still required from product/domain behavior.
Do not add shallow tests that reach into inner structure, call
non-entry-point helpers, or assert on internal state just to flip Stryker green.
Do add or extend coverage by driving a high-level entry point
(controller, mounted page, runInteractive, real CLI). Assert only what a user
or integrator can observe: HTTP response, CLI stdout, DOM, black-box
inputs/outputs.
Pure helpers (inputs → result, no hidden globals) may keep direct-import
black-box tests only when that API is the intentional stable contract.
If a good observable test is hard to compose, ask the developer whether the
mutated code deserves to exist.
```bash
CURSOR_DEV=true nix develop -c bash -c 'cd cli && pnpm test:mutation'
```
For each survived mutant, apply the policy above: delete, merge, prove
necessity, or add observable entry-point coverage — never shallow
structure-pinning tests.
| Piece | Role |
|-------|------|
| `devDependencies` | `@stryker-mutator/core`, `@stryker-mutator/vitest-runner` |
| `stryker.conf.mjs` | Must set `plugins: ['@stryker-mutator/vitest-runner']` |
| `vitest.stryker.config.ts` | Dedicated Vitest config for mutation runs |
| `.gitignore` | `.stryker-tmp/`, `reports/mutation/`, `stryker-setup-*.js` |
- **`vitest.related`** — Vitest may skip tests that reach mutated code
indirectly. Fix: `vitest: { related: false }` in `stryker.conf.mjs`.
- **`mergeConfig` + `test.include`** — Can union includes so Stryker runs too
many tests. Fix: standalone `vitest.stryker.config.ts` with only the
relevant tests.
- **`coverageAnalysis: 'perTest'`** — Can show no effective coverage on ESM
setups. `coverageAnalysis: 'off'` with a small test set is acceptable.
1. Add devDependencies and `stryker.conf.mjs` (adjust `mutate`,
`vitest.configFile`).
2. Point `vitest.stryker.config.ts` at only tests that import mutated sources.
3. Add ignore block to that package's `.gitignore`.
4. Wire a root/package script with the Nix prefix.
<success_criteria>
- Mutation run executed with Nix prefix (
cli/ scope unless extending)
- Survived mutants interpreted per policy (no auto shallow tests)
- Developer consulted when observable coverage is hard to compose
- Final output includes
## MUTATION TEST COMPLETE
</success_criteria>
Report mutation results, survived-mutant decisions, and any recommended
follow-ups, then:
## MUTATION TEST COMPLETE
<out_of_scope>
- Do not run proactively without explicit developer or plan request.
- Do not add tests that only pin internal structure to kill mutants.
- Do not extend beyond
cli/ unless following extend_to_subproject.
</out_of_scope>
