mutation-guard

Mutation Guard

Test quality analysis through mutation testing for Claude Code.

The problem: 90% code coverage doesn't mean your tests catch bugs. Tests can execute code without verifying behavior — giving false confidence.

The solution: Mutation Guard injects small bugs (mutants) into your code and checks if tests catch them. If a test passes with a bug injected, that test has a gap.

Installation

claude plugins add github:rezafarzaneh7/claude-code-plugins/plugins/mutation-guard

Usage

Two commands — analyze first, then fix:

# Step 1: See the gaps
/mutation-guard ./services

# Step 2: Fix them
/mutation-guard-fix ./services

Path Options

Path Type	Example
Subdirectory	/mutation-guard ./services
Package tree (Go)	/mutation-guard ./internal/...
Full repo	/mutation-guard ~/projects/my-service
Current dir	/mutation-guard .

Tip: Start small. Analyze a single directory first — mutation testing is slow on large scopes.

What You Get

/mutation-guard — Analyze

Produces a quality report with:

• Coverage analysis — per-file line coverage with status indicators
• Mutation testing — survived mutants ranked by priority (Critical → High → Medium)
• Impact analysis — concrete production risk for each gap
• Quality matrix — detects "false confidence" (high coverage + low mutation score)
• Baseline tracking — shows trends across runs

/mutation-guard-fix — Fix

Writes the missing tests:

• Reads your existing test patterns and matches them exactly
• Writes tests that kill survived mutants (Critical first)
• Verifies all new tests pass
• Produces a before/after comparison report

Example Output

Quality Report (abbreviated)

## Mutation Guard — Quality Report

**Project**: my-service
**Language**: Go
**Scope**: ./services

### TL;DR

| Metric          | Score  | Trend |
|-----------------|--------|-------|
| Coverage        | 72.4%  | 🆕    |
| Mutation Score  | 58.3%  | 🆕    |
| Quality Verdict | ⚠️ False Confidence | ⚠️ |

High coverage masks weak assertions — 5 critical gaps found.

### Part 4: Quality Matrix

| # | File              | Coverage | Mutation | Verdict            |
|---|-------------------|----------|----------|--------------------|
| 1 | `handler.go`      | 89.2%    | 42.1%    | ⚠️ False Confidence |
| 2 | `service.go`      | 76.5%    | 71.4%    | 🟡 Partial          |
| 3 | `repository.go`   | 45.0%    | 33.3%    | 🔴 Critical          |

Fix Report (abbreviated)

## Mutation Guard — Fix Report

### TL;DR

> 7 tests written | 5 mutants killed
> Coverage: 72.4% → 84.1% (↑ +11.7%)
> Mutation Score: 58.3% → 78.9% (↑ +20.6%)

### Before / After

| Metric          | Before | After  | Change     |
|-----------------|--------|--------|------------|
| Coverage        | 72.4%  | 84.1%  | ↑ +11.7%   |
| Mutation Score  | 58.3%  | 78.9%  | ↑ +20.6%   |
| Survived mutants| 10     | 5      | -5         |

Supported Languages

Language	Status	Coverage Tool	Mutation Tool
Go	✅ Active	go test -cover	go-mutesting
PHP	🔜 Planned	phpunit --coverage	Infection
Node.js	🔜 Planned	jest --coverage / nyc	Stryker
Java	🔜 Planned	jacoco	PIT
Rust	🔜 Planned	cargo tarpaulin	cargo-mutants

Baseline Tracking

Mutation Guard saves results to .mutation-guard/baseline.json in your project root. Subsequent runs show trends (↑/↓/→) compared to the previous baseline — so you can track quality improvements over time.

Add .mutation-guard/ to your .gitignore or commit it to track quality in your repo history.

Key Principles

• Coverage ≠ Quality — line coverage measures execution, mutation score measures verification
• Never modifies source code — only test files are created or edited
• Matches your patterns — reads existing tests and follows the same conventions
• Explains every fix — you understand what risk each new test eliminates

More Info

See the main repository for all available plugins.