mutant
Run mutant, read mutation reports, fix alive mutations, and verify coverage. Use when running mutation testing or responding to alive mutations.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mbj/mutant with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mbj/mutant'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/mbj--mutant)HTML
<a href="/listings/mbj--mutant"><img src="/api/listings/mbj--mutant/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# lib/person.rb
class Person
def initialize(age:)
@age = age
end
def adult?
@age >= 18
end
end# spec/person_spec.rb
RSpec.describe Person do
describe '#adult?' do
it 'returns true for age 19' do
expect(Person.new(age: 19).adult?).to be(true)
end
it 'returns false for age 17' do
expect(Person.new(age: 17).adult?).to be(false)
end
end
endTests pass. But run mutant:
gem install mutant-rspec mutant run --use rspec --usage opensource --require ./lib/person 'Person#adult?'
Mutant finds a surviving mutation indicating a shallow test:
def adult? - @age >= 18 + @age > 18 end
Your tests don't cover `age == 18`. The mutation from `>=` to `>` doesn't break them.
This is just one of many mutation operators. Mutant also mutates arithmetic, logical, bitwise operators, removes statements, modifies return values, and more.
A full working example is available in the [quick_start](quick_start/) directory.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 241 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: mutant
- description: Run mutant, read mutation reports, fix alive mutations, and verify coverage. Use when running mutation testing or responding to alive mutations.
- compatibility: Unified agent skills CLI
- metadata:
- author: dkubb
- version: "2026-03-v22"
- triggers:
- - "mutation testing"
- - "mutant"
- - "alive mutation"
- - "mutation coverage"
- ---
- # Mutant
- ## When to Activate
- - The user asks to run mutation testing.
- - The user has alive mutations to fix.
- - The user asks to verify mutation coverage.
- ## When Not to Use
- - The task does not involve mutation testing.
- ## Inputs
- - Alive mutation output to act on.
- ## Outputs (Fixed Order)
- 1. Mutation results (alive count, coverage percentage).
- 2. Action for each alive mutation.
- ## Reading Output
- An alive mutation looks like:
- ```text
- evil:YourClass#method:YourClass#method:lib/your_class.rb:42:abc12
- @@ -1,3 +1,3 @@
- def method
- - @value >= threshold
- + @value > threshold
- end
- ```
- - `evil` means no test killed this mutation.
- - The diff shows original (minus) and mutated (plus) code.
- ## Reporting Format
- Lead with the verdict (BLUF — bottom line up front):
- **If unkillable:**
- > **Unkillable.** Both forms are equivalent because \[reason\].
- > Add to ignore list.
- **If killable:**
- > **Killable.**
- >
- > **Option A — add test:**
- >
- > ```diff
- > (test diff)
- > ```
- >
- > **Option B — simplify code:**
- >
- > ```diff
- > (source diff)
- > ```
- Always present both options together so the user can choose. Include
- evidence: if you cannot think of a test that would kill the mutation,
- say so — that is valuable signal toward unkillable.
- ## Fixing Alive Mutations
- For each alive mutation, read the diff, then read the source and
- existing tests. Ask: "is the mutated code acceptable?" Then choose:
- 1. **Add a test** when the mutated code is wrong but the tests do
- not prove it. The test must pass with the original code and fail
- with the mutated code. Common reasons a test is missing:
- - Only one value of a boolean/flag is tested (add the other).
- - A collection has one element, so `next` and `break` behave the
- same (add a test with multiple elements).
- - Two objects return the same value in test data, hiding which one
- the code actually uses (add test data where they differ).
- - A method has a default parameter value, and all tests pass the
- argument explicitly, leaving the default path uncovered (add a
- test that omits the argument).
- 2. **Simplify the code** when the mutated code is correct for all
- valid inputs. Apply the mutation's change directly to the source
- code — do not restructure or rewrite, just accept the mutated
- form.
- ### How Simplification Works
- Mutant encodes the **principle of least power**: use the most
- constrained primitive that satisfies the requirement. When Ruby
- offers multiple methods that overlap in behavior but differ in
- power, mutant replaces the more powerful one with the less powerful
- one. If the tests still pass, you did not need the extra power —
- accept the simpler form. If a test fails, the test proves you
- needed the more powerful primitive.
- Before accepting a simplification, verify the mutation preserves
- behavior across the method's full input domain and all call sites.
- ### Simplification Trap: Syntax Rewriting
- Do not rewrite code to eliminate a mutation axis without first
- ensuring the expression has test coverage. Changing syntax (e.g.
- replacing `&method(:name)` with `{ |x| name(x) }`) may make the
- mutation disappear, but it does not prove the code is correct — it
- just hides the gap. The correct sequence is:
- 1. Add test coverage for the expression (e.g. a meta spec or
- integration test that exercises the code path).
- 2. Apply the simplification that mutant suggests (e.g. `method` →
- `public_method`).
- 3. Verify 100% mutation coverage on the subject.
- If a simplification removes a mutation axis, the underlying
- expression must still be reachable by tests. Every code path that
- mutant can mutate must have at least one test that exercises it.
- ### When a Mutation Is Equivalent
- When the original and mutated code produce the same result for all
- inputs, the mutation is **equivalent**. Equivalent does NOT mean
- unkillable. Ask: does the mutated form use a more constrained
- primitive? If yes, it IS the simplification — apply it to the
- source. Examples: `method` → `public_method` (restricts to public
- API), `kind_of?` → `instance_of?` (restricts to exact class).
- A mutation is only **unkillable** when you cannot add a test AND
- you cannot apply the mutation to the source (e.g. both forms call
- through to the same underlying method with no way to prefer either).
- When unkillable:
- 1. Add the subject to the ignore list with an inline comment
- explaining why it is unkillable.
- 2. Do not commit code or test changes for this subject.
- 3. Report: which mutation survived, why it is equivalent, and what
- you tried before concluding it is unkillable.
- Every ignored subject must have a comment. No uncommented entries.
- ## Usage
- 1. Run mutant:
- ```sh
- bundle exec mutant run --fail-fast
- ```
- When the subject is already known, scope the run to avoid
- testing unrelated subjects:
- ```sh
- bundle exec mutant run --fail-fast 'Foo::Bar#baz'
- ```
- If the command succeeds, coverage is 100% — done.
- If it fails, find the `evil:` line in the output — it has the
- subject name, file path, and line number. The diff block
- immediately after shows the original and mutated code.
- 2. Read the source file and existing test file for the subject.
- 3. Decide: add test or simplify code. Make the change. Do not change
- both code and tests in the same commit — if both need changing,
- commit the test first, then simplify the code in a second commit.
- 4. Re-run mutant (repeat step 1) until 100%. If the same mutation
- survives after 2 attempts, evaluate whether it is unkillable (see
- "When a Mutation Is Equivalent" above).
- 5. Run the project test suite.
- 6. Commit the change. Follow the project's commit message
- conventions, defaulting to conventional commits if none are
- present. The commit body must explain why the change was made
- with enough detail for effective code review — which mutation
- survived, why the test kills it or why the simplification is
- correct.
- ### Prepare Legacy Project
- When adding mutant to a project that has no ignore list yet,
- run mutant once to find all alive subjects, then seed the ignore
- list so the burn-down process can start from a passing baseline:
- ```sh
- bundle exec mutant run 2>&1 \
- | sed -n 's/^evil:\([A-Za-z][A-Za-z0-9_:]*[#.][^:]*\):.*/\1/p' \
- | LC_ALL=C sort -u \
- || true
- ```
- The `sed` pattern extracts the subject expression (e.g.
- `Axiom::Foo#bar`) from each `evil:` line, handling `::` in
- namespaced constants. The evil line format is:
- ```text
- evil:SUBJECT:SOURCE_LOC:FILE:LINENO:ID
- ```
- Add each subject to the `ignore` list in the mutant config with an
- inline comment (e.g. `# legacy baseline`) and commit as a baseline. Then remove one subject at a time from
- the ignore list and follow the Usage instructions above to kill
- its alive mutations. Commit each subject's fix with the ignore
- list removal included.
- ## Checklist
- - Each alive mutation has a clear action: add test or simplify code.
- - New tests fail against the mutated code, not just pass against the
- original.
- - The project test suite passes after each change.
- - Each commit touches one subject only.
- - Report what you did and why so the user can review your decisions:
- - Research before asking. If a question depends on information you
- can gather first, gather it — then ask an informed question
- instead of a speculative one.
- - If unkillable, say so up front. Do not bury the verdict in
- analysis the reader cannot act on.
- - If killable, present the options clearly: add a test (Option A)
- or simplify the code (Option B). See "Reporting Format" above.
README.md · README · 188 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- mutant
- ======
- [](https://github.com/mbj/mutant/actions/workflows/ci.yml)
- [](https://rubygems.org/gems/mutant)
- [](https://rubygems.org/gems/mutant)
- [](https://github.com/mbj/mutant)
- [](https://discord.gg/BSr62b4RkV)
- ## What is Mutant?
- **AI writes your code. AI writes your tests. But who tests the tests?**
- Copilot, Claude, and ChatGPT generate code faster than humans can review it. They'll even
- write tests that pass. But passing tests aren't the same as *meaningful* tests.
- Mutant is mutation testing for Ruby. It systematically modifies your code and verifies your
- tests actually catch each change.
- The more code AI writes for you, the more you need verification you can trust.
- ## What is an Alive Mutation?
- Each surviving (alive) mutation is a call to action with exactly one of two options:
- - **Keep the mutated code** - your tests already specify the correct semantics, and the
- original code is redundant. Accept the mutation as a simplification.
- - **Add the missing test** - the original code is correct, but the tests don't verify the
- behavior the mutation removed.
- ## Author
- Mutant was created and is developed by [Markus Schirp](https://schirp-dso.com).
- It is the subject of [IEEE-published research](https://ieeexplore.ieee.org/document/7107453/)
- and is included in the [Trail of Bits Ruby Security Field Guide](https://trailofbits.github.io/rubysec/mutant/index.html).
- ## Quick Start
- ```ruby
- # lib/person.rb
- class Person
- def initialize(age:)
- @age = age
- end
- def adult?
- @age >= 18
- end
- end
- ```
- ```ruby
- # spec/person_spec.rb
- RSpec.describe Person do
- describe '#adult?' do
- it 'returns true for age 19' do
- expect(Person.new(age: 19).adult?).to be(true)
- end
- it 'returns false for age 17' do
- expect(Person.new(age: 17).adult?).to be(false)
- end
- end
- end
- ```
- Tests pass. But run mutant:
- ```bash
- gem install mutant-rspec
- mutant run --use rspec --usage opensource --require ./lib/person 'Person#adult?'
- ```
- Mutant finds a surviving mutation indicating a shallow test:
- ```diff
- def adult?
- - @age >= 18
- + @age > 18
- end
- ```
- Your tests don't cover `age == 18`. The mutation from `>=` to `>` doesn't break them.
- This is just one of many mutation operators. Mutant also mutates arithmetic, logical,
- bitwise operators, removes statements, modifies return values, and more.
- A full working example is available in the [quick_start](quick_start/) directory.
- ## Session History
- Mutant records every run to `.mutant/results/`, and keeps the 100 most recent.
- You can recall past results without re-running mutation testing:
- ```bash
- # List past sessions (most recent first)
- mutant session list
- # Show full report from the latest session
- mutant session show
- # Show full report from a specific session
- mutant session show --session-id 019cf6f1-77e8-74b6-82db-f8b5faf570cd
- # List subjects with alive/total mutation counts
- mutant session subject
- # Show alive mutations for a specific subject
- mutant session subject 'Foo::Bar#baz'
- # Remove old or incompatible session files
- mutant session gc --keep 50
- ```
- ## Next Steps
- 1. Learn the [nomenclature](/docs/nomenclature.md) (subjects, mutations, operators)
- 2. Set up your [integration](/docs/nomenclature.md#integration): [RSpec](/docs/mutant-rspec.md), [Minitest](/docs/mutant-minitest.md), or [Test::Unit](/docs/mutant-test-unit.md)
- 3. Run mutant on CI in [incremental](/docs/incremental.md) mode
- ## Ruby Versions
- Mutant is supported on Linux and macOS.
- | Version | Runtime | Syntax | Mutations |
- | ------- | ------- | ------ | --------- |
- | 3.2 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
- | 3.3 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
- | 3.4 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
- | 4.0 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
- ## Rails
- Mutant runs against Rails applications, including parallel-worker database
- isolation (PostgreSQL and SQLite). The hook recipes are verified in CI on every
- non-EOL Rails version:
- | Version | Status |
- | ------- | ------ |
- | 7.2 | :heavy_check_mark: |
- | 8.0 | :heavy_check_mark: |
- | 8.1 | :heavy_check_mark: |
- See the [Rails Integration guide](/docs/rails.md) for setup, eager loading, and
- per-worker database isolation. A runnable, CI-verified example lives in
- [rails_example](rails_example/).
- ## Licensing
- **Free for open source.** Use `--usage opensource` for public repositories.
- **Commercial use** requires a subscription ($30/month or $250/year per developer).
- **Enterprise** — [reach out directly](mailto:info@schirp-dso.com?subject=Mutant%20Enterprise).
- See [commercial licensing](/docs/commercial.md) for pricing and details.
- ## Documentation
- * [Configuration](/docs/configuration.md)
- * [RSpec Integration](/docs/mutant-rspec.md)
- * [Minitest Integration](/docs/mutant-minitest.md)
- * [Test::Unit Integration](/docs/mutant-test-unit.md)
- * [Rails Integration](/docs/rails.md)
- * [Incremental Mode](/docs/incremental.md)
- * [Test Selection](/docs/test-selection.md)
- * [Reading Reports](/docs/reading-reports.md)
- * [Concurrency](/docs/concurrency.md)
- * [AST Pattern Matching](/docs/ast-pattern.md)
- * [Session JSON Schema](/docs/session-json-schema.yml)
- * [Hooks](/docs/hooks.md)
- * [Sorbet](/docs/sorbet.md)
- * [Nomenclature](/docs/nomenclature.md)
- * [Limitations](/docs/limitations.md)
- * [Mutant in the Wild](/docs/in-the-wild.md)
- ## Communication
- * [Discord](https://discord.gg/BSr62b4RkV)
- * [GitHub Issues](https://github.com/mbj/mutant/issues)
- * [Release Announcements](https://announce.mutant.dev/signup)
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
- ## Acknowledgments
- * [Contributors](https://github.com/mbj/mutant/graphs/contributors)
- * The `mutant-minitest` integration was sponsored by [Arkency](https://arkency.com/)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.