audit_code_resilience
Uncover unit test gaps by running sandboxed mutation testing on a file, injecting faults to see which ones your tests fail to catch.
Instructions
Runs on-demand, sandbox-isolated mutation testing against a single source file to identify gaps in unit test coverage. Chaos-MCP generates mutants (logical faults like changing > to >=) and checks whether the local test suite catches them. Surviving mutants indicate test coverage holes. Supports TypeScript/JavaScript (StrykerJS), Python (cosmic-ray), Rust (cargo-mutants), and PHP (Infection).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| runId | No | Verify mode by id: re-run against the cached survivor baseline from a prior audit (the runId it returned). Auto-scoped to the baseline lines (StrykerJS) or whole-file (other languages). Mutually exclusive with baseline, diffBase, and lineScope. Example: "a1b2c3d4". | |
| dryRun | No | If true, run only the dry-run phase to validate the test suite passes before mutation testing (StrykerJS only). Useful for pre-flight checks. Example: false | |
| enrich | No | Augment each surviving / no-coverage line with deterministic guidance: severity (high/medium/low), a "why it matters" explanation, a test-writing hint, and a source-context snippet — and rank survivors severity-first. Defaults to TRUE; pass false to disable and return the plain (unranked, unclassified) output. Richest for TypeScript; Python and PHP report severity "unknown". | |
| baseline | No | Verify mode: pass back the `survivors` and `noCoverage` arrays from a PRIOR run to re-test only those mutants and get a delta — which are now killed vs still surviving (plus any new regressions on the same lines). The re-run is auto-scoped to the baseline lines (StrykerJS) or whole-file (other languages). Mutually exclusive with diffBase and lineScope. Example: { "survivors": [{ "line": 42, "mutators": { "ConditionalExpression": 1 } }] } | |
| diffBase | No | Auto-scope mutation to only the lines changed in git. The value selects the base to diff against: "HEAD" (all uncommitted changes), "staged" (staged changes only), or any git ref/branch/SHA (e.g. "main", resolved via merge-base with HEAD). Mutually exclusive with lineScope. Line-level scoping is StrykerJS-only; Python/Rust/PHP targets run whole-file with a note. If the file has no changes vs the base, the run is skipped. Example: "HEAD" | |
| filePath | Yes | Workspace-relative path to the file to audit. Must end in .ts, .js, .tsx, .jsx, .mjs, .cjs, .mts, .cts, .py, .rs, or .php. Example: "src/utils/math.ts" | |
| minScore | No | Gate: if the mutation score is below this (0–100), the result reports gate.passed=false (never an error). Example: 80. | |
| suppress | No | Mark mutants as equivalent (unkillable) so future runs exclude them from the score and output. Appended to .chaos-mcp/suppressions.json for this file, stamped with a fingerprint of the source line so a later edit to that line retires the suppression instead of silently re-pointing it. Re-issue the same entry to re-confirm one reported as drifted or unverified. Example: [{ "line": 42, "mutator": "ConditionalExpression", "reason": "guard unreachable" }]. | |
| lineScope | No | Constrain mutations to a 1-based line range (inclusive). Only supported by StrykerJS; ignored for Python, Rust, and PHP targets. Useful for surgically auditing a specific function or block. Example: { "start": 10, "end": 45 } | |
| timeoutMs | No | Maximum time in milliseconds for the entire mutation run. Default: 300000 (5 minutes). Increase for large files or slow test suites. Must be <= 2147483647 (the largest delay a timer accepts). Example: 120000 for a 2-minute cap. | |
| unsuppress | No | Remove previously-suppressed mutants for this file (undo a wrong suppress). | |
| concurrency | No | Number of parallel mutation workers (StrykerJS only). When omitted, StrykerJS auto-detects CPU core count. Lower this on memory-constrained machines; raise it on CI with spare cores. Must be an integer between 1 and 64. Example: 4 | |
| incremental | No | Enable incremental mode to reuse results from a previous run and skip unchanged mutants (StrykerJS only). Speeds up repeat audits of the same file. Example: true | |
| maxSurvivors | No | Cap on how many survivor (and how many no-coverage) line groups are returned, after severity ranking. Hidden groups are counted in survivorsTruncated/noCoverageTruncated. Precedence: this arg > config.defaultMaxSurvivors > 10. Example: 20 | |
| outputFormat | No | Output format for the result. "json" (default) returns a structured MutationResult object. "text" returns a human-readable summary. Example: "json" | |
| severityFloor | No | Report-time filter: drop survivor groups below this severity (requires enrichment, which is on by default). Dropped groups are counted in survivorsFiltered/noCoverageFiltered. "unknown"-severity groups are below "low" and are dropped by any floor. Ignored (with a note) when enrich is false. Example: "high" | |
| ignorePatterns | No | Substring patterns for files/directories to exclude from the sandbox copy, applied in addition to built-in exclusions. Any path containing the pattern string is skipped. Example: [".test.ts", "fixtures/", "snapshots/"] | |
| mutatorDenylist | No | Stryker mutator names to exclude — these are filtered out. StrykerJS only. Useful for skipping noisy or irrelevant mutators. Example: ["StringLiteral"] | |
| prebuildCommand | No | Shell command to run in the sandbox BEFORE mutation testing begins. Use this to compile/build the target — the sandbox has a full workspace copy. Essential for TypeScript projects ("npm run build") and Rust projects ("cargo build"). DISABLED BY DEFAULT: because it runs an arbitrary shell command that can reach outside the sandbox, the server must opt in via "allowPrebuild": true in its config file or the CHAOS_MCP_ALLOW_PREBUILD=1 environment variable. Counts against the overall timeoutMs budget. Example: "npm run build" | |
| mutatorAllowlist | No | NOT SUPPORTED in StrykerJS v9 — REJECTED: passing this fails the call with an error. v9 has no way to express "only these mutators" without the full mutator list. Use mutatorDenylist to exclude noisy mutators instead, or supply your own stryker.config.json. | |
| perMutantTimeoutMs | No | Maximum time in milliseconds per individual mutant test (StrykerJS only). Distinct from timeoutMs (total run cap). Use this to prevent a single slow mutant from hanging the entire mutation run. Default: StrykerJS default (~5000ms). Must be <= 2147483647 (the largest delay a timer accepts). Example: 10000 for a 10-second per-mutant ceiling. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gate | No | ||
| mode | No | ||
| note | No | ||
| runId | No | ||
| target | No | ||
| summary | No | ||
| complete | No | ||
| nowKilled | No | ||
| scopeNote | No | ||
| survivors | No | ||
| enrichNote | No | ||
| noCoverage | No | ||
| incompetent | No | ||
| killedCount | No | ||
| fidelityNote | No | ||
| newSurvivors | No | ||
| baselineTotal | No | ||
| mutationScore | No | ||
| stoppedReason | No | ||
| batchesPlanned | No | ||
| ignoredOptions | No | ||
| stillSurviving | No | ||
| suppressedCount | No | ||
| batchesCompleted | No | ||
| suggestedTestFile | No | ||
| survivorsFiltered | No | ||
| noCoverageFiltered | No | ||
| survivorsTruncated | No | ||
| driftedSuppressions | No | ||
| noCoverageTruncated | No | ||
| unverifiedSuppressions | No |