mutant

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:

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:

(test diff)

Option B — simplify code:

(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:

   bundle exec mutant run --fail-fast
   

   When the subject is already known, scope the run to avoid testing unrelated subjects:

   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:

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:

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.