parallel_tests

To use parallel_tests in a Rails project, add the gem to your Gemfile within the :development and :test groups.

gem 'parallel_tests', group: [:development, :test]

Run your test suites in parallel using the corresponding Rake tasks:

• Minitest: rake parallel:test
• RSpec: rake parallel:spec
• Cucumber: rake parallel:features
• Spinach: rake parallel:features-spinach

You can also run tests matching a specific regex pattern:

# Run all tests in the test/unit folder
rake "parallel:test[^test/unit]"

# Run RSpec tests except those in spec/features
rake "parallel:spec['spec\/(?!features)']"

Use the following Rake tasks to manage the multiple databases required for parallel testing:

• Create databases: rake parallel:create (or rake parallel:create:<database> for multi-db setups).
• Prepare databases: rake parallel:prepare (copies the development schema into all test databases; run this after migrations).
• Run migrations: rake parallel:migrate (or rake parallel:migrate:<database> for multi-db setups).
• Setup from scratch: rake parallel:setup (creates databases and loads schema; useful for CI).
• Drop databases: rake parallel:drop (or rake parallel:drop:<database> for multi-db setups).

ParallelTests requires one database per test process. Use the ENV['TEST_ENV_NUMBER'] environment variable to append a unique suffix to your database name. Note that for the first process, this environment variable is an empty string, while subsequent processes will have values like '2', '3', etc.

Example configuration in config/database.yml:

test:
  database: yourproject_test<%= ENV['TEST_ENV_NUMBER'] %>

The parallel_test command runs tests in parallel, assigning each process a unique ENV['TEST_ENV_NUMBER'] (e.g., '', '2', '3', ...). You can specify files or folders to run, or use patterns to include/exclude tests.

To pass options directly to the underlying test runner (like RSpec or Cucumber), use the -- separator.

Example:

parallel_test -- -t acceptance -f progress -- spec/foo_spec.rb spec/acceptance_spec.rb

You can execute any command in parallel using the parallel_test -e flag or the parallel:rake Rake task.

To limit the number of processes, append the process count to the Rake task.

# Using the CLI
RAILS_ENV=test parallel_test -e "rake my:custom:task"

# Using Rake
rake "parallel:rake[my:custom:task]"

# Limited parallelism (e.g., 2 processes)
rake "parallel:rake[my:custom:task,2]"

You can customize RSpec output using formatters. These can be added to your .rspec_parallel or .rspec file, or passed via --test-options='--format x'.

• SummaryLogger: Logs test output without processes overwriting each other. --format ParallelTests::RSpec::SummaryLogger --out tmp/spec_summary.log
• FailuresLogger: Produces pasteable command-line snippets for failed examples. --format ParallelTests::RSpec::FailuresLogger --out tmp/failing_specs.log
• VerboseLogger: Prints a single line for starting and finishing each example (PID, process number, status, description). --format ParallelTests::RSpec::VerboseLogger

To log failed Cucumber scenarios to a file, use the ParallelTests::Cucumber::FailuresLogger formatter.

CLI usage:

cucumber --format ParallelTests::Cucumber::FailuresLogger --out tmp/cucumber_failures.log

Cucumber.yml usage: Add to the parallel: profile:

parallel: --format progress --format ParallelTests::Cucumber::FailuresLogger --out tmp/cucumber_failures.log

To rerun failures:

cucumber @tmp/cucumber_failures.log

Use the isolate or isolate_count options to ensure certain tests run in dedicated processes, preventing them from being grouped with other tests. This is useful for tests that are not thread-safe or require exclusive access to resources.

• isolate: When set, at least one process will be dedicated to an isolated test.
• isolate_count: Specifies the exact number of processes to be used for isolated tests. The isolate_count must be less than the total number of processes (-n).
• single_process: An array of patterns (regex) used to identify tests that should run in a single process.

When running RSpec tests in parallel, you can provide additional RSpec options by creating one of the following configuration files in your project root or spec directory. The runner will automatically detect and apply these options using the -O flag:

• .rspec_parallel (in project root)
• spec/parallel_spec.opts
• spec/spec.opts