references/mutation-frameworks.md · 24000
nch is untested. Classify as Missing Tests if low CC, Fuzzing Target if high CC or entrypoint-reachable.
- Tweak survived (AOR, ROR, LIR, etc.) → boundary or arithmetic behavior is untested. Good candidates for property-based tests.
- Mutant doesn't compile → skip (slither-mutate already filters these).
Complementary Use with Necessist
For Foundry projects, run both slither-mutate (production code mutations) and
necessist with --framework foundry (test statement removal). When both tools
flag the same function, mark as corroborated in the triage report.
# Production mutations
slither-mutate . --test-cmd "forge test" --comprehensive -v
# Test statement removal (parallel)
necessist --framework foundry
Troubleshooting
| Problem | Solution |
| ------- | -------- |
| slither-mutate: command not found | Install with uv tool install slither-analyzer |
| Test suite fails before mutations | Fix tests first — slither-mutate needs a green baseline |
| No mutants generated | Check --contract-names matches actual contract names (case-sensitive) |
| Timeout too short | Increase --timeout or omit to use 2x baseline auto-detection |
| Wrong framework detected | Use --compile-force-framework foundry (or hardhat, solc) |
| Mutations on library code | Use --ignore-dirs to exclude lib/, node_modules/ |
Universal Mutant Record Format
Regardless of framework, normalize each survived mutant to this schema before feeding into Phase 3 triage:
{
"file_path": "src/parser.py",
"line": 42,
"mutation_type": "arithmetic_operator",
"original": "+",
"replacement": "-",
"function_name": "parse_header",
"status": "survived"
}
Map the containing function name by matching file_path:line against
trailmark graph nodes using their location.start_line and
location.end_line ranges.
Necessist: Test Statement Removal
Necessist complements mutation testing by removing statements and method calls from test code and re-running the tests. If a test still passes after a statement is removed, that statement may be unnecessary — indicating weak assertions or missing coverage.
Mutation testing mutates production code to check if tests detect changes. Necessist mutates test code to check if each test statement is actually needed. Run both when the language supports it.
Supported Frameworks
| Framework | Language | Auto-detected | | --------- | -------- | ------------- | | Anchor | Rust (Solana) | Yes | | Foundry | Solidity | Yes | | Go | Go | Yes | | Hardhat (TypeScript) | TypeScript | Yes | | Rust | Rust | Yes | | Vitest | JavaScript/TypeScript | Yes |
Necessist auto-detects the framework from project files. Use --framework
to override when auto-detection fails.
Install
cargo install necessist
Run
# Auto-detect framework, run on all test files
necessist
# Explicit framework selection
necessist --framework foundry
# Target specific test files
necessist tests/test_parser.rs tests/test_validator.rs
# Set timeout per test (default 60s, 0 = no timeout)
necessist --timeout 120
# Resume a previous run (results stored in SQLite)
necessist --resume
Parse Results
Necessist stores results in a SQLite database by default. Use --dump
to export:
necessist --dump
Each result line contains the test file, line number, the removed statement, and whether the test passed or failed after removal. Filter to passed after removal entries — these are the findings to triage.
Configuration
Create necessist.toml in the project root (necessist --default-config
generates a template):
ignored_functions = ["println", "eprintln", "dbg"]
ignored_methods = ["clone", "to_string", "unwrap"]
ignored_macros = ["debug_assert", "trace"]
ignored_functions— Skip removals of these function callsignored_methods— Skip removals of these method callsignored_macros— Skip removals of these macro invocations
For Foundry projects, consider ignoring common cheatcodes that are
setup-only (e.g., vm.label, vm.deal for labeling/funding).
Normalized Necessist Record Format
Normalize each finding before feeding into Phase 3 triage:
{
"test_file_path": "tests/test_parser.rs",
"test_line": 42,
"removed_statement": "parser.validate(&input)",
"test_function": "test_parse_header",
"status": "passed_after_removal",
"source": "necessist"
}
The source field distinguishes necessist findings from mutation testing
results during triage and reporting. Map the removed statement to a
production function using the graph analysis algorithm.