Configuration

Mutagoph can be configured via YAML file, environment variables, or command-line flags.

Configuration Priority

Configuration is applied in this order (highest priority first):

Command-line flags
Environment variables
Configuration file
Built-in defaults

Configuration Reference

All available configuration options with their defaults:

Option	YAML Key	Environment Variable	Default	Description
Target	`target`	`MUTAGOPH_TARGET`	`./...`	Package pattern to mutate
Files	`files`	`MUTAGOPH_FILES`	(empty)	Specific files to mutate (comma-separated, overrides target)
Lines	`lines`	`MUTAGOPH_LINES`	(empty)	Specific lines to mutate (`file:line` format, comma-separated)
Mutation Set	`mutation_set`	`MUTAGOPH_MUTATION_SET`	`mutilated`	Mutation operators to use: `lite`, `standard`, `thorough`, `mutilated`
Parallelism	`parallelism`	`MUTAGOPH_PARALLELISM`	`dynamic`	Parallelism level: `low`, `medium`, `high`, `mutilated`, `dynamic`
Dynamic Level	`dynamic_level`	`MUTAGOPH_DYNAMIC_LEVEL`	`balanced`	Sub-level when parallelism=dynamic: `minimal`, `balanced`, `comprehensive`, `mutilated`
Timeout	`timeout`	`MUTAGOPH_TIMEOUT`	`30s`	Timeout per mutant test (e.g., `30s`, `1m`, `2m30s`)
Output	`output`	`MUTAGOPH_OUTPUT`	`terminal`	Output format: `terminal`, `json`, `html`
Output File	`output_file`	`MUTAGOPH_OUTPUT_FILE`	(empty)	Path to write output file
Exclude Generated	`exclude_generated`	`MUTAGOPH_EXCLUDE_GENERATED`	`true`	Exclude files with generated code markers
Exclude Vendor	`exclude_vendor`	`MUTAGOPH_EXCLUDE_VENDOR`	`true`	Exclude vendor directory
Coverage Filter	`coverage_filter`	`MUTAGOPH_COVERAGE_FILTER`	`false`	Only test mutations on lines covered by tests
Exclude Patterns	`exclude_patterns`	—	(empty)	Glob patterns for files/directories to exclude
Cache	`cache`	`MUTAGOPH_CACHE`	`true`	Enable caching of test results and coverage data
Cache Dir	`cache_dir`	`MUTAGOPH_CACHE_DIR`	`~/.cache/mutagoph`	Directory to store cache files
Clear Cache	`clear_cache`	`MUTAGOPH_CLEAR_CACHE`	`false`	Clear cache before running
Min Score	`min_mutation_score`	`MUTAGOPH_MIN_MUTATION_SCORE`	`0`	Minimum mutation score (0-100), fail if below
Package Thresholds	`package_thresholds`	—	(empty)	Per-package score thresholds (map of package path to score)

Mutation Sets

Set	Description
`lite`	Minimal mutations, fastest run
`standard`	Common mutation operators
`thorough`	Extended set of operators
`mutilated`	All available mutation operators (default)

Parallelism Levels

Level	Description
`low`	Conservative resource usage
`medium`	Moderate parallelism
`high`	Higher parallelism
`mutilated`	Maximum parallelism (all CPUs)
`dynamic`	Adjusts based on system load (default)

Dynamic Levels

When parallelism: dynamic, the dynamic_level controls how aggressively resources are used:

Level	Description
`minimal`	Very conservative, 1 worker
`balanced`	Moderate, ~25% of CPUs (default)
`comprehensive`	Higher, ~50% of CPUs
`mutilated`	Maximum, all CPUs

Configuration File

Create .mutagoph.yml in your project root:

# Target packages to mutate
target: "./..."

# Mutation set: lite, standard, thorough, mutilated
mutation_set: mutilated  # default

# Parallelism level: low, medium, high, mutilated, dynamic
parallelism: dynamic

# Dynamic parallelism sub-level
dynamic_level: balanced

# Timeout per mutant test
timeout: 30s

# Output format: terminal, json, html
output: terminal

# Exclusions
exclude_generated: true
exclude_vendor: true

# Coverage-based filtering
coverage_filter: false

# Patterns to exclude (glob patterns)
exclude_patterns:
  - "**/testdata/**"
  - "**/mock_*.go"
  - "**/generated/**"

# Caching
cache: true
# cache_dir: ~/.cache/mutagoph

# Quality gate
min_mutation_score: 80.0

# Per-package thresholds
package_thresholds:
  github.com/myorg/myapp/core: 90.0
  github.com/myorg/myapp/utils: 70.0

Supported Filenames

Configuration files are searched in the current directory and parent directories:

.mutagoph.yml
.mutagoph.yaml
mutagoph.yml
mutagoph.yaml

Environment Variables

All options can be set via environment variables with the MUTAGOPH_ prefix:

Variable	Description
`MUTAGOPH_TARGET`	Package pattern to mutate
`MUTAGOPH_FILES`	Specific files (comma-separated)
`MUTAGOPH_LINES`	Specific lines (`file:line` format)
`MUTAGOPH_MUTATION_SET`	Mutation set
`MUTAGOPH_PARALLELISM`	Parallelism level
`MUTAGOPH_DYNAMIC_LEVEL`	Dynamic parallelism sub-level
`MUTAGOPH_TIMEOUT`	Timeout per mutant (e.g., `30s`, `1m`)
`MUTAGOPH_OUTPUT`	Output format
`MUTAGOPH_OUTPUT_FILE`	Output file path
`MUTAGOPH_EXCLUDE_GENERATED`	Exclude generated code (`true`/`false`)
`MUTAGOPH_EXCLUDE_VENDOR`	Exclude vendor directory
`MUTAGOPH_COVERAGE_FILTER`	Coverage-based filtering
`MUTAGOPH_CACHE`	Enable caching
`MUTAGOPH_CACHE_DIR`	Cache directory
`MUTAGOPH_CLEAR_CACHE`	Clear cache before running
`MUTAGOPH_MIN_MUTATION_SCORE`	Minimum mutation score (0-100)

Example

export MUTAGOPH_MUTATION_SET=standard
export MUTAGOPH_MIN_MUTATION_SCORE=80
mutagoph run

CI Configuration

For CI environments, use environment variables:

# GitHub Actions - Basic
- name: Mutation Testing
  env:
    MUTAGOPH_MUTATION_SET: standard
    MUTAGOPH_MIN_MUTATION_SCORE: 70
  run: mutagoph run --diff-base origin/main

# GitHub Actions - Fast mode with coverage filter
- name: Mutation Testing (Fast)
  env:
    MUTAGOPH_MUTATION_SET: standard
    MUTAGOPH_COVERAGE_FILTER: true
    MUTAGOPH_MIN_MUTATION_SCORE: 70
  run: mutagoph run --diff-base origin/main

Coverage Filter

The --coverage-filter flag (or coverage_filter: true in config) enables coverage-based filtering:

Mutations on lines not covered by tests are marked as Naked (skipped)
Significantly speeds up mutation testing by avoiding redundant test runs
Useful when you know certain code paths aren’t tested yet

When to use:

Large codebases with partial test coverage
CI pipelines where speed is important
Incremental testing during development

Note: Naked mutations don’t count as “survived” - they indicate untested code, not weak tests.