# Mutation Testing

> Uses mutation testing to measure test effectiveness and close gaps that coverage alone misses. Use this skill when evaluating whether tests would catch real faults, tuning Stryker, or improving weak suites after green coverage. Do not use when/for writing the first tests (use writing-tests) or load/chaos testing (use performance-testing).

- Skill: `jagreehal/mutation-testing` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add jagreehal/mutation-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/mutation-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/mutation-testing

---


# Mutation Testing

## Critical rules

- Coverage = execution. Mutation = **detection**. Prefer **Stryker** over manual mutation for JS/TS.
- Run at the **PR-readiness / end-of-phase gate** — never inside each RED-GREEN increment.
- Diff-scoped runs for branches; full runs for setup, CI, or baseline work.
- Mutate **production source only** — never tests, fixtures, snapshots, generated, `.d.ts`, build output.
- Every survivor: kill with a behavior test, classify equivalent, or ask the user.
- New tests must **fail against the mutant for the right reason** before restoring production code.
- Assert exact observable behavior — not `toBeDefined` / weak inequalities.
- Before operators, survivors, or WRONG/CORRECT examples, read the matching resource below.

## Workflow

1. **Inspect** — Find package manager, runner, Stryker config; `git diff <base>...HEAD --name-only`. Monorepo: smallest affected package first.
2. **Setup if missing** — `npm init stryker@latest`; Vitest plugin; `coverageAnalysis: perTest`; mutate `src/**/*.ts` excluding tests. Add scripts: `mutation`, `mutation:incremental`, `mutation:diff`. Before editing config details, read [references/setup.md](references/setup.md).
3. **Run** — Prefer `mutation:diff` for branch feedback. Full `mutation` for first setup / shared infra / CI gates.
4. **Triage** — Killed: ok. Survived: strengthen the assertion **or** change the input (equal original/mutant results for the current input means no assertion can kill it), unless equivalent. No Coverage: add behavior test. High-value code (money, permissions, safety): fix immediately. Subtle/unspecified: ask user with concrete choices.
5. **Kill survivors (TDD)** — Keep mutant → write smallest failing behavior test → restore code → verify pass → re-run scoped mutate then diff. Assert returns, persisted state, events — not implementation details.
6. **CI** — Start report-only; add failing thresholds after a baseline. Persist HTML/clear-text artifacts. Incremental locally; force full periodically.

During RED (cheap): use mutator heuristics mentally — see [references/mutator-rules.md](references/mutator-rules.md). Manual fallback only when Stryker can't target the code.

## Resources

- [references/mutator-rules.md](references/mutator-rules.md) — operators, heuristics, equivalent mutants, manual procedure. Read when planning tests or triaging survivors.
- [references/setup.md](references/setup.md) — Stryker config, scripts, diff scoping. Read when adding or tuning the harness.
- [references/examples.md](references/examples.md) — weak coverage vs boundary-killing tests. Read when strengthening survivors.

## Validation

- [ ] Harness is Stryker (or documented manual fallback)
- [ ] Run timed at PR gate, not per TDD increment
- [ ] Diff-scoped for the branch; mutate production only
- [ ] Survivors killed, marked equivalent, or escalated to user
- [ ] Killer tests failed against the mutant first; assert exact behavior

## Constraints

- Not for authoring first tests (`writing-tests`) or load/chaos (`performance-testing`).
- Adjacent: `tdd-workflow` (cycles before this gate), `testing-strategy` (pyramid placement), `verification-before-completion` (include mutation report in evidence).