From atdd
Runs mutation testing to verify tests catch bugs by introducing mutants into code and checking if tests fail. Extends ATDD workflow as third validation after green acceptance and unit tests.
npx claudepluginhub swingerman/atdd --plugin atddThis skill uses the workspace's default tool permissions.
Add a third validation layer to the ATDD two-stream testing approach.
Runs mutation testing on test suites using stack-specific tools like Stryker (JS), Infection (PHP), Mutmut (Python), and go-mutesting (Go) to validate test quality. Use for verifying test effectiveness.
Runs mutation tests with Stryker, mutmut, PITest, or go-mutesting to evaluate test suite effectiveness by generating code mutants and verifying test detection. Identifies gaps in test coverage.
Runs mutation testing workflow: mutates source code, executes tests per mutation, identifies survivors, generates tests for them, commits per module. Multi-session progress tracking in .test-mutations.json.
Share bugs, ideas, or general feedback.
Add a third validation layer to the ATDD two-stream testing approach. Acceptance tests verify WHAT, unit tests verify HOW, mutation testing verifies that the tests actually catch bugs.
Mutation testing introduces deliberate bugs (mutants) into source code, then runs the test suite. If tests fail, the mutant is killed (good). If tests pass despite the bug, the mutant survives (test gap found).
Source code → introduce mutation → run tests
├── tests FAIL → mutant killed ✓
└── tests PASS → mutant survived ✗
A project with 100% code coverage can still have a 60% mutation score — meaning 40% of introduced bugs go undetected by the test suite.
Run mutation testing after both test streams are green:
This is Phase 6 in the team-based ATDD workflow, or a standalone quality check at any point during development.
The preferred approach is to build a custom mutation tool for the project. This follows the methodology Uncle Bob developed for empire-2025 — a project-specific tool that walks the AST/source tree, applies one mutation at a time, runs targeted tests, and reports survivors.
+ → -, true → false,
>= → >) plus matching logic that walks the AST/form tree| Category | Examples |
|---|---|
| Arithmetic | + ↔ -, * ↔ /, ++ ↔ -- |
| Comparison | > ↔ >=, < ↔ <= |
| Equality | == ↔ != |
| Boolean | true ↔ false, && ↔ ` |
| Conditional | negate conditions, swap if/if-not |
| Constant | 0 ↔ 1, "" ↔ "mutant" |
| Return value | return true → return false |
| Void method | remove method call entirely |
For the full architecture and detailed reference, see
references/frameworks.md.
When speed of setup is more important than tight integration, use an established mutation framework as a secondary option:
| Language | Framework |
|---|---|
| JavaScript/TypeScript | Stryker |
| Python | mutmut |
| Java/JVM | PIT (pitest) |
| C# | Stryker.NET |
| Rust | cargo-mutants |
| Go | go-mutesting |
| Ruby | mutant |
| Scala | Stryker4s |
For install commands, configuration, and CLI reference, see
references/frameworks.md.
Before running mutation testing, confirm:
If no mutation tool is configured:
generated-acceptance-tests/ and acceptance-pipeline/ from mutationImportant: Configure mutation testing to target source code only. Never mutate test files, spec files, or generated pipeline code.
Execute the mutation framework and collect results:
For each surviving mutant:
>= → >, removed function call)Equivalent mutants are mutations that don't change observable behavior
(e.g., changing x = x + 0). These can be ignored.
For each real survivor:
Present a summary:
Mutation Testing Report
═══════════════════════
Score: 87% → 95% (after killing survivors)
Killed: 190 / 200
Survived: 10 → 5 (5 equivalent mutants ignored)
New tests: 5 unit tests added
Remaining survivors (equivalent mutants):
- src/utils.js:42 — changed `x + 0` to `x + 1` (no-op mutation)
- ...
| Score | Assessment |
|---|---|
| 90%+ | Strong test suite — minor gaps only |
| 70-89% | Moderate — meaningful gaps to address |
| < 70% | Weak — significant untested behavior |
A 100% mutation score is not always practical or necessary. Focus on killing mutants that represent real behavioral gaps, not chasing equivalent mutants.
Mutation testing extends the existing two-stream approach:
1. Write specs (WHAT) ← acceptance tests
2. Implement with TDD (HOW) ← unit tests
3. Verify test quality (REAL?) ← mutation testing
When using the atdd-team skill, mutation testing is Phase 6:
assign to the reviewer or implementer after post-implementation
review passes.
No. Fix failing tests first. Mutation testing assumes a green baseline.
Not practical. Equivalent mutants inflate the denominator. Aim for 90%+ and document the equivalent mutants that remain.
Never mutate generated test files or the acceptance pipeline. Only mutate source code under development.
For detailed framework setup and configuration:
references/frameworks.md — Installation, configuration, and CLI
reference for each supported mutation testing framework