Installation & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
Mutineer provides zero-dependency mutation testing for Ruby using the Prism parser. It mutates source code one change at a time and runs the test suite against each mutant to identify code changes that tests fail to catch. This system prioritizes CI/agent gating and machine-readable JSON reporting.
Sources: skills/mutineer/SKILL.md:4-7, lib/mutineer.rb:3-44
Installation
You install Mutineer as a Ruby gem. For projects using a standard Ruby environment, run the installation command directly. For projects managing dependencies via Bundler, include Mutineer in your Gemfile and use bundle exec.
gem install mutineer
If you use Mutineer with a Rails application or require specific version pinning, add it to your Gemfile:
group :development, :test do
gem 'mutineer'
end
Sources: skills/mutineer/SKILL.md:15, action.yml:102-106
Environment Requirements
- Ruby Version: Requires Ruby 3.4 or higher (since Prism ships with it).
- Dependencies: Zero runtime dependencies; relies only on Prism and the Ruby standard library.
Sources: skills/mutineer/SKILL.md:5, lib/mutineer.rb:3-44
Project Initialization
The mutineer init command sets up the necessary configuration for a project. It generates a starter .mutineer.yml file and detects common Ruby source directories to provide a suggested first run command.
Initialization Flow
The following diagram illustrates how Mutineer initializes a new project configuration.
The initialization process identifies existing source folders to construct a valid entry point for the user.
Sources: lib/mutineer/init.rb:14-87, test/init_test.rb:16-90
Initialization Options
| Flag | Description |
|---|---|
--rails | Configures Mutineer for Rails. Boots the environment once and searches app/models and app/services. |
--force | Overwrites an existing .mutineer.yml file. |
--help | Displays usage information. |
Sources: lib/mutineer/init.rb:18-23, test/init_test.rb:104-118
Running Mutineer
Execute a mutation run by specifying source files or directories and the corresponding test files.
mutineer run <source_paths> --test <test_paths> [options]
Basic Usage Examples
- Standard Library:
mutineer run lib/calculator.rb --test test/calculator_test.rb - Rails Model with Threshold:
mutineer run app/models/user.rb --test test/models/user_test.rb --threshold 90 - Scoping to Changes:
mutineer run app/ --since origin/main --format json
Sources: skills/mutineer/SKILL.md:21-35, action.yml:15-20
CI Integration (GitHub Actions)
Mutineer includes a composite GitHub Action to automate mutation testing in CI pipelines. The action supports diff-scoping to only test lines changed in a Pull Request.
Workflow Example
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Required for --since scoping
- uses: davidteren/mutineer@v1
with:
sources: "app/models lib"
threshold: 90
since: ${{ github.event.pull_request.base.sha }}
Sources: action.yml:9-251
Action Inputs Reference
| Input | Default | Description |
|---|---|---|
sources | (Required) | Space-separated paths to mutate. |
test | "" | Optional test files. Auto-detected if omitted. |
since | "" | Scopes mutation to lines changed since this ref. |
threshold | "" | Minimum mutation score to pass the build. |
baseline | "" | Path to a prior JSON report to detect regressions. |
use-bundler | false | Runs via bundle exec mutineer if true. |
Sources: action.yml:12-92
Understanding Results
Mutineer provides feedback via exit codes and formatted reports. The exit code determines if the CI gate passes.
Exit Codes
| Code | Meaning |
|---|---|
0 | Success: Score ≥ threshold AND no baseline regression. |
1 | Failure: Score below threshold, baseline regression, or runtime error. |
2 | Usage Error: Invalid flags or unreadable configuration. |
Sources: skills/mutineer/SKILL.md:65-72, lib/mutineer/reporter.rb:119-138
The Scoring Model
Mutineer calculates the score as killed / (killed + survived). Other states are excluded from the denominator:
- No Coverage: Code that was never reached by tests.
- Uncapturable/Unplaceable: Technical failures preventing mutation.
- Ran at Load: Code executed during initial file loading.
- Ignored: Mutants manually suppressed by the user.
Sources: lib/mutineer/reporter.rb:147-217, skills/mutineer/SKILL.md:46-52
Mutineer ensures that if a significant portion of the run produces "No Verdict" (e.g., timeouts or errors exceeding 10% of attempted mutants), the threshold gate fails to prevent misleadingly high scores from incomplete runs.
Sources: lib/mutineer/reporter.rb:19-27, lib/mutineer/reporter.rb:713-720