CLI Reference¶
Global¶
| Flag | Description |
|---|---|
--version | Print version (irradiate 0.4.3) |
--help | Print help |
irradiate run¶
Run mutation testing
Options¶
| Flag | Default | Description |
|---|---|---|
--mutant <MUTANT> | -- | Filter to specific mutant names (advanced — test only these mutants) |
--paths-to-mutate <PATHS_TO_MUTATE> | -- | Alias for positional paths, for backward compatibility. Prefer positional: irradiate run src/ instead of --paths-to-mutate src/ |
--tests-dir <TESTS_DIR> | -- | Path to test directory (default: "tests", overrides pyproject.toml) |
--workers <WORKERS> | -- | Number of worker processes |
--timeout-multiplier <TIMEOUT_MULTIPLIER> | 10 | Timeout multiplier (applied to baseline test duration) |
--no-stats | -- | Skip stats collection, test all mutants against all tests |
--covered-only | -- | Skip mutants with no test coverage |
--python <PYTHON> | -- | Python interpreter path (auto-detected from venv if not set) |
--max-worker-memory <MAX_WORKER_MEMORY> | -- | Recycle workers whose RSS exceeds this threshold in megabytes. Default: 1024 on macOS, 0 (unlimited) on Linux. Pass 0 to disable |
--no-fork | -- | Disable fork-per-mutant in workers (default on macOS to avoid kernel panics from memory pressure). Slightly less isolation but avoids fork() overhead |
--fork | -- | Force fork-per-mutant even on macOS (overrides --no-fork and the macOS default) |
--isolate | -- | Run each mutant in a fresh subprocess (slower, better isolation) |
--verify-survivors | -- | After the main run, re-test survived mutants in isolate mode to detect false negatives from warm-session state leakage. No-op when --isolate is set |
--fail-under <FAIL_UNDER> | -- | Fail with exit code 1 if mutation score (killed/tested*100) is below this threshold. Value must be between 0.0 and 100.0. Only applied when at least one mutant is tested |
--diff <DIFF> | -- | Only mutate functions changed since this git ref (e.g., main, HEAD~3). Requires a git repository |
--report <REPORT> | -- | Generate a report in the specified format (json = Stryker schema v2) |
-o, --output <OUTPUT> | -- | Output path for the generated report (default: irradiate-report. |
--sample <SAMPLE> | -- | Randomly sample a subset of mutants. Values 0.0-1.0 are fractions (e.g. 0.1 = 10%). Values > 1 are absolute counts (e.g. 100 = test exactly 100 mutants) |
--sample-seed <SAMPLE_SEED> | 0 | RNG seed for --sample (default: 0 for reproducibility) |
--no-cache | -- | Ignore cached results — re-test all mutants from scratch |
--stats-timeout <STATS_TIMEOUT> | 300 | Timeout in seconds for stats collection (default: 300). Increase for large test suites (e.g., 600 for 10K+ tests) |
--pytest-args <PYTEST_ARGS> | -- | Extra arguments to pass to every pytest invocation (appended after config file values). Example: --pytest-args=-v --pytest-args=--tb=short |
--worker-timeout <WORKER_TIMEOUT> | 30 | Timeout in seconds for workers to complete test collection (default: 30). Increase for projects with slow imports (e.g. --worker-timeout 120 for tinygrad/torch) |
--cache-pre-sync <CACHE_PRE_SYNC> | -- | Shell command to run before the mutation testing run (e.g. download remote cache). Overrides cache_pre_sync in pyproject.toml |
--cache-post-sync <CACHE_POST_SYNC> | -- | Shell command to run after the mutation testing run (e.g. upload cache to remote). Overrides cache_post_sync in pyproject.toml |
--type-checker <TYPE_CHECKER> | -- | Run a type checker to filter mutants caught by static analysis. Accepts a preset name (mypy, pyright, ty) or a raw command string. Mutants that introduce type errors are marked as killed (exit code 37) |
--no-source-patch | -- | Disable source-patch mutations for decorated functions. Only trampoline-compatible functions (@property, @classmethod, @staticmethod) will be mutated. Skips the slower source-patch phase |
--ignore <IGNORE> | -- | Glob patterns for files to exclude from mutation. Can be repeated. Merged with do_not_mutate from pyproject.toml |
--operators <OPERATORS> | -- | Only run these mutation operators (allowlist). Supports glob patterns. Can be repeated. Mutually exclusive with --skip-operators |
--skip-operators <SKIP_OPERATORS> | -- | Skip these mutation operators (denylist). Supports glob patterns (e.g., regex_*). Can be repeated. Mutually exclusive with --operators |
-h, --help | -- | Print help |
Examples¶
irradiate run # basic run (auto-detects src/)
irradiate run src/mylib # mutate a specific path
irradiate run --diff main # incremental: changed functions only
irradiate run --fail-under 80 # CI gate
irradiate run --report html -o report.html # HTML report
irradiate run --isolate # full subprocess isolation
irradiate run --verify-survivors # re-check survivors after warm run
irradiate run --python .venv/bin/python # specific interpreter
irradiate run --mutant mylib.x_add__irradiate_3 # test one specific mutant
irradiate run --workers 4 --covered-only # tuning
irradiate run --sample 0.1 # test 10% of mutants (fast CI)
irradiate run --sample 50 --sample-seed 42 # test exactly 50, reproducible
irradiate run --no-cache # ignore cache, re-test everything
irradiate run --ignore "src/vendor/*" # exclude files from mutation
irradiate run --type-checker mypy # filter mutants caught by type checker
irradiate run --pytest-args "--ignore=tests/e2e" # skip a test directory
irradiate results¶
Display mutation testing results
| Flag | Default | Description |
|---|---|---|
--all | -- | Show all mutants, not just survived |
--json | -- | Output machine-readable JSON instead of text |
--report <REPORT> | -- | Generate a report in the specified format (json = Stryker schema v2) |
-o, --output <OUTPUT> | -- | Output path for the generated report (default: irradiate-report. |
-h, --help | -- | Print help |
irradiate show¶
Show diff for a specific mutant
| Argument | Description |
|---|---|
<MUTANT_NAME> | e.g. mylib.x_func__irradiate_1 |
irradiate cache clean¶
Remove the local result cache.
irradiate cache gc¶
Garbage-collect old or excess cache entries
| Flag | Default | Description |
|---|---|---|
--max-age <MAX_AGE> | -- | Maximum age for cache entries (e.g. "30d", "24h", "1h30m"). Default: "30d". Overrides cache_max_age in pyproject.toml |
--max-size <MAX_SIZE> | -- | Maximum total cache size (e.g. "1gb", "500mb"). Default: "1gb". Overrides cache_max_size in pyproject.toml |
--dry-run | -- | Show what would be pruned without deleting anything |
-h, --help | -- | Print help |
Defaults can be set in pyproject.toml via cache_max_age and cache_max_size. See Remote Cache.
Configuration¶
run options can also be set in pyproject.toml under [tool.irradiate]. CLI flags override config. See Configuration.
Mutant name format¶
| Python source | Mutant name |
|---|---|
def add() in mylib | mylib.x_add__irradiate_1 |
class Foo method bar() | mylib.xǁFooǁbar__irradiate_1 |
The x_ prefix avoids collisions. The ǁ (U+01C1) separator encodes class membership.