audit_code_resilience
Run mutation testing on a source file to expose gaps in unit test coverage. It generates code mutants, runs your test suite, and pinpoints survivors that reveal untested logic.
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). PATHS: filePath is resolved against the SERVER's working directory (or given absolute). The target in the result is relative to the audited file's own WORKSPACE, which differs whenever the file sits in a monorepo package or another root — packages/api/src/math.ts comes back as src/math.ts. When the two differ the result carries workspace (an absolute path) and join(workspace, target) is a filePath you can pass straight back; when it is absent, target already is one. A file from triage_test_coverage is always a valid filePath as-is.
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 | Path to the file to audit, resolved against the server's working directory (an absolute path is also accepted). NOT relative to the audited file's workspace — in a monorepo that is the package root, and the two differ. 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. A suppression is identified by its mutator and the CHANGE it makes, not by its line, so it follows the code when an edit moves it. Supply `change` (the "original → mutated" string from a survivor's `changes`) to name WHICH mutant when one line carries several of the same mutator; omit it and Chaos-MCP resolves it from this run's survivors, refusing the entry rather than suppressing all of them if several match. 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). Supply `change` to remove one specific entry; omit it to remove every entry for that mutator. The `line` is ignored when matching, so an entry that has relocated is still removable. | |
| concurrency | No | Number of parallel mutation workers. Honoured by StrykerJS (--concurrency), cargo-mutants (-j) and Infection (--threads); cosmic-ray has no worker flag and reports this as an ignored option. When omitted, StrykerJS auto-detects CPU core count while cargo-mutants deliberately stays low (2 jobs, or 1 on a small machine) because each job wants its own multi-GB target directory. 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 | Path segments for files/directories to exclude from the sandbox, applied in addition to built-in exclusions. A path is skipped when any of its segments equals the pattern exactly. This now also suppresses the dependency-directory link, so excluding "node_modules" leaves the sandbox without it — which will usually break the run. A pattern is never a suffix or a substring: ".test.ts" excludes only a path segment named exactly that, not "billing.test.ts". One trailing separator is stripped, so "fixtures/" and "fixtures" are the same pattern. Example: ["fixtures/", "testdata"] | |
| 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 by StrykerJS — 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 and Rust). 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 | ||
| resources | No | ||
| scopeNote | No | ||
| survivors | No | ||
| workspace | No | Absolute workspace root that `target` is relative to. Present only when that root is not the server's working directory (a monorepo package, or another root via CHAOS_ALLOWED_ROOTS). `join(workspace, target)` is a path this tool accepts as `filePath`; when the field is absent, `target` already is one. | |
| enrichNote | No | ||
| noCoverage | No | ||
| incompetent | No | ||
| killedCount | No | ||
| coverageNote | No | ||
| fidelityNote | No | ||
| newSurvivors | No | ||
| baselineTotal | No | ||
| coverageScope | No | ||
| mutationScore | No | ||
| stoppedReason | No | ||
| batchesPlanned | No | ||
| ignoredOptions | No | ||
| stillSurviving | No | ||
| suppressedCount | No | ||
| batchesCompleted | No | ||
| unsuppressMissed | No | ||
| suggestedTestFile | No | ||
| survivorsFiltered | No | ||
| unsuppressedCount | No | ||
| noCoverageFiltered | No | ||
| survivorsTruncated | No | ||
| driftedSuppressions | No | ||
| noCoverageTruncated | No | ||
| orphanedSuppressions | No | ||
| rejectedSuppressions | No | ||
| relocatedSuppressions | No | ||
| unverifiedSuppressions | No |