Skip to content
Back to search

mutant

SkillWorks with Claude CodeGitHub

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mbj--mutant/badge.svg)](/listings/mbj--mutant)

HTML

<a href="/listings/mbj--mutant"><img src="/api/listings/mbj--mutant/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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
end

Tests 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)

  1. ---
  2. name: mutant
  3. description: Run mutant, read mutation reports, fix alive mutations, and verify coverage. Use when running mutation testing or responding to alive mutations.
  4. compatibility: Unified agent skills CLI
  5. metadata:
  6. author: dkubb
  7. version: "2026-03-v22"
  8. triggers:
  9. - "mutation testing"
  10. - "mutant"
  11. - "alive mutation"
  12. - "mutation coverage"
  13. ---
  14. # Mutant
  15. ## When to Activate
  16. - The user asks to run mutation testing.
  17. - The user has alive mutations to fix.
  18. - The user asks to verify mutation coverage.
  19. ## When Not to Use
  20. - The task does not involve mutation testing.
  21. ## Inputs
  22. - Alive mutation output to act on.
  23. ## Outputs (Fixed Order)
  24. 1. Mutation results (alive count, coverage percentage).
  25. 2. Action for each alive mutation.
  26. ## Reading Output
  27. An alive mutation looks like:
  28. ```text
  29. evil:YourClass#method:YourClass#method:lib/your_class.rb:42:abc12
  30. @@ -1,3 +1,3 @@
  31. def method
  32. - @value >= threshold
  33. + @value > threshold
  34. end
  35. ```
  36. - `evil` means no test killed this mutation.
  37. - The diff shows original (minus) and mutated (plus) code.
  38. ## Reporting Format
  39. Lead with the verdict (BLUF — bottom line up front):
  40. **If unkillable:**
  41. > **Unkillable.** Both forms are equivalent because \[reason\].
  42. > Add to ignore list.
  43. **If killable:**
  44. > **Killable.**
  45. >
  46. > **Option A — add test:**
  47. >
  48. > ```diff
  49. > (test diff)
  50. > ```
  51. >
  52. > **Option B — simplify code:**
  53. >
  54. > ```diff
  55. > (source diff)
  56. > ```
  57. Always present both options together so the user can choose. Include
  58. evidence: if you cannot think of a test that would kill the mutation,
  59. say so — that is valuable signal toward unkillable.
  60. ## Fixing Alive Mutations
  61. For each alive mutation, read the diff, then read the source and
  62. existing tests. Ask: "is the mutated code acceptable?" Then choose:
  63. 1. **Add a test** when the mutated code is wrong but the tests do
  64. not prove it. The test must pass with the original code and fail
  65. with the mutated code. Common reasons a test is missing:
  66. - Only one value of a boolean/flag is tested (add the other).
  67. - A collection has one element, so `next` and `break` behave the
  68. same (add a test with multiple elements).
  69. - Two objects return the same value in test data, hiding which one
  70. the code actually uses (add test data where they differ).
  71. - A method has a default parameter value, and all tests pass the
  72. argument explicitly, leaving the default path uncovered (add a
  73. test that omits the argument).
  74. 2. **Simplify the code** when the mutated code is correct for all
  75. valid inputs. Apply the mutation's change directly to the source
  76. code — do not restructure or rewrite, just accept the mutated
  77. form.
  78. ### How Simplification Works
  79. Mutant encodes the **principle of least power**: use the most
  80. constrained primitive that satisfies the requirement. When Ruby
  81. offers multiple methods that overlap in behavior but differ in
  82. power, mutant replaces the more powerful one with the less powerful
  83. one. If the tests still pass, you did not need the extra power —
  84. accept the simpler form. If a test fails, the test proves you
  85. needed the more powerful primitive.
  86. Before accepting a simplification, verify the mutation preserves
  87. behavior across the method's full input domain and all call sites.
  88. ### Simplification Trap: Syntax Rewriting
  89. Do not rewrite code to eliminate a mutation axis without first
  90. ensuring the expression has test coverage. Changing syntax (e.g.
  91. replacing `&method(:name)` with `{ |x| name(x) }`) may make the
  92. mutation disappear, but it does not prove the code is correct — it
  93. just hides the gap. The correct sequence is:
  94. 1. Add test coverage for the expression (e.g. a meta spec or
  95. integration test that exercises the code path).
  96. 2. Apply the simplification that mutant suggests (e.g. `method` →
  97. `public_method`).
  98. 3. Verify 100% mutation coverage on the subject.
  99. If a simplification removes a mutation axis, the underlying
  100. expression must still be reachable by tests. Every code path that
  101. mutant can mutate must have at least one test that exercises it.
  102. ### When a Mutation Is Equivalent
  103. When the original and mutated code produce the same result for all
  104. inputs, the mutation is **equivalent**. Equivalent does NOT mean
  105. unkillable. Ask: does the mutated form use a more constrained
  106. primitive? If yes, it IS the simplification — apply it to the
  107. source. Examples: `method` → `public_method` (restricts to public
  108. API), `kind_of?` → `instance_of?` (restricts to exact class).
  109. A mutation is only **unkillable** when you cannot add a test AND
  110. you cannot apply the mutation to the source (e.g. both forms call
  111. through to the same underlying method with no way to prefer either).
  112. When unkillable:
  113. 1. Add the subject to the ignore list with an inline comment
  114. explaining why it is unkillable.
  115. 2. Do not commit code or test changes for this subject.
  116. 3. Report: which mutation survived, why it is equivalent, and what
  117. you tried before concluding it is unkillable.
  118. Every ignored subject must have a comment. No uncommented entries.
  119. ## Usage
  120. 1. Run mutant:
  121. ```sh
  122. bundle exec mutant run --fail-fast
  123. ```
  124. When the subject is already known, scope the run to avoid
  125. testing unrelated subjects:
  126. ```sh
  127. bundle exec mutant run --fail-fast 'Foo::Bar#baz'
  128. ```
  129. If the command succeeds, coverage is 100% — done.
  130. If it fails, find the `evil:` line in the output — it has the
  131. subject name, file path, and line number. The diff block
  132. immediately after shows the original and mutated code.
  133. 2. Read the source file and existing test file for the subject.
  134. 3. Decide: add test or simplify code. Make the change. Do not change
  135. both code and tests in the same commit — if both need changing,
  136. commit the test first, then simplify the code in a second commit.
  137. 4. Re-run mutant (repeat step 1) until 100%. If the same mutation
  138. survives after 2 attempts, evaluate whether it is unkillable (see
  139. "When a Mutation Is Equivalent" above).
  140. 5. Run the project test suite.
  141. 6. Commit the change. Follow the project's commit message
  142. conventions, defaulting to conventional commits if none are
  143. present. The commit body must explain why the change was made
  144. with enough detail for effective code review — which mutation
  145. survived, why the test kills it or why the simplification is
  146. correct.
  147. ### Prepare Legacy Project
  148. When adding mutant to a project that has no ignore list yet,
  149. run mutant once to find all alive subjects, then seed the ignore
  150. list so the burn-down process can start from a passing baseline:
  151. ```sh
  152. bundle exec mutant run 2>&1 \
  153. | sed -n 's/^evil:\([A-Za-z][A-Za-z0-9_:]*[#.][^:]*\):.*/\1/p' \
  154. | LC_ALL=C sort -u \
  155. || true
  156. ```
  157. The `sed` pattern extracts the subject expression (e.g.
  158. `Axiom::Foo#bar`) from each `evil:` line, handling `::` in
  159. namespaced constants. The evil line format is:
  160. ```text
  161. evil:SUBJECT:SOURCE_LOC:FILE:LINENO:ID
  162. ```
  163. Add each subject to the `ignore` list in the mutant config with an
  164. inline comment (e.g. `# legacy baseline`) and commit as a baseline. Then remove one subject at a time from
  165. the ignore list and follow the Usage instructions above to kill
  166. its alive mutations. Commit each subject's fix with the ignore
  167. list removal included.
  168. ## Checklist
  169. - Each alive mutation has a clear action: add test or simplify code.
  170. - New tests fail against the mutated code, not just pass against the
  171. original.
  172. - The project test suite passes after each change.
  173. - Each commit touches one subject only.
  174. - Report what you did and why so the user can review your decisions:
  175. - Research before asking. If a question depends on information you
  176. can gather first, gather it — then ask an informed question
  177. instead of a speculative one.
  178. - If unkillable, say so up front. Do not bury the verdict in
  179. analysis the reader cannot act on.
  180. - If killable, present the options clearly: add a test (Option A)
  181. 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)

  1. mutant
  2. ======
  3. [![Build Status](https://github.com/mbj/mutant/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mbj/mutant/actions/workflows/ci.yml)
  4. [![Gem Version](https://img.shields.io/gem/v/mutant.svg)](https://rubygems.org/gems/mutant)
  5. [![Gem Downloads](https://img.shields.io/gem/dt/mutant.svg)](https://rubygems.org/gems/mutant)
  6. [![GitHub Stars](https://img.shields.io/github/stars/mbj/mutant.svg)](https://github.com/mbj/mutant)
  7. [![Discord](https://img.shields.io/discord/767914934016802818.svg)](https://discord.gg/BSr62b4RkV)
  8. ## What is Mutant?
  9. **AI writes your code. AI writes your tests. But who tests the tests?**
  10. Copilot, Claude, and ChatGPT generate code faster than humans can review it. They'll even
  11. write tests that pass. But passing tests aren't the same as *meaningful* tests.
  12. Mutant is mutation testing for Ruby. It systematically modifies your code and verifies your
  13. tests actually catch each change.
  14. The more code AI writes for you, the more you need verification you can trust.
  15. ## What is an Alive Mutation?
  16. Each surviving (alive) mutation is a call to action with exactly one of two options:
  17. - **Keep the mutated code** - your tests already specify the correct semantics, and the
  18. original code is redundant. Accept the mutation as a simplification.
  19. - **Add the missing test** - the original code is correct, but the tests don't verify the
  20. behavior the mutation removed.
  21. ## Author
  22. Mutant was created and is developed by [Markus Schirp](https://schirp-dso.com).
  23. It is the subject of [IEEE-published research](https://ieeexplore.ieee.org/document/7107453/)
  24. and is included in the [Trail of Bits Ruby Security Field Guide](https://trailofbits.github.io/rubysec/mutant/index.html).
  25. ## Quick Start
  26. ```ruby
  27. # lib/person.rb
  28. class Person
  29. def initialize(age:)
  30. @age = age
  31. end
  32. def adult?
  33. @age >= 18
  34. end
  35. end
  36. ```
  37. ```ruby
  38. # spec/person_spec.rb
  39. RSpec.describe Person do
  40. describe '#adult?' do
  41. it 'returns true for age 19' do
  42. expect(Person.new(age: 19).adult?).to be(true)
  43. end
  44. it 'returns false for age 17' do
  45. expect(Person.new(age: 17).adult?).to be(false)
  46. end
  47. end
  48. end
  49. ```
  50. Tests pass. But run mutant:
  51. ```bash
  52. gem install mutant-rspec
  53. mutant run --use rspec --usage opensource --require ./lib/person 'Person#adult?'
  54. ```
  55. Mutant finds a surviving mutation indicating a shallow test:
  56. ```diff
  57. def adult?
  58. - @age >= 18
  59. + @age > 18
  60. end
  61. ```
  62. Your tests don't cover `age == 18`. The mutation from `>=` to `>` doesn't break them.
  63. This is just one of many mutation operators. Mutant also mutates arithmetic, logical,
  64. bitwise operators, removes statements, modifies return values, and more.
  65. A full working example is available in the [quick_start](quick_start/) directory.
  66. ## Session History
  67. Mutant records every run to `.mutant/results/`, and keeps the 100 most recent.
  68. You can recall past results without re-running mutation testing:
  69. ```bash
  70. # List past sessions (most recent first)
  71. mutant session list
  72. # Show full report from the latest session
  73. mutant session show
  74. # Show full report from a specific session
  75. mutant session show --session-id 019cf6f1-77e8-74b6-82db-f8b5faf570cd
  76. # List subjects with alive/total mutation counts
  77. mutant session subject
  78. # Show alive mutations for a specific subject
  79. mutant session subject 'Foo::Bar#baz'
  80. # Remove old or incompatible session files
  81. mutant session gc --keep 50
  82. ```
  83. ## Next Steps
  84. 1. Learn the [nomenclature](/docs/nomenclature.md) (subjects, mutations, operators)
  85. 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)
  86. 3. Run mutant on CI in [incremental](/docs/incremental.md) mode
  87. ## Ruby Versions
  88. Mutant is supported on Linux and macOS.
  89. | Version | Runtime | Syntax | Mutations |
  90. | ------- | ------- | ------ | --------- |
  91. | 3.2 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
  92. | 3.3 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
  93. | 3.4 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
  94. | 4.0 | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
  95. ## Rails
  96. Mutant runs against Rails applications, including parallel-worker database
  97. isolation (PostgreSQL and SQLite). The hook recipes are verified in CI on every
  98. non-EOL Rails version:
  99. | Version | Status |
  100. | ------- | ------ |
  101. | 7.2 | :heavy_check_mark: |
  102. | 8.0 | :heavy_check_mark: |
  103. | 8.1 | :heavy_check_mark: |
  104. See the [Rails Integration guide](/docs/rails.md) for setup, eager loading, and
  105. per-worker database isolation. A runnable, CI-verified example lives in
  106. [rails_example](rails_example/).
  107. ## Licensing
  108. **Free for open source.** Use `--usage opensource` for public repositories.
  109. **Commercial use** requires a subscription ($30/month or $250/year per developer).
  110. **Enterprise** — [reach out directly](mailto:info@schirp-dso.com?subject=Mutant%20Enterprise).
  111. See [commercial licensing](/docs/commercial.md) for pricing and details.
  112. ## Documentation
  113. * [Configuration](/docs/configuration.md)
  114. * [RSpec Integration](/docs/mutant-rspec.md)
  115. * [Minitest Integration](/docs/mutant-minitest.md)
  116. * [Test::Unit Integration](/docs/mutant-test-unit.md)
  117. * [Rails Integration](/docs/rails.md)
  118. * [Incremental Mode](/docs/incremental.md)
  119. * [Test Selection](/docs/test-selection.md)
  120. * [Reading Reports](/docs/reading-reports.md)
  121. * [Concurrency](/docs/concurrency.md)
  122. * [AST Pattern Matching](/docs/ast-pattern.md)
  123. * [Session JSON Schema](/docs/session-json-schema.yml)
  124. * [Hooks](/docs/hooks.md)
  125. * [Sorbet](/docs/sorbet.md)
  126. * [Nomenclature](/docs/nomenclature.md)
  127. * [Limitations](/docs/limitations.md)
  128. * [Mutant in the Wild](/docs/in-the-wild.md)
  129. ## Communication
  130. * [Discord](https://discord.gg/BSr62b4RkV)
  131. * [GitHub Issues](https://github.com/mbj/mutant/issues)
  132. * [Release Announcements](https://announce.mutant.dev/signup)
  133. ## Contributing
  134. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
  135. ## Acknowledgments
  136. * [Contributors](https://github.com/mbj/mutant/graphs/contributors)
  137. * The `mutant-minitest` integration was sponsored by [Arkency](https://arkency.com/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.