Stryker Mutation Testing for TypeScript and React: A Practical Guide
Code coverage tells you which lines executed during your tests. It tells you nothing about whether your tests would catch a bug. A test suite with 90% coverage can still miss critical failures — and mutation testing is how you find out.
Stryker is the leading mutation testing framework for JavaScript and TypeScript. This guide focuses specifically on TypeScript and React projects: the configuration quirks, the common mutation operators, and how to interpret results in a frontend codebase.
What Mutation Testing Actually Does
Stryker automatically makes small changes — mutations — to your source code. It then runs your test suite against each mutated version. If your tests catch the change (the mutant "dies"), your tests are doing their job. If your tests pass despite the mutation, you have a surviving mutant: a gap in your test coverage.
Common mutations include:
- Changing
>to>=or< - Replacing
&&with|| - Removing a conditional block
- Negating a return value
- Deleting a function call
If your tests can't catch these changes, they won't catch real bugs either.
Installing Stryker in a TypeScript Project
Start with the Stryker CLI:
npm install --save-dev @stryker-mutator/core @stryker-mutator/typescript-checkerFor React projects using Jest:
npm install --save-dev @stryker-mutator/jest-runnerInitialize the config:
npx stryker initThis creates stryker.config.json (or .mjs if you prefer ES modules).
Configuring Stryker for TypeScript
A working config for a TypeScript React project:
{
"$schema": "./node_modules/@stryker-mutator/core/schema/stryker-schema.json",
"testRunner": "jest",
"jest": {
"projectType": "create-react-app"
},
"checkers": ["typescript"],
"tsconfigFile": "tsconfig.json",
"mutate": [
"src/**/*.ts",
"src/**/*.tsx",
"!src/**/*.test.ts",
"!src/**/*.test.tsx",
"!src/**/*.spec.ts",
"!src/**/*.spec.tsx",
"!src/index.tsx",
"!src/setupTests.ts"
],
"reporters": ["html", "clear-text", "progress"],
"coverageAnalysis": "perTest",
"thresholds": {
"high": 80,
"low": 60,
"break": 50
}
}Key settings:
- checkers: typescript — skips mutants that would cause TypeScript compilation errors, saving time
- coverageAnalysis: perTest — only runs tests that cover a mutated line, dramatically faster
- mutate — exclude test files and entry points from mutation
Understanding TypeScript-Specific Behavior
Type-Aware Mutation
The TypeScript checker is important. Without it, Stryker generates mutants that TypeScript would reject at compile time — useless work that slows down your run. With the checker enabled, Stryker filters these out before running tests.
Example: if you have a function typed to return string, Stryker won't generate a mutant that returns undefined without the TypeScript checker, but with it, such invalid mutants are pruned early.
React Component Mutations
For React components, Stryker mutates the logic inside your components, not JSX structure. Common survivors in React code:
Conditional rendering gaps:
// Original
{isLoading && <Spinner />}
// Mutant: removes the condition
{<Spinner />}If your tests don't assert that the spinner is absent when isLoading is false, this mutant survives.
Event handler gaps:
// Original
<button onClick={handleSubmit} disabled={!isValid}>Submit</button>
// Mutant: negates disabled
<button onClick={handleSubmit} disabled={isValid}>Submit</button>If you only test that the button is clickable when valid, but not that it's disabled when invalid, the mutant survives.
Running Stryker
Basic run:
npx stryker runFor large projects, limit scope during development:
npx stryker run --mutate "src/components/checkout/**"Stryker outputs an HTML report at reports/mutation/mutation.html. Open it to see exactly which mutants survived and where.
Reading the HTML Report
The HTML report shows your files with color-coded lines:
- Green: mutants killed (tests caught the change)
- Red: mutants survived (tests missed the change)
- Grey: no coverage (no tests ran against this code)
- Yellow: timeout (tests hung — often indicates infinite loop potential)
Click any survived mutant to see the exact change Stryker made. This is your actionable list.
Fixing Surviving Mutants in React
Pattern 1: Missing Negative Assertions
You test that something appears. You don't test that it disappears.
// Survivor: removes the && condition
{hasError && <ErrorMessage message={error} />}
// Fix: add a test for the absent state
test('does not show error when hasError is false', () => {
render(<Form hasError={false} error="" />);
expect(screen.queryByRole('alert')).not.toBeInTheDocument();
});Pattern 2: Boundary Condition Gaps
// Original
function isOverBudget(amount: number, budget: number): boolean {
return amount > budget;
}
// Mutant: changes > to >=
// Survivor if you only test amount=150, budget=100 (both return true)
// Fix: add test at the exact boundary
test('returns false when amount equals budget', () => {
expect(isOverBudget(100, 100)).toBe(false);
});Pattern 3: Boolean Logic Gaps
// Original
const canCheckout = isAuthenticated && cartHasItems && !isProcessing;
// Mutant: changes && to ||
// Survivor if you only test the "all true" path
// Fix: test each condition independentlyPerformance Optimization for Large Projects
Stryker can be slow on large TypeScript codebases. Use these strategies:
Incremental mode (Stryker 7+):
{
"incremental": true,
"incrementalFile": ".stryker-tmp/incremental.json"
}Only re-runs mutants in files that changed since the last run. Essential for CI.
Limit mutation operators:
{
"mutator": {
"excludedMutations": ["StringLiteral", "ObjectLiteral"]
}
}Removing string and object mutations speeds up runs significantly with minimal quality impact.
Parallel workers:
{
"concurrency": 4
}Match this to your CI runner's CPU count.
CI Integration
Add to your GitHub Actions workflow:
- name: Mutation Testing
run: npx stryker run
env:
CI: true
- name: Upload Stryker Report
uses: actions/upload-artifact@v3
if: always()
with:
name: mutation-report
path: reports/mutation/To enforce a minimum mutation score, set thresholds.break in your config. If the score drops below this value, Stryker exits with a non-zero code, failing the CI build.
A reasonable threshold progression:
- Week 1: set break at your current score minus 5
- Month 1: raise break to current score
- Ongoing: raise by 2-3 points per sprint
Don't try to jump from 40% to 80% overnight — you'll create pressure to write bad tests just to kill mutants.
Connecting to Continuous Quality Monitoring
Mutation testing tells you where your tests are weak. But a mutation score snapshot once a week isn't the same as knowing your application is working right now.
HelpMeTest complements mutation testing with continuous end-to-end monitoring. Where Stryker finds gaps in your unit test coverage, HelpMeTest runs your actual user flows 24/7 — catching failures that no amount of unit test quality can prevent, like API changes, infrastructure issues, or third-party service failures.
Use both: Stryker to maintain test suite quality, HelpMeTest to monitor your live application.
What to Expect
A TypeScript React project with no prior mutation testing work typically starts at 30–50% mutation score. Anything above 70% is solid. Above 85% is excellent, but diminishing returns set in — the remaining mutants are often in error handling paths or defensive code that's hard to trigger.
The goal isn't a perfect score. The goal is finding the untested logic that would matter if it broke — and writing targeted tests for those gaps.
Start with your business-critical components: checkout flows, auth logic, data transformations. Fix surviving mutants there first.