Add Mutation Testing Launcher

Add Mutation Testing Launcher is a command that scaffolds and configures a complete mutation testing framework for your codebase, including tool installation, operator configuration, CI pipeline integration, and quality gate enforcement. Mutation testing works by introducing small, deliberate faults (mutants) into your source code and then running your test suite to see how many mutants are detected (killed). A high mutation score indicates that your tests are genuinely verifying behavior rather than simply achieving line coverage.

When to Use This Command

Run this command when...

• Your test suite reports high code coverage but you suspect the tests are not actually asserting meaningful behavior and want to validate test quality.
• You are establishing quality gates for a project and need a more rigorous metric than line or branch coverage to enforce testing standards.
• A critical module handles financial calculations, authentication, or data integrity, and you need confidence that every logical path is genuinely tested.
• You want to integrate mutation testing into your CI/CD pipeline so that regressions in test quality are caught automatically before merging.
• Your team is adopting test-driven development and wants a feedback mechanism that reveals weak or missing test assertions.

Consider alternatives when...

• Your project does not yet have a basic test suite in place; write foundational tests first before measuring their effectiveness with mutation testing.
• The codebase is extremely large and mutation testing would take prohibitively long even with optimization; consider running it only on critical modules.
• You are working on a prototype or throwaway code where test quality investment does not justify the setup effort.

Quick Start

Copy
# stryker.conf.yml (JavaScript/TypeScript example)
mutate:
  - "src/**/*.ts"
  - "!src/**/*.spec.ts"
testRunner: jest
reporters: ["html", "clear-text", "progress"]
coverageAnalysis: perTest
thresholds:
  high: 80
  low: 60
  break: 50

Example invocation:

Copy
add-mutation-testing-launcher "typescript with jest and github-actions"

Example output:

Mutation Testing Setup Complete
--------------------------------
Framework:     Stryker Mutator v7.3
Test Runner:   Jest (detected from package.json)
Language:      TypeScript
Mutators:      ArithmeticOperator, ConditionalExpression,
               EqualityOperator, LogicalOperator, StringLiteral

Files Created:
  stryker.conf.yml          - Core configuration
  .github/workflows/
    mutation-testing.yml     - CI pipeline (runs on PR)
  scripts/mutation-report.sh - HTML report generator

Quality Gates:
  Break threshold: 50% (build fails below this)
  Low threshold:   60% (warning issued)
  High threshold:  80% (target for mature modules)

Next Steps:
  1. Run `npx stryker run` locally to establish baseline
  2. Review surviving mutants in the HTML report
  3. Strengthen tests targeting survivors

Core Concepts

Concept	Purpose	Details
Mutant	A deliberately introduced fault in source code	Generated by applying a mutation operator such as replacing + with - or flipping === to !== in a copy of the source file
Mutation Score	Measures test suite effectiveness	The percentage of generated mutants that were detected (killed) by at least one test; higher scores indicate stronger test assertions
Mutation Operator	Defines what types of faults to inject	Categories include arithmetic, relational, logical, conditional boundary, and statement deletion operators
Surviving Mutant	A mutant that no test detected	Indicates a gap in test coverage where the modified logic produces different behavior but all tests still pass
Quality Gate	Enforces minimum mutation score thresholds	A CI check that fails the build if the mutation score drops below a configured minimum, preventing test quality regression

         Mutation Testing Launcher Architecture
  +-----------------------------------------------------------+
  |  SOURCE CODE            TEST SUITE                        |
  |  [src/**/*.ts]  <--->   [src/**/*.spec.ts]                |
  +-----------------------------------------------------------+
           |                         |
           v                         |
  +-----------------------------------------------------------+
  |  MUTATION ENGINE                                          |
  |  Apply Operators --> Generate Mutants --> Fork Processes   |
  +-----------------------------------------------------------+
           |                                      |
           v                                      v
  +----------------------------+   +----------------------------+
  |  MUTANT #1: a + b -> a - b |   |  MUTANT #N: x > 0 -> x < 0|
  |  Run tests --> KILLED       |   |  Run tests --> SURVIVED    |
  +----------------------------+   +----------------------------+
           |                                      |
           v                                      v
  +-----------------------------------------------------------+
  |  REPORT & QUALITY GATE                                    |
  |  Score: 74% | Survivors: 26 | Gate: PASS (>50%)           |
  +-----------------------------------------------------------+

Configuration

Parameter	Type	Default	Description
mutate	array	["src/**/*.ts"]	Glob patterns specifying which source files to mutate; test files should be excluded
testRunner	string	auto-detect	The test framework to execute against mutants: jest, mocha, pytest, junit, or cargo-test
thresholds.break	integer	50	Mutation score percentage below which the build fails; acts as the hard quality gate
coverageAnalysis	string	perTest	Strategy for optimizing which tests to run per mutant: off, all, perTest
concurrency	integer	CPU cores - 1	Number of parallel mutation test processes; reduce if system resources are constrained

Best Practices

1. Start with a focused module rather than the entire codebase. Mutation testing is computationally expensive because it runs your test suite once for every generated mutant. Begin by targeting your most critical business logic module, establish a baseline score, and strengthen those tests. Expand scope gradually as your team becomes comfortable with the workflow and the CI pipeline can handle the load.

2. Treat surviving mutants as test improvement opportunities. Each survivor represents a specific code change that your tests did not detect. Rather than dismissing survivors, examine each one to understand what assertion is missing. Often a single additional assertion kills multiple related mutants, yielding outsized improvement for minimal effort.

3. Configure mutation operators appropriate to your domain. Not all operators are equally useful for every codebase. If your application is math-heavy, arithmetic and boundary operators are critical. For a web application with complex conditionals, logical and equality operators matter more. Disable operators that generate noise without meaningful signal to reduce execution time and report clutter.

4. Integrate with CI as a non-blocking check initially. When first adopting mutation testing, set the break threshold low (around 30-40%) and configure the CI check as informational rather than blocking. This gives the team time to improve test quality without halting all development. Gradually raise the threshold as the mutation score improves.

5. Schedule full mutation runs on a cadence rather than every commit. Running mutation tests on every pull request can be slow for large codebases. Instead, run incremental mutation testing (only mutating changed files) on PRs and schedule full-codebase mutation runs nightly or weekly. This balances feedback speed with comprehensive coverage.

Common Issues

Mutation testing takes too long to complete. Execution time scales with the number of mutants multiplied by the number of tests. Enable perTest coverage analysis so the framework only runs relevant tests for each mutant. Also consider reducing the set of active mutation operators and increasing concurrency. For very large codebases, restrict the mutate glob to critical paths only.

Many equivalent mutants inflate the survivor count. An equivalent mutant produces the same observable behavior as the original code, making it impossible to detect. For example, mutating x >= 0 to x > 0 in code that never receives exactly zero. These false survivors cannot be killed and should be reviewed and excluded. Some frameworks offer heuristics to filter likely equivalents automatically.

Build fails immediately with threshold errors on first run. This happens when the default break threshold is set higher than the codebase's current mutation score. Lower the thresholds.break value to something achievable, run a baseline, and then incrementally raise the threshold as your tests improve. Trying to achieve a high score all at once discourages the team and stalls adoption.