.mutineer.yml Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• lib/mutineer/config.rb
• lib/mutineer/cli.rb
• lib/mutineer/init.rb
• action.yml
• lib/mutineer/reporter.rb

The .mutineer.yml file defines project-specific settings for mutation testing. It allows you to persist configurations like mutation operators, thresholds, and execution strategies. Mutineer searches for this file in the current working directory and walks up to the user's home directory until it finds a match.

Sources: lib/mutineer/config.rb:141-155, lib/mutineer/cli.rb:182-184

Configuration Precedence and Resolution

Mutineer resolves configuration through a specific hierarchy. Command-line flags always override values defined in .mutineer.yml. If neither a flag nor a YAML key is present, Mutineer applies a default value.

The diagram shows the data flow from discovery to the final resolved configuration object used during execution.

Sources: lib/mutineer/config.rb:215-225, lib/mutineer/cli.rb:182-189

Configuration Options Reference

The following table summarizes the keys available in .mutineer.yml, their data types, and corresponding CLI flags.

YAML Key	Type	CLI Flag	Description
operators	String List	--operators	List of mutation operators to apply.
jobs	Positive Int	--jobs	Number of parallel worker processes.
threshold	Percent	--threshold	Minimum score percentage to pass the gate.
only	String	--only	Restricts mutation to one subject.
require	String List	N/A	Extra files to load before running.
boot	String	--boot	File to boot the application environment.
rails	Boolean	--rails	Enables Rails-specific environment booting.
since	Git Ref	--since	Scopes mutations to lines changed since a ref.
framework	Enum	--framework	Testing framework: minitest or rspec.
ignore	Ignore List	N/A	List of mutant IDs to suppress.
baseline	String	--baseline	Path to a JSON report for delta gating.
strategy	Enum	--strategy	reload (whole-file) or redefine (surgical).
daemon	Boolean	--daemon	Boots app in a persistent daemon process.

Sources: lib/mutineer/config.rb:45-71, lib/mutineer/cli.rb:84-125

Initialization

You generate a starter .mutineer.yml file using the mutineer init command. This command writes a template containing default operators and common settings.

This sequence illustrates the process of creating a new configuration file.

Sources: lib/mutineer/init.rb:20-63

Template Structure

The standard template includes a commented-out since key to encourage full scans on the first run. If you use the --rails flag, the template includes rails: true and a commented daemon setting.

Sources: lib/mutineer/init.rb:71-92

Advanced Configuration Logic

Rails Mode

When you set rails: true, Mutineer modifies several behaviors:

• It defaults the boot file to config/environment.
• It sets the execution strategy to redefine for in-process runs.
• It forces jobs to 1 unless --daemon is active to prevent database contention.

Sources: lib/mutineer/config.rb:229-245, lib/mutineer/cli.rb:304-311

Ignore Lists

The ignore key accepts mutant IDs to skip during testing. You can provide these as a list of strings or as mappings containing an id and a reason.

ignore:
  - "MutantID1"
  - id: "MutantID2"
    reason: "Equivalent mutant"

Sources: lib/mutineer/config.rb:396-415

Git Scoping

The since key supports Git references. Setting since: false in YAML explicitly disables diff scoping, even if a default or environment variable suggests otherwise.

Sources: lib/mutineer/config.rb:355-364, action.yml:143-149

Configuration Validation

Mutineer validates all inputs during resolution. Invalid values like negative jobs or out-of-range thresholds raise a ConfigError.

Constraint	Requirement
jobs	Must be a positive integer.
threshold	Must be a float between 0.0 and 100.0.
operators	Must name at least one known operator.
cache_dir	Must not be a blank string.

Sources: lib/mutineer/config.rb:315-350

Summary

The .mutineer.yml file serves as the persistent configuration layer for the Mutineer library and GitHub Action. It integrates CLI flag overrides with project-specific defaults to control mutation testing scope, execution strategy, and CI gating thresholds. Correct configuration ensures stable mutant IDs and reliable test results across different environments.

Sources: lib/mutineer/config.rb:78-86, lib/mutineer/cli.rb:202-214