Mutation testing in TypeScript and JavaScript

Why 100% coverage can still mean untested

Coverage measures which lines ran during the tests, not whether the tests checked the result. That gap matters more now, because AI coding agents are very good at producing tests that execute code and very inconsistent at asserting what it should do.

Here is a small function and the kind of test an agent often writes for it:

export function canCreateProject(plan: "free" | "pro", existing: number): boolean {
  if (plan === "pro") return true;
  return existing < 5;
}

it("enforces the free plan limit", () => {
  expect(canCreateProject("free", 2)).toBe(true);
  expect(canCreateProject("pro", 50)).toBe(true);
});

Every line and both branches run, so coverage reports 100%. But the test never checks the one thing its name promises: that a free user with five projects is refused. Change existing < 5 to existing <= 5, or to true, and the test still passes.

How mutation testing works

1. The tool parses your source and finds places it can make a small change.
2. Each change produces a mutant: a copy of the program with one deliberate bug.
3. The tests run against each mutant.
4. A mutant that makes at least one test fail is killed. A mutant that every test tolerates survived.

How to read a mutation score

The mutation score is the share of mutants your tests detected. In StrykerJS’s definition, detected mutants are those killed or timed out, and the score is detected divided by detected plus undetected (survived or not covered by any test). Mutants that fail to compile or crash the runner are excluded.

StrykerJS’s default thresholds treat 80% or more as high and below 60% as low, and do not fail the build unless you set a break threshold. The number matters less than the list of survivors. Each surviving mutant points at a specific line and a specific missing assertion, which is far more actionable than a coverage percentage.

Running StrykerJS with Vitest or Jest

StrykerJS is the most widely used mutation testing framework for JavaScript and TypeScript. Its setup wizard detects your test runner and installs the matching plugin:

npm init stryker@latest
npx stryker run

A minimal configuration for a Vitest project looks like this:

{
  "testRunner": "vitest",
  "mutate": ["src/**/*.ts", "!src/**/*.test.ts"],
  "incremental": true,
  "thresholds": { "high": 80, "low": 60, "break": 60 }
}

incremental reuses results for code that has not changed, which makes repeated runs much faster. Setting break fails the run when the score drops below that value.

Mutation testing only what the AI changed

A full mutation run on a large codebase can take a long time, because every mutant reruns tests. For AI-generated changes, you usually only need to know whether the tests protect the code that just changed. Pass Stryker the changed files:

CHANGED=$(git diff --name-only main...HEAD -- 'src/*.ts' ':!*.test.ts' | paste -sd, -)
[ -n "$CHANGED" ] && npx stryker run --mutate "$CHANGED"

MaruCheck builds this in. maru mutate --diff finds mutation candidates only in the changed TypeScript files, runs only the tests linked to the affected requirements, and works in a temporary Git worktree so your checkout is never modified. It focuses on the mutations that matter most in AI-written changes: inverted booleans, changed comparisons, removed guards, and removed ownership or permission conditions.

npx --no-install maru mutate --diff --max 8

The unmodified code has to pass first; otherwise the run is reported as inconclusive rather than blaming a mutant. Any survivor is reported as WEAK VERIFICATION DETECTED and blocks the release, with the mutated line and the tests that missed it. See the CLI reference for every option.

When to use mutation testing

• On critical paths such as authorization, billing, and quotas, on every change.
• When an AI agent wrote both the implementation and its tests.
• After an agent edited existing tests. Weakened assertions show up immediately as new survivors. See how agents change tests to make them pass.
• Before trusting a coverage number in a release decision.

Related guides