# Mutation Testing

Run mutant, read mutation reports, fix alive mutations, and verify coverage.

- Repository: https://github.com/ThibautBaissac/rails_ai_agents (671 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-06-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ThibautBaissac/rails_ai_agents --skill mutation-testing -g -a claude-code -y`
Codex: `npx skills add ThibautBaissac/rails_ai_agents --skill mutation-testing -g -a codex -y`
Cursor: `npx skills add ThibautBaissac/rails_ai_agents --skill mutation-testing -g -a cursor -y`
Gemini CLI: `npx skills add ThibautBaissac/rails_ai_agents --skill mutation-testing -g -a gemini-cli -y`

## Description

Run mutant, read mutation reports, fix alive mutations, and verify coverage. Use when running mutation testing, responding to alive mutations, or improving test quality. Triggers: "mutation testing", "mutant", "alive mutation", "mutation coverage". WHEN NOT: Writing tests from scratch (use rspec-agent), fixing failing tests, or general code review.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Mutation Testing with 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 on a subject.

## When Not to Use

- The task does not involve mutation testing.

## Inputs

- Alive mutation output to act on (paste the `evil:` block).
- Optional: subject expression to scope the run.

## Outputs (Fixed Order)

1. Mutation results (alive count, coverage percentage).
2. Clear action for each alive mutation: add test or simplify code.

---

## Reading Mutation 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 (`-`) and mutated (`+`) code.

---

## Reporting Format (BLUF)

Lead with the verdict, 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 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.

---

## Usage

### 1. Run Mutant

```bash
bundle exec mutant run --fail-fast
```

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

```bash
bundle exec mutant run --fail-fast 'Entities::CreateService#call'
```

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

Read the source file and existing spec file for the subject.
Ask: **"Is the mutated code acceptable for all valid inputs?"**

The rest: https://github.com/ThibautBaissac/rails_ai_agents/blob/HEAD/.agents/skills/mutation-testing/SKILL.md