AutoGineer
Generated banner for Mutation Testing
Generated logo for Mutation Testing

Mutation Testing

Trail of BitsOfficialPublished by Trail of Bits

  • Skill
  • Tool integration
  • Software development
  • CC-BY-SA-4.0
  • No issues found
Download ZIP

From the author

Configures mewt or muton campaigns, analyzes surviving mutants, and investigates bugs exposed by testing gaps. Use when setting up mutation testing, reviewing campaign results, identifying equivalent mutants, or finding bugs from surviving mutations.
— the description by Trail of Bits

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to mutation testing using the mewt or muton tools. It guides users through the entire lifecycle of a mutation testing campaign, from initial configuration and execution to the analysis of surviving mutants. By systematically injecting faults into source code and observing test behavior, it helps developers distinguish between equivalent mutants and genuine testing gaps, ultimately revealing bugs that standard coverage metrics might miss.

What it does

  • Configures and executes mutation testing campaigns via mewt or muton.
  • Provides commands to filter, inspect, and re-test specific mutants.
  • Categorizes mutation results into caught, uncaught, timeout, or skipped outcomes.
  • Offers a framework for identifying equivalent mutants to reduce false positives.
  • Prioritizes investigation based on mutation severity and language-specific patterns.
  • Supports advanced analysis for blockchain-specific constructs like Solidity and Move.

When to use it

  • When you need to validate the effectiveness of your existing test suite.
  • When you want to identify untested code paths or weak assertions.
  • When you need to analyze why specific mutants survived your test execution.
  • When you are working on a project that requires high-assurance testing, such as blockchain smart contracts.

Advantages

  • Uncovers subtle bugs that traditional line coverage metrics fail to detect.
  • Provides a clear, actionable workflow for triaging and resolving surviving mutants.
  • Reduces noise by helping developers identify and ignore semantically equivalent mutants.
  • Enables targeted re-testing of specific code segments to verify fixes.

Usage examples

“Run a mutation testing campaign on the src/auth directory.”
The agent will execute the mutation campaign specifically targeting the auth module and provide a summary of the results.
“Show me all uncaught mutants in the current project.”
The agent will list the surviving mutants, allowing you to investigate potential testing gaps.
“How do I investigate a high-severity surviving mutant?”
The agent will guide you through inspecting the mutated code and suggest how to write a test to catch it.
“Is this mutant equivalent to the original code?”
The agent will apply the verification procedure to help you determine if the mutation is semantically identical or a genuine testing gap.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/trailofbits/mutation-testing/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip mutation-testing.zip -d .agents/skills

Documentation by Trail of Bits

Mutation Testing (mewt/muton)

Routes to the right mutation testing workflow and loads the references that workflow needs.

Note: muton and mewt share identical interfaces. Examples use mewt; substitute muton and its file names (muton.toml, muton.sqlite) for muton projects.

mewt --help and mewt <subcommand> --help are the source of truth for command-line behavior. Examples below reflect the mewt 4.x API; run --help when a flag looks unfamiliar or a command fails.

When to Use

Use this skill when the user:

  • Mentions "mewt", "muton", or "mutation testing"

  • Wants to configure, scope, or speed up a mutation testing campaign

  • Wants to analyze mutation results — surviving/uncaught mutants, equivalent mutants, kill rate

  • Wants to use mutation results to find bugs in the source code

When NOT to Use

Do not use this skill when the user asks about tests or line coverage without any mutation testing context.

Routing

Pick the workflow, then load it together with the references listed for it. Workflows and references do not load each other — that decision belongs here.

Setting up, scoping, or speeding up a campaign → workflows/configuration.md → Also load references/optimization-strategies.md when the campaign estimate is long enough to need trimming, or the user asks to make it faster.

Campaign finished, hunting for bugs in untested code → workflows/bug-hunter.md

Turning results into a formal analysis report → workflows/analyzing-results.md, plus:

Anything else → run mewt --help or mewt <subcommand> --help, then assist directly.

Essential Commands

# Set up and run
mewt init                    # Create config and database
mewt mutate [paths]          # Generate mutants without testing them
mewt run [paths]             # Generate mutants and run the campaign

# Read results
mewt status                  # Overview with per-file breakdown
mewt results                 # Uncaught mutants (default view)
mewt results --all           # Every outcome, not just uncaught
mewt results --format json   # json | sarif | ids | table

# Narrow down (these filters work on both `results` and `print mutants`)
mewt results --target 'src/auth/**'   # Quote globs so the shell does not expand them
mewt results --severity high,medium
mewt results --mutation-types ER,CR
mewt results --status Uncaught        # Uncaught | TestFail | Skipped | Timeout
mewt results --line 42

# Investigate and re-test
mewt print mutant --id [id]              # View the mutated code
mewt test --ids [ids]                    # Re-test specific mutants
mewt test --ids-file uncaught_ids.txt    # Re-test IDs from a file, or '-' for stdin

# Inspect configuration
mewt print config                        # Effective config
mewt print targets                       # Files actually mutated
mewt print mutations --language [lang]   # Mutations and severities for a language

Language labels are canonical family or family/dialect values in mewt 4.x — for example rust, javascript/ts, move/sui, move/iota.

What Results Mean

  • Caught/TestFail: tests detected the mutation (good)

  • Uncaught: tests did not detect the change. Inspect the code to distinguish a testing gap from an equivalent mutation.

  • Timeout: tests took too long — inconclusive, not evidence of coverage

  • Skipped: a less severe mutant was skipped because a more severe mutant on the same line was uncaught

Interpreting Mutation Types

mewt print mutations --language [lang] lists every mutation slug, description, and severity for a language, and is authoritative — the operator set grows with each release. What that output does not tell you is what a survivor means, which is where prioritization comes from:

SeverityRepresentative slugsWhat an uncaught mutant tells you
HighER (Error Replacement)Tests tolerate the injected error. Investigate whether the path executes, whether error handling masks the change, and whether assertions check the outcome.
MediumCR (Comment Replacement)Removing the statement does not fail the tests. Check whether its effects matter and whether assertions observe them.
MediumIF/IT (If False/True), NR (Negation Removal)Tests do not distinguish the changed condition. Both constant replacements surviving can indicate an unexecuted condition or weak assertions on the branch outcomes.
LowOperator shuffles (AOS, COS, LOS, BOS, shift/assignment variants), BL, AS, LC, WFCheck boundary inputs, arithmetic assertions, and semantic equivalence. The mutation result alone does not establish whether the code executed.

Severity ranks the mutation, not the risk. A low-severity survivor in a fee calculation matters more than a high-severity survivor in a log line — weigh what the mutated code does. Filter with --severity to work through the results in priority order.

Files

references/report-template.md

Mutation Testing Analysis Report

Project: [Project Name] Repository: [Repository URL or Path] Analysis Date: [Date] Mutation Testing Tool: [Tool Name and Version] Analyzer: [Agent and model, if known] with mutation-testing skill

Executive Summary

MetricValue
Total mutants generated[N]
Mutants killed[N]
Mutants survived[N]
Equivalent mutants (false positives)[N]
Real surviving mutants[N]
Unresolved survivors[N]
Skipped or inconclusive mutants[N]
Mutation kill rate (raw)[N]%
Adjusted kill rate (excluding equivalent)[N]%
Key Findings

[Describe the concrete testing gaps, affected behavior, and recommended tests. Explain the campaign's scope and rate denominators. Do not infer overall test quality from the adjusted kill rate. These findings concern weaknesses in tests, not confirmed vulnerabilities in the original code.]

Severity Distribution
Severity TierCountPercentage of Real Survivors
Critical (Security-Sensitive)[N][N]%
High (Financial/State Integrity)[N][N]%
Medium (Business Logic)[N][N]%
Low (Observability)[N][N]%

Equivalent Mutants (False Positives)

[One to two sentences explaining what equivalent mutants are and how many were identified in this analysis.]

#FileLineMutationEquivalence Reason
1[path/to/file][N][original] → [mutated][Brief explanation of why this is a false positive]

Tier 1: Critical — Security-Sensitive Findings

[One sentence introducing the tier and the number of findings.]

Finding C-1: [Descriptive title]

File: [path/to/file] Line: [N] Mutation: [original code] → [mutated code] Mutation Operator: [operator type, if known]

Context: [One to two sentences describing what the mutated code does and what security property it enforces.]

Responsible test file(s): [path/to/test/file] Relevant test case(s): [test function name(s)]

Why this was not caught: [One to two paragraphs. Reference the existing test code and explain what assertion, branch, or edge case is missing. Be specific about the gap.]

Recommended test improvement: [Specific, actionable description of what to add or modify in the test. Do not include code snippets — describe the change in prose.]

[Repeat for each Tier 1 finding: C-2, C-3, ...]

Tier 2: High — Financial/State Integrity Findings

[One sentence introducing the tier and the number of findings.]

Finding H-1: [Descriptive title]

[Same structure as Tier 1 findings.]

[Repeat for each Tier 2 finding: H-2, H-3, ...]

Tier 3: Medium — Business Logic Findings

[One sentence introducing the tier and the number of findings.]

Finding M-1: [Descriptive title]

[Same structure as Tier 1 findings.]

[Repeat for each Tier 3 finding: M-2, M-3, ...]

Tier 4: Low — Observability Findings

[One sentence introducing the tier and the number of findings.]

Finding L-1: [Descriptive title]

[Same structure as Tier 1 findings.]

[Repeat for each Tier 4 finding: L-2, L-3, ...]

Recommendations

Organize all recommendations by test file, grouping related improvements across severity tiers. For each test file, list the findings it should address and summarize the changes needed.

Unresolved Cases

[For each unresolved survivor, state its location, the uncertain behavior, and the evidence needed to classify it. Omit this section if there are none.]

Appendix

Input Files Analyzed

  • [List of mutation result input files provided by the user]

Source Files with Surviving Mutants
FileTotal SurvivingCriticalHighMediumLow
[path/to/file][N][N][N][N][N]
Methodology

This analysis follows Trail of Bits' mutation testing analysis methodology. Surviving mutants are classified by the impact type of the mutated code, not by the mutation operator used. Equivalent mutants are identified through type-system analysis and reachability checks. For background on mutation testing, see the Trail of Bits blog post "Use mutation testing to find the bugs your tests do not catch."

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Trail of Bits
Publisher
Trail of Bits (Official)
Source
trailofbits/skills · plugins/mutation-testing/skills/mutation-testing · commit e4dd0bb
Licence
Creative Commons Attribution-ShareAlike 4.0 International (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Trail of Bits.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download mutation-testing.zip