A test can execute every branch and still accept the wrong answer. Mutants help you find where that happens.
Mutation testing evaluates a test suite by changing application code and checking whether tests reject the change. A passing suite can execute a refund calculation without checking the refund amount. Mutating that calculation gives you a specific question to investigate. Stryker's introduction to mutation testing explains this relationship between code coverage and fault detection.
All code, scenarios, commands, and score calculations here are hypothetical illustrations, not executed experiments or measured results. Adapt them to your repository and installed tool versions.
Start with rules whose failure would matter to a customer or operator. Permission checks and monetary boundaries usually deserve attention before decorative strings. The useful output is a clearer assertion attached to a requirement, with enough evidence to explain why a surviving change matters.
Mutation operators and the changes they challenge
Change one behavior at a time
A mutant is a version of the program with one small syntactic change active. For example, changing balance >= amount to balance > amount challenges whether a withdrawal may consume the full balance. Stryker's supported mutators include comparison boundary changes, arithmetic substitutions, and emptied blocks. One edit can affect several downstream behaviors.
If a relevant test fails, the mutant is killed. If all executed tests pass, it survives. Survival invites investigation into inputs, assertions, and whether tests execute the changed implementation. It does not establish that the original implementation contains a customer bug.
A mutation testing example at a refund boundary
Consider canRefund = (requested, remaining) => requested <= remaining, with validated nonnegative integer cents. A test calling canRefund(500, 1000) exercises the comparison. An assertion that the result is defined accepts both boolean answers. Even an assertion expecting true misses the boundary mutant when requested and remaining differ.
Specify the contract independently. A refund equal to the remaining amount is allowed; a refund one cent greater is rejected. Check expect(canRefund(1000, 1000)).toBe(true) and expect(canRefund(1001, 1000)).toBe(false). Those expectations distinguish the boundary behavior without copying the comparison into the test. Keep negative amount validation in its own cases, wherever the public contract owns that validation.
Treat that unit test as one layer of evidence. At the service boundary, create an account with a known remaining refund balance, submit the allowed request, and read the resulting ledger independently. Submit an excessive request against a fresh fixture and verify that it creates no refund entry. This distinguishes a correct decision from a service that computes the right answer and still writes incorrect state.
Name tests after the policy they protect. When tests fail under mutation, the failure message should identify the input and expected outcome. Avoid calculating the expected refund by invoking the same helper as the application. Shared faulty arithmetic can make source code and test agree. Review test coverage alongside those observations to locate paths still missing from the suite.
Build a repeatable mutation testing workflow
Review each change against a business rule
Choose meaningful code
Select a small module with observable consequences and fast deterministic tests. Write down its input constraints and failure policy before running a tool. For refunds, include the permitted amount, currency units, and whether rejection must leave the ledger untouched. A predicate test cannot establish transaction atomicity.
Run the unchanged suite repeatedly and investigate intermittent failures first. Control clocks and random seeds where appropriate. Await asynchronous assertions and give every case independent fixtures. A flaky test can kill an unrelated mutant and make the report look reassuring for the wrong reason. Record the source revision and test command with the baseline.
Investigate survivors
Open the changed expression, identify the tests that reached it, and state which input would produce a different observable result. Check the exact boundary first. For a survivor replacing logical AND with OR, try a caller satisfying only one permission requirement. Verify both denial and the absence of a protected write.
If almost everything survives, verify imports before adding cases. Stryker's troubleshooting guide documents alias setups that execute the original source outside the sandbox. A suite targeting old build output can create a similar diagnostic problem. Confirm the test process loads the instrumented application code.
Strengthen assertions
Add the smallest case that expresses the missing requirement. For a rejected refund, assert the rejection category and unchanged balance through the public interface. A mock called once says little about the persisted amount. Choose a database integration test when durable state is the behavior you need to observe.
Run the ordinary suite, then rerun the affected mutants. Read the killing failure to confirm it identifies the intended violation. Preserve the case through refactoring by asserting the contract's result or side effect. Assertions about private helper order should have a documented behavioral reason. Otherwise they can reject harmless refactors while leaving the business outcome weakly specified.
Introduce Stryker into a JavaScript or TypeScript project
Keep setup small and inspectable
Stryker's getting started instructions use npm init stryker@latest, followed by npx stryker run. Run initialization only in your intended development checkout, inspect its generated configuration, and review dependency changes. Retain a lockfile so CI uses the reviewed versions.
For an existing Vitest project, install the compatible @stryker-mutator/vitest-runner development dependency and select testRunner: "vitest". The Vitest runner documentation says the plugin uses your project's Vitest installation. Check its peer requirements before selecting versions. This setup assumes tests import the selected source module.
The configuration file guide supports an exported object in stryker.config.mjs. A compact starting object is export default { testRunner: "vitest", mutate: ["src/refunds.ts"], reporters: ["clear-text", "html"], concurrency: 2, thresholds: { high: 80, low: 60, break: null } };. Replace the source path with your owned module. The numbers are example policy choices.
Establish the instrumented baseline
Run npx stryker run --dryRunOnly first. It executes the initial tests with instrumentation present and mutants inactive. Then run npx stryker run for mutation analysis. In the StrykerJS configuration reference, high and low control report colors; break controls failure below the configured score. A null break disables score based build failure. Set an agreed numeric break only after reviewing a trustworthy baseline.
For TypeScript, a separate normal typecheck remains useful. The optional TypeScript checker checks mutants and marks type invalid changes CompileError. Decide whether that filtering fits your project and record the decision, because changing checker settings changes the population you compare.
Calculate the mutation score with its denominator
Account for every outcome
Stryker's mutant states and metrics define detected as killed plus timeout, and valid as detected plus survived plus no coverage. The overall mutation score is detected divided by valid, multiplied by 100. No coverage means tests did not reach the mutant. Compile errors, runtime errors, ignored mutants, and pending work do not enter that valid denominator. The covered code score uses a different denominator that omits no coverage.
For illustration, 70 killed, 5 timeouts, 15 survivors, and 10 without coverage produce 75 detected out of 100 valid mutants, or 75%. Another 8 compile errors do not change that calculation. Read the counts with the percentage and confirm your tool's definitions before comparing reports.
Inspect unexpected timeouts despite their detected classification. A genuine infinite loop and an overloaded worker need different responses. Runtime errors deserve investigation too, especially when a large invalid population shrinks the denominator. Keep incomplete runs visibly incomplete; a partial score cannot establish that the intended scope finished.
Review equivalent mutants without chasing perfection
An equivalent mutant preserves observable behavior throughout the relevant input domain. Failure to find a distinguishing input alone does not prove equivalence. Review the domain constraints and the transformation together. Include those assumptions in the review so a future expansion of allowed inputs can reopen the decision.
Stryker's equivalent mutant explanation acknowledges that it cannot definitively identify and ignore all such changes. A universal 100% target can reward unnecessary tests or exclusions. Accept a documented survivor when the evidence supports it, and keep consequential unexplained survivors visible.
The disable mutants guide supports scoped comments naming a mutator and a reason. Use narrow exclusions only after review. Disabling every comparison mutation because one is equivalent hides other boundary gaps. Record scope changes alongside score trends so removing difficult code cannot masquerade as better assertions.
Keep execution isolated and CI feedback affordable
Give parallel workers independent resources
Run mutation analysis locally or in disposable CI environments, never against production services. Tests that send email, charge a payment method, or write shared customer state need safe substitutes or isolated fixtures before any mutant executes. A mutated guard can activate a path that ordinary fixtures never reached.
The parallel workers documentation explains that Stryker forks worker processes and that its sandbox does not isolate their shared files. Use worker specific database namespaces, temporary directories, and allocated ports. The example concurrency of two limits worker count; it cannot prevent resource collisions. Lower concurrency while diagnosing contention and inspect memory use before increasing it.
Combine focused runs with broader checks
In CI, scope pull request jobs to affected modules for fast review. Retain a broader nightly run to catch gaps outside that scope. Treat a changed files list as a starting point and include callers or shared policies when the change can affect their behavior. Keep ordinary tests required independently.
Stryker's incremental mode documentation describes npx stryker run --incremental and reuse through reports/stryker-incremental.json. It tracks mutated code and test changes, with runner dependent limits. Dependency updates, environment changes, and other configuration changes can escape detection. Use npx stryker run --incremental --force to rerun all mutants in the selected scope when those assumptions change.
Retain the report, selected paths, exclusions, tool versions, and sanitized failure details as review evidence. Put a job deadline around the run and distinguish cancellation from completed analysis. A score trend is useful only when readers can understand changes in scope and execution policy.
Review mutation testing results across release checks
Use the contract testing guide when a survivor exposes uncertainty about a consumer's expected response. The API rate limit testing guide develops retry boundaries that often need precise state assertions. Browser journeys in the Playwright testing guide add evidence about whether users can complete the resulting flow.
For the human side, create a BetaRoast feedback round against a safe hosted build. Ask people whether a rejected refund explains what happened and how to proceed. BetaRoast collects human feedback; it does not generate mutants or automatically evaluate assertion strength. Turn reproducible observations into explicit requirements and regression cases.
Frequently asked questions
Does full coverage make mutation testing unnecessary?
No. Coverage establishes execution, while a mutant challenges whether a changed result is detected. Keep coverage to find untouched paths and use survivors to investigate weak observations or missing inputs.
Does every surviving mutant need another test?
Investigate first. A survivor can reveal a missing assertion, an incorrect test setup, or equivalent behavior. Add a case when it expresses a meaningful requirement; document justified exceptions with their assumptions.
What mutation score should a team require?
Choose a threshold after reviewing the module's risks, valid mutant population, and existing survivors. Inspect critical rules individually. A strong aggregate percentage can conceal a single untested permission boundary.
Should mutation analysis run on every pull request?
Use it where the runtime budget and module risk justify it. Focus pull request runs on relevant code and retain broader checks. Reevaluate incremental reuse after dependency or configuration changes, and keep reports clear about what actually ran.
Start with consequential business rules, establish a stable baseline, and investigate each survivor against an observable requirement. Use Stryker reports and bounded CI runs to improve assertions while keeping equivalent mutants and infrastructure failures visible.