stryker-mutation
Overview
Per stryker-intro:
"Stryker started as a pure JavaScript mutation testing
framework" and now "supports most JavaScript projects, including
TypeScript, React, Angular, VueJS, Svelte, and NodeJS."
Mutation testing introduces small bugs (mutants) into the production
code; if tests still pass, the test suite is too weak. A green
suite with high mutation-survival rate is the bug coverage hides.
When to use
- A JS/TS suite has ≥80% line/branch coverage and the team wants
to verify assertions actually catch bugs.
- Code review keeps surfacing weak assertions in tests
(
.toBeTruthy() etc); mutation testing makes the cost visible.
- A critical module needs a higher quality bar than coverage alone
proves.
Step 1 - Install
npm install --save-dev \
@stryker-mutator/core \
@stryker-mutator/jest-runner # or mocha-runner / vitest-runner / etc.
Per stryker-intro, supported runners include Jest, Mocha,
Karma, Vitest, Jasmine, Cucumber, Tap.
Step 2 - Initialize
npx stryker init
Generates stryker.conf.json:
{
"$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
"packageManager": "npm",
"reporters": ["progress", "clear-text", "html"],
"testRunner": "jest",
"coverageAnalysis": "perTest",
"mutate": ["src/**/*.ts", "!src/**/*.test.ts"],
"thresholds": { "high": 80, "low": 60, "break": 50 }
}
Key fields:
| Field | Use |
|---|
mutate | Glob patterns: which files to mutate; exclude tests + types. |
testRunner | jest / mocha / vitest / karma / etc. |
coverageAnalysis | perTest (fastest - only re-run tests that touched the mutated line). |
thresholds.break | Mutation score below this → npx stryker run exits non-zero (CI gate). |
incremental | true to only mutate files changed since last run. |
concurrency | Worker count (default = CPU count). |
Step 3 - Run
npx stryker run
Per-mutant output:
[Survived] Conditional Boundary
src/cart.ts:42:5
- if (item.qty < 0) throw new Error(...);
+ if (item.qty <= 0) throw new Error(...);
Tests run: 12 (all passed - mutant survived).
Survived mutant = tests passed despite the introduced bug =
the tests don't actually catch this regression. Add a test for
qty = 0.
Step 4 - Report + threshold
Ran 142 tests.
Mutants killed: 198
Mutants survived: 24
Mutants timed out: 3
Mutants no coverage: 12
Mutation score: 84.7%
Per stryker-intro: thresholds via the thresholds object
gate the build:
>= high (80) → green.>= low (60) → yellow.< break (50) → red, exit code != 0.
The HTML report shows per-file mutation breakdown - drill in to
see which mutants survived and where to add tests.
Step 5 - Incremental mode for PR runs
Full mutation runs are slow (5-30 min on medium codebases). For
PRs, incremental mode only mutates changed files:
npx stryker run --incremental
This stores state in .stryker-tmp/ (commit to git so subsequent
runs benefit). Per-PR runs typically complete in <2 min.
Step 6 - CI integration
- name: Mutation testing (changed files only)
if: github.event_name == 'pull_request'
run: npx stryker run --incremental
- name: Full mutation run
if: github.ref == 'refs/heads/main' && github.event.schedule == '0 2 * * 0'
run: npx stryker run
- uses: actions/upload-artifact@v4
if: always()
with:
name: stryker-report
path: reports/mutation/
Pattern: incremental on PRs (fast feedback) + full weekly run on
main (catches drift in unchanged code).
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
Setting break: 100 | Impossible bar; team disables. | Start at 50-60; ratchet up over time. |
Running on every PR without --incremental | 30-min PR feedback loop; team disables. | --incremental for PRs (Step 5). |
| Mutating test files | Mutants in test code don't reflect production quality. | Exclude in mutate glob (Step 2). |
| Ignoring "no coverage" mutants | Files in mutate glob without any test coverage; mutation testing wastes effort. | Either add tests OR exclude those files from mutate. |
Using coverageAnalysis: off | Re-runs entire suite per mutant; very slow. | perTest (the default; Step 2). |
| Hard-coding break threshold without team agreement | Fails surprise PRs; team disables. | Land threshold via PR with team review. |
Limitations
- Slow for large codebases. Even with incremental + perTest,
mutation testing scales worse than test execution.
- Surviving mutants don't always indicate weak tests - some
are equivalent mutants (semantically identical to the original);
flag and exclude these.
- TypeScript checking adds time. Disable type-check (
tsconfig.tsbuildinfo)
for mutation runs if not needed.
- Per-runner integration quality varies. Jest is the most
mature; Vitest / Karma have known edges.
References
- si - StrykerJS overview, supported test runners, supported
frameworks (TS / React / Angular / Vue / Svelte / Node).
stryker-net-mutation -
.NET sibling.pitest-mutation - Java sibling.mutmut-mutation - Python sibling.mull-mutation - C/C++ sibling.