Check your Ruby tests / Minitest & RSpec

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.

00 runtime dependencies 22 types of code change 01 change at a time JSON reports for CI and agents
In practice

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 X
How it works

Find 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.

One change. One missed boundary.COMPARISON
ORIGINALreturn 0.1 if qty >= 10
MUTANTreturn 0.1 if qty > 10

Still 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.

Reading a result24 caught. 1 missed.

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 report
Your first run

Start 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

$ gem 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

$ mutineer run lib/discount.rb \ --test test/discount_test.rb

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+).

Before you adopt it

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.

RubyDatabaseFrameworkParallelismStatus
3.4 or laterSQLite fileMinitestsupported with --daemonsupported
3.4 or laterSQLite fileRSpecnot supportedserial only
3.4 or laterPostgreSQLMinitestsupported with --daemonsupported
3.4 or laterPostgreSQLRSpecnot supportedserial only
3.4 or laterMySQL 8Minitestsupported with --daemonsupported
3.4 or laterMySQL 8RSpecnot supportedserial only
3.4 or laterMariaDBMinitestnot testednot tested
3.4 or laterMySQL 9 or laterMinitestnot testednot tested
3.4 or laterSQLite in memoryMinitestnot supportedserial only
3.4 or laterSQLite in memoryRSpecnot supportedserial only
3.4 or latermore than one databaseMinitestone workerserial only
3.4 or latermore than one database, Rails 7.1 or later, the extra ones in shared_databasesMinitestsupported with --daemonsupported, unless the test environment registers a pool for a shared database
3.4 or latermore than one databaseRSpecnot supportedserial 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:.

  • --rails without --daemon is serial on every row. --daemon is 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: --daemon isolates only the primary connection. On Rails 7.1 or later, list the databases your tests never use in shared_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, ConnectionNotDefined is a code error and still scores killed. On Rails 7.2 that case raises ConnectionNotEstablished and scores errored. Other statement errors still score killed.

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 resultScore
Exit 1, normallykilled
SimpleCov gate exit with a failing testkilled
Other exit codeerror
Crash before a test failsCan score error
Only a SimpleCov gate fails, with its gate message and a passing summarysurvived

See Apps on Ruby < 3.4 and release guarantees in STABILITY.md.

AI agents & CI

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.

Agent inner loop

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

PR / CI gate

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

GitHub Action

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

Why Mutineer

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.

Operators

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.

Default set keeps survivor output focused; opt into Tier 2 for a harder pass.
OperatorMutation ruleTier
comparison< ↔ <= , > ↔ >= , == ↔ !=default
arithmetic+ ↔ − , * ↔ / , % → * , ** → *default
boolean_connector&& ↔ ||default
boolean_literaltrue ↔ false , nil → truedefault
statement_removalreplace a non-final statement with nildefault
return_nilreplace a return / final expression with niltier 2
literal_mutationinteger → 0, 1, n+1 ; string → emptytier 2
condition_negationwrap if/unless/ternary condition in !( … )tier 2
string_literalnon-empty string → "" ; "" → "mutineer"tier 2
regexdrop ^ / $ anchors ; + ↔ *tier 2
collection_methodmap ↔ each , all? ↔ any? , first ↔ last , min ↔ max , select ↔ rejecttier 2
safe_navigation&. → .tier 2
range.. ↔ ...tier 2
negation_removal!x , not x → xtier 2
chain_linkdrop one call from a chain: a.b.c → a.ctier 2
call_to_receiverdrop the last call of a chain: foo.bar → footier 2
operand_removala && b → a , btier 2
array_literal[a, b] → []tier 2
condition_trueif / elsif / unless / ternary / modifier / case-in guard condition → truetier 2
condition_falseif / elsif / unless / ternary / modifier / case-in guard condition → falsetier 2
operator_assignment+= ↔ −= , *= ↔ /= , %= → *= , **= → *= (not ||= , &&=)tier 2
rescue_bodyrescue clause body → nil ; x rescue y → x rescue niltier 2

Run mutineer --list-operators to see the live set for your installed version.

Mutineer and Mutant

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.

Mutant is the established tool, with a deeper operator set. Mutineer trades that depth for an MIT license, no dependencies, and a JSON contract for CI and agents.
AspectMutineerMutant 0.17
LicenseMIT, for every useFree for open source; commercial use needs a paid subscription
Runtime dependenciesNone (Prism + stdlib)parser, unparser, sorbet-runtime and others
Ruby3.4 and later (older app Rubies via --test-command)3.3 and later
Test frameworksMinitest and RSpecRSpec, Minitest and Test::Unit
What you mutateFiles, or one method with --onlySubjects named by expression

Checked against Mutant 0.17 on 2026-10-06. Full comparison and when to pick each: comparison guide.