Introduction to Mutineer
Relevant source files
The following files were used as context for generating this wiki page:
Mutineer provides clean-room mutation testing for Ruby projects. It uses the Prism parser and the Ruby standard library to ensure zero runtime dependencies. The system mutates source code one change at a time, runs the existing test suite against each mutant, and reports which changes go undetected by the tests.
This process helps developers identify weak or missing tests by proving whether a test suite notices functional regressions. Mutineer supports CI gates and AI coding agents through versioned JSON reports and specific exit code contracts.
Sources: skills/mutineer/SKILL.md:1-10, lib/mutineer.rb:3-50, AGENTS.md:5-15
System Architecture
Mutineer operates as a CLI tool that orchestrates source parsing, mutation generation, test execution, and result reporting. It uses a MutatorRegistry to manage different types of code transformations and a WorkerPool for parallel execution.
Core Components
- CLI (
Mutineer::CLI): Handles argument parsing, configuration resolution, and command dispatching. - Project & Parser: Discovers source files and generates Abstract Syntax Trees (AST) using Prism.
- Mutators: Logic modules (e.g.,
Arithmetic,Comparison,BooleanLiteral) that define how to transform specific AST nodes. - Runner: Coordinates the execution of mutation jobs, test isolation, and result aggregation.
- Reporter: Formats outcomes into human-readable text, JSON, or HTML.
Sources: lib/mutineer.rb:3-50, lib/mutineer/cli.rb:14-118
Execution Flow
The following diagram illustrates the high-level flow from a user command to the final report generation:
Mutation Results and Scoring
Mutineer classifies the outcome of each mutant into ten distinct states. These states determine the final mutation score and the success of CI gates.
Mutant Outcome States
| Status | Meaning | Included in Score |
|---|---|---|
killed | A test failed, catching the mutation. | Yes |
survived | All tests passed; the mutation was undetected. | Yes |
no_coverage | No tests exercise the mutated line. | No |
error | The child process crashed during execution. | No |
timeout | The mutant execution exceeded the time limit. | No |
ignored | User-suppressed equivalent mutant. | No |
uncapturable | Tests failed to run during coverage capture. | No |
unplaceable | Redefine strategy cannot name the class. | No |
ran_at_load | Code ran during app/class boot. | No |
skipped | Mutated source failed to re-parse. | No |
Sources: lib/mutineer/result.rb:5-48, lib/mutineer/reporter.rb:170-205
The Mutation Score Formula
The mutation score represents the percentage of testable mutants that the suite caught. Mutineer excludes environmental failures, coverage gaps, and ignored mutants from the denominator to ensure the score accurately reflects test logic strength.
Score = killed / (killed + survived)
If the denominator (killed + survived) is zero, the score is reported as nil (N/A).
Sources: lib/mutineer/result.rb:180-195, lib/mutineer/reporter.rb:440-455, AGENTS.md:155-160
CLI Commands and Usage
Mutineer provides several subcommands for managing mutation tests and configurations.
| Command | Purpose |
|---|---|
run | Mutates source files and executes the test suite. |
init | Generates a starter .mutineer.yml configuration file. |
triage | Generates ignore entries for surviving mutants from a JSON report. |
migrate | Updates old-format mutant IDs in .mutineer.yml. |
Sources: lib/mutineer/cli.rb:20-40, lib/mutineer/init.rb:20-40
Exit Code Contract
Mutineer uses standardized exit codes to facilitate integration with CI pipelines and automated agents.
| Code | Meaning |
|---|---|
0 | Success: Score is above threshold and no baseline regressions occurred. |
1 | Failure: Score is below threshold, regressions detected, or runtime errors occurred. |
2 | Usage Error: Invalid flags, bad paths, or unreadable configurations. |
Sources: skills/mutineer/SKILL.md:50-60, STABILITY.md:35-45, lib/mutineer/cli.rb:14-19
Configuration and Integration
Developers configure Mutineer via CLI flags or the .mutineer.yml file. Command-line flags always override file-based settings.
Key Configuration Options
threshold: The minimum mutation score required to exit with code 0.since: Scopes mutation to lines changed since a specific Git ref (e.g.,origin/main).baseline: Compares current results against a prior JSON report to detect new survivors or score drops.jobs: Configures the number of parallel worker processes.rails: Enables specialized handling for Rails environments, including environment booting.
Sources: lib/mutineer/cli.rb:42-88, action.yml:12-85, lib/mutineer/init.rb:65-85
GitHub Action Integration
The mutineer-ruby action automates mutation testing in GitHub workflows. It automatically detects pull request base commits to scope tests to changed lines and provides per-survivor annotations directly on PR diffs.
Conclusion
Mutineer is a specialized tool for Ruby developers seeking to validate test coverage through mutation. By leveraging the Prism parser and a zero-dependency architecture, it provides a stable and performant way to audit test suites. Its integration features, including JSON reporting and Git-diff scoping, make it suitable for modern CI/CD workflows and AI-assisted development cycles.