Rails Integration & Boot Mode

Relevant source files

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

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

Mutineer provides a specialized execution mode for Ruby on Rails applications. This mode optimizes the mutation testing process by booting the Rails environment once and then forking workers to run tests against specific mutants. This architecture reduces the overhead of repeatedly loading the Rails framework for every mutation.

Overview of Rails Integration

Mutineer integrates with Rails through the --rails flag or the rails: true configuration key. This setting triggers a "boot mode" that loads the Rails environment before starting the mutation run. It primarily targets models and services but can be extended to any source directory within a Rails project.

Sources: lib/mutineer/cli.rb:142, lib/mutineer/init.rb:112-120

Initialization and Configuration

You can initialize a Rails-ready configuration by running mutineer init --rails. This command performs several setup actions:

• It creates a .mutineer.yml file with rails: true.
• It automatically identifies standard Rails directories like app/models and app/services if they exist.
• It provides commented-out options for the daemon mode, which is the recommended path for parallel execution in Rails.

Sources: lib/mutineer/init.rb:111-122, test/init_test.rb:30-40

Boot Mode Architecture

Boot mode utilizes a parent process to load the application environment once. For each mutation, Mutineer forks a worker process. This worker process inherits the booted environment, applies a mutation, and runs the relevant tests.

The diagram shows the lifecycle of a mutation test in boot mode, where the expensive boot process happens only once in the parent.

Sources: lib/mutineer/cli.rb:111-115, lib/mutineer/reporter.rb:140-150

Execution Strategies

When Rails integration is active, Mutineer adjusts its default behavior to ensure compatibility with the Rails framework.

Strategy	Behavior in Rails Mode
redefine	Surgical mutation applied to the existing VM. This is the default when --rails is used without a daemon.
reload	Whole-file reloading. This is forced when using the --daemon mode.

Sources: lib/mutineer/cli.rb:298-311, test/config_test.rb:316-324

Parallelism and Daemon Mode

Parallel execution in Rails requires careful management of shared resources, specifically the database.

Serial vs. Parallel Execution

By default, enabling --rails forces the worker count to 1 (serial execution) if no daemon is used. This prevents multiple workers from conflicting on the same database instance.

• Serial Execution: The strategy defaults to redefine and --jobs is forced to 1.
• Parallel Execution: Requires the --daemon flag. The daemon mode provides per-worker database isolation for SQLite, PostgreSQL, and MySQL.

Sources: lib/mutineer/cli.rb:156-160, lib/mutineer/cli.rb:303-311, test/config_test.rb:584-596

Daemon Mode Constraints

The --daemon mode introduces specific constraints to maintain environment stability:

• It supports only the minitest framework (RSpec support is not yet implemented for the daemon).
• It ignores the --timeout setting, as the daemon manages its own per-mutant limits.
• It forces the reload strategy.

Sources: lib/mutineer/cli.rb:300-315

Technical Constraints and Validation

Mutineer performs several pre-flight checks when Rails or boot mode is active to prevent invalid states.

Validation Rules

• Source Paths: If no source folder is found during init --rails (e.g., no app/models), the command prints an error.
• Test Requirement: Using --boot or --rails requires at least one --test file to be provided or inferred.
• Framework Detection: Mutineer auto-detects the framework (minitest or rspec) from the test file names. If a mix is found, it defaults to minitest.
• Database Isolation: When running in parallel without a daemon, Mutineer warns the user and forces --jobs 1 unless the user explicitly opts into the daemon.

Sources: lib/mutineer/cli.rb:271-274, lib/mutineer/cli.rb:305-310, test/init_test.rb:71-80, test/config_test.rb:601-615

Summary

The Rails Integration & Boot Mode provides a high-performance path for mutation testing Rails applications. By leveraging process forking and optional daemon-based database isolation, it allows developers to run comprehensive mutation suites with minimal overhead. While it defaults to safe, serial execution, the system is designed to scale to parallel workloads using the persistent daemon backend.

Sources: lib/mutineer/cli.rb, lib/mutineer/init.rb, action.yml