Make your
tests prove it.
Your tests pass. Would they catch a bug?
Mutineer makes small changes to your Ruby code, then runs your tests. If they still pass, it shows you the change they missed. This is called mutation testing.
Works with your existing Minitest or RSpec tests. Free under the MIT license.
8,170spec examples, down from 17,702 (−54%)
Stephen Margheim had Opus 5.5 use Mutineer to check that every spec in his team's suite did real work, and refactor the suite. Lines of spec code fell 27%.
Read Stephen's post on XFind a bug your tests would miss.
Each changed version of your code is called a mutant. For example, a discount should start at 10 items. Tests for 1 and 50 items can pass even when the rule is wrong at exactly 10.
Line coverage tells you which lines ran. Mutation testing checks whether your tests notice a change to those lines.
return 0.1 if qty >= 10return 0.1 if qty > 10Still passes? Your tests missed qty = 10.
Show the test that catches it
assert_equal 0.1, Discount.new.rate(10)The original returns 0.1 at 10. The changed method returns 0. This test catches the missing discount. The report calls that a killed mutant.
No Ruby runs in this page. Run the complete example yourself.
Change one thing
Mutineer changes a comparison, swaps an operator, or removes a statement. Each change must still be valid Ruby before Mutineer tests it.
Run your tests
Mutineer runs the tests that cover the changed line. A test should fail when the change breaks a rule your code must follow.
Read what they missed
Killed means a test caught the change. Survived means the tests still passed. Read the changed line and add a test if it exposes a gap. Some changes leave the behaviour the same; record why you ignore those.
96% mutation score. 24 killed ÷ (24 killed + 1 survived). Uncovered and unscored changes are excluded. The score does not prove that the code has no bugs.
Inspect a sample reportStart with one file.
Use Ruby 3.4 or later on Linux or macOS. Choose a small file with tests that already pass. Mutation testing runs tests repeatedly, so it takes longer than a normal test run.
Install Mutineer
In a Bundler project, add gem "mutineer", group: :test to your Gemfile, run bundle install, and prefix the commands below with bundle exec.
Run it against your file and its test
Replace both paths with files in your project. For RSpec, use a spec file with --test. For Rails, follow the one-model guide.
Read one surviving change
Find Surviving Mutants in the report. Read the changed line. Add a test that passes with the original code and fails with the change, then run Mutineer again.
Some changes have the same result as the original. Those are called equivalent mutants. Review them and record a reason before you ignore them.
No file in mind? Run the complete example →
You do not need a score target for your first run. After you understand the results, add a CI check or save settings with mutineer init (1.7+).
Is it production-ready?
Check your database and framework before adding a CI gate. Mutineer requires Ruby 3.4 or later. In-process runs require Linux or macOS for forks. Plain Ruby projects without databases support parallel runs. In the Status column, supported means parallel runs work and serial only runs one mutant at a time.
| Ruby | Database | Framework | Parallelism | Status |
|---|---|---|---|---|
| 3.4 or later | SQLite file | Minitest | supported with --daemon | supported |
| 3.4 or later | SQLite file | RSpec | not supported | serial only |
| 3.4 or later | PostgreSQL | Minitest | supported with --daemon | supported |
| 3.4 or later | PostgreSQL | RSpec | not supported | serial only |
| 3.4 or later | MySQL 8 | Minitest | supported with --daemon | supported |
| 3.4 or later | MySQL 8 | RSpec | not supported | serial only |
| 3.4 or later | MariaDB | Minitest | not tested | not tested |
| 3.4 or later | MySQL 9 or later | Minitest | not tested | not tested |
| 3.4 or later | SQLite in memory | Minitest | not supported | serial only |
| 3.4 or later | SQLite in memory | RSpec | not supported | serial only |
| 3.4 or later | more than one database | Minitest | one worker | serial only |
| 3.4 or later | more than one database, Rails 7.1 or later, the extra ones in shared_databases | Minitest | supported with --daemon | supported, unless the test environment registers a pool for a shared database |
| 3.4 or later | more than one database | RSpec | not supported | serial only |
This matrix is for a Rails app on Ruby 3.4 or later. A plain Ruby project with no database runs in parallel with either framework. not supported means --daemon cannot run that cell; not tested means no CI job runs it. SQLite file means a database file, not :memory:.
--railswithout--daemonis serial on every row.--daemonis Minitest only.- MySQL older than 8.0 stops
--daemon. MariaDB and MySQL 9 or later warn and run. - An app with more than one database runs one worker:
--daemonisolates only the primary connection. On Rails 7.1 or later, list the databases your tests never use inshared_databases, and the workers run in parallel. CI tests that row on SQLite. See More than one database. - Postgres worker databases are copied once at the start; MySQL 8 worker databases are created then and the rows copied.
- A test that commits rows outside a transaction leaves them in that worker's database, and the next mutant on that worker sees them. Rails parallel tests have the same limit.
- RSpec: the first failed example with an Active Record connection or lock error scores
errored, on the same classes as Minitest (#347). On Rails 8,ConnectionNotDefinedis a code error and still scoreskilled. On Rails 7.2 that case raisesConnectionNotEstablishedand scoreserrored. Other statement errors still scorekilled.
Mutineer sets PARALLEL_WORKERS=1, so a parallelize call in test_helper.rb starts no Rails workers during a mutant run. See Rails parallel tests, Spring, Bootsnap, and Redis.
Older Ruby apps use --test-command; Mutineer still requires Ruby 3.4 or later. This path uses one Mutineer worker and no coverage-based test selection by default; a wrapper can re-enable Rails test workers by setting PARALLEL_WORKERS.
| Subprocess result | Score |
|---|---|
| Exit 1, normally | killed |
| SimpleCov gate exit with a failing test | killed |
| Other exit code | error |
| Crash before a test fails | Can score error |
| Only a SimpleCov gate fails, with its gate message and a passing summary | survived |
See Apps on Ruby < 3.4 and release guarantees in STABILITY.md.
Give your pipeline evidence.
Once you understand your first report, use Mutineer to check code changes in CI or give an AI coding agent a specific test gap to fix. JSON reports describe each missed change. You can limit runs to changed lines and compare results with an earlier run.
Close the loop on test quality
An agent writes code and tests, then runs Mutineer on just the diff. Each survivor ships a ready-made diff to feed back: "write a test that fails under this change." Ask for a human review when a survivor cannot be caught; it may leave the behaviour unchanged.
--since origin/main --format json
Fail only when a PR makes tests worse
Diff the run against a stored baseline by mutant id. Exit 1 on any new survivor or a score drop — adopt mutation testing on a legacy suite without fixing everything first.
--baseline prior.json --threshold 90
One step in your workflow
A composite action wraps the CLI: point it at your sources, a baseline, and a threshold. Reads the diff, posts the report, sets the exit code.
uses: davidteren/mutineer@v1
Small tool. Exacting work.
Prism and the standard library provide the runtime. Test-framework changes stay in disposable child processes; Rails apps can use the optional --rails or --boot entry point.
Zero runtime deps
Mutineer uses the parser and standard library included with Ruby 3.4 or later. It adds no runtime gems.
Valid mutants only
Every mutation is re-parsed before it runs. Syntactically broken mutants are skipped, not counted against your score.
Fork isolation
Each mutant runs in a separate process on Linux or macOS. Plain Ruby runs use multiple workers. Rails runs need --daemon for multiple workers. --test-command forces one Mutineer worker. It also sets PARALLEL_WORKERS=1 for Rails tests. A script that sets this variable again can start Rails test workers.
Coverage-mapped
A per-mutant coverage map runs only the test files that reach the mutated line. Digest-keyed cache skips unchanged work.
CI & agent ready
Stable, sorted --format json with a versioned schema and mutant ids that survive unrelated edits. --threshold and --baseline gate the build.
Rails-aware
Use --rails to load your app. Minitest apps can add --daemon for worker test databases on SQLite files, PostgreSQL, or MySQL 8. Start with one model.
Twenty-two ways to break your code.
Five run by default. Seventeen Tier-2 operators are off until you ask for them with --operators or .mutineer.yml — they're noisier, but they catch deeper gaps.
| Operator | Mutation rule | Tier |
|---|---|---|
| comparison | < ↔ <= , > ↔ >= , == ↔ != | default |
| arithmetic | + ↔ − , * ↔ / , % → * , ** → * | default |
| boolean_connector | && ↔ || | default |
| boolean_literal | true ↔ false , nil → true | default |
| statement_removal | replace a non-final statement with nil | default |
| return_nil | replace a return / final expression with nil | tier 2 |
| literal_mutation | integer → 0, 1, n+1 ; string → empty | tier 2 |
| condition_negation | wrap if/unless/ternary condition in !( … ) | tier 2 |
| string_literal | non-empty string → "" ; "" → "mutineer" | tier 2 |
| regex | drop ^ / $ anchors ; + ↔ * | tier 2 |
| collection_method | map ↔ each , all? ↔ any? , first ↔ last , min ↔ max , select ↔ reject | tier 2 |
| safe_navigation | &. → . | tier 2 |
| range | .. ↔ ... | tier 2 |
| negation_removal | !x , not x → x | tier 2 |
| chain_link | drop one call from a chain: a.b.c → a.c | tier 2 |
| call_to_receiver | drop the last call of a chain: foo.bar → foo | tier 2 |
| operand_removal | a && b → a , b | tier 2 |
| array_literal | [a, b] → [] | tier 2 |
| condition_true | if / elsif / unless / ternary / modifier / case-in guard condition → true | tier 2 |
| condition_false | if / elsif / unless / ternary / modifier / case-in guard condition → false | tier 2 |
| operator_assignment | += ↔ −= , *= ↔ /= , %= → *= , **= → *= (not ||= , &&=) | tier 2 |
| rescue_body | rescue clause body → nil ; x rescue y → x rescue nil | tier 2 |
Run mutineer --list-operators to see the live set for your installed version.
Written from scratch. MIT licensed.
Mutineer was written from scratch. It contains no code from Mutant or any other mutation-testing tool. Mutineer’s own code is licensed under MIT.
| Aspect | Mutineer | Mutant 0.17 |
|---|---|---|
| License | MIT, for every use | Free for open source; commercial use needs a paid subscription |
| Runtime dependencies | None (Prism + stdlib) | parser, unparser, sorbet-runtime and others |
| Ruby | 3.4 and later (older app Rubies via --test-command) | 3.3 and later |
| Test frameworks | Minitest and RSpec | RSpec, Minitest and Test::Unit |
| What you mutate | Files, or one method with --only | Subjects named by expression |
Checked against Mutant 0.17 on 2026-10-06. Full comparison and when to pick each: comparison guide.