Rails App Fixtures Integration

Relevant source files

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

• test/init_test.rb
• lib/mutineer/init.rb
• lib/mutineer/cli.rb
• test/cli_test.rb
• test/site_docs_test.rb
• action.yml
• AGENTS.md

Rails App Fixtures Integration provides a specialized environment for mutation testing Ruby on Rails applications. It automates the configuration of Rails-specific source directories and ensures that the testing environment boots correctly through standard Rails entry points.

This integration manages the lifecycle of the Rails environment during mutation runs, supporting either in-process execution or a persistent daemon mode for parallel processing. It specifically targets common Rails patterns such as models and services while maintaining zero runtime dependencies in the core gem.

Sources: lib/mutineer/init.rb, lib/mutineer/cli.rb, AGENTS.md

Initialization and Configuration

You initialize a Rails project by running mutineer init --rails. This command scans the local directory for standard Rails folders and generates a tailored .mutineer.yml configuration file.

Automated Directory Discovery

The initialization logic searches for specific directories to include in the default run command. If these directories exist, it includes them in the output:

• app/models
• app/services
• lib

If none of these folders are found, the tool writes the configuration but warns that no source folder was found.

Sources: lib/mutineer/init.rb:96-107, test/init_test.rb:34-45

Configuration Parameters

The following table describes Rails-specific configuration options available in the project.

Option	Type	Description
rails	Boolean	Boots config/environment once. Defaults to redefine strategy and serial execution without a daemon.
boot	String	Specifies a file to require once in the parent process to boot the application environment.
daemon	Boolean	Boots the app once in a persistent daemon. Enables per-worker DB isolation for safe parallel execution.

Sources: lib/mutineer/cli.rb:55-66, action.yml:45-53

Technical Workflow

The integration follows a specific sequence to ensure the Rails environment is stable before mutation begins.

Boot Sequence

When you use the --rails flag, the system performs several validation and setup steps:

1. Validation: The system requires at least one --test file when --boot or --rails is active.
2. Environment Boot: It requires config/environment to load the Rails application.
3. Strategy Selection: It defaults the mutation strategy to redefine (surgical) and forces the worker count to 1 unless --daemon is enabled.

Sources: lib/mutineer/cli.rb:216-224, lib/mutineer/cli.rb:304-307

Process Management

The following diagram illustrates the flow from initialization to execution for a Rails application.

The persistent daemon mode allows for parallel worker execution by providing database isolation, which is critical for Rails test suites that interact with a database.

Sources: lib/mutineer/cli.rb:71-80, lib/mutineer/init.rb:76-94

Execution Strategies

Rails integration supports two primary execution backends:

In-Process Redefinition

By default, Rails runs use the redefine strategy. This strategy performs surgical redefinition of methods within the same Ruby VM. Because Rails applications often share a single database connection in-process, the worker count is forced to 1 to prevent race conditions and data corruption.

Sources: lib/mutineer/cli.rb:304-307, test/config_test.rb:296-302

Persistent Daemon

The --daemon flag enables a more performant execution model.

• Boot Once: The application boots only once in a background process.
• Worker Isolation: It uses per-worker database isolation (supported for SQLite, PostgreSQL, and MySQL).
• Parallelism: This mode allows jobs > 1 to be safe under Rails.

Sources: lib/mutineer/cli.rb:64-69, lib/mutineer/cli.rb:323-338

Integration Testing

Testing for Rails features is decoupled from the main zero-dependency suite.

• Rails Fixtures: A specific Rails application fixture is located in test/fixtures/rails_app.
• Daemon Tests: You must run Rails-dependent tests via bundle exec rake test:daemon.
• CI Integration: The rails dogfood and daemon integration jobs run in CI to verify these features without polluting the core gem suite.

Sources: AGENTS.md:21-25, AGENTS.md:37-38

Summary

The Rails App Fixtures Integration ensures that Mutineer can effectively test Rails applications by automating directory discovery, managing complex boot sequences, and providing isolated execution environments. By defaulting to safe serial execution while offering a high-performance daemon mode, the system balances accuracy with speed for database-backed Ruby applications.