Skip to content

Parallel RSpec Setup

This guide explains how to run RSpec tests in parallel to speed up test execution.

Overview

The parallel_tests gem has been configured to run RSpec tests across multiple processes, with each process using its own test database.

  • Workers: 6 by default (configurable via PARALLEL_TEST_PROCESSORS or task argument)
  • Databases: Named with suffix pattern: {base_name}_test, {base_name}_test1, {base_name}_test2, etc.

Prerequisites

  1. MySQL/Percona server running (via Docker Compose or locally)
  2. Proper database credentials configured in environment variables
  3. Application must be fully set up with migrations and assets compiled

Configuration

Database Configuration

The config/database.yml test environment is configured to support parallel databases:

test:
  <<: *development
  database: <%= ENV["TEST_MYSQL_DATABASE_PREFIX"] || ENV["DB_NAME"] || ENV["MYSQL_DATABASE"].gsub(/_test$/, '') %>_test<%= ENV["TEST_ENV_NUMBER"] %>

This appends TEST_ENV_NUMBER to the database name:

  • Worker 0: Uses {base_name}_test (TEST_ENV_NUMBER is empty)
  • Worker 1: Uses {base_name}_test1 (TEST_ENV_NUMBER=1)
  • Worker 2: Uses {base_name}_test2 (TEST_ENV_NUMBER=2)
  • Worker 3: Uses {base_name}_test3 (TEST_ENV_NUMBER=3)

Runtime Log

The gem tracks test runtimes to distribute tests evenly across workers:

tmp/parallel_runtime_rspec.log

This file is automatically updated after each run and helps balance the load.

On the first run, tests are distributed by file size. After the first run, the runtime log optimizes distribution.

Running Parallel Tests

Use the rake task to run all unit tests (excluding feature specs) in parallel:

bundle exec rake rspec:parallel:unit

With custom worker count:

bundle exec rake "rspec:parallel:unit[6]"

This command:

  • Runs all specs across the entire project (core, plugins, engines)
  • Excludes feature specs by default (--tag ~type:feature)
  • Uses 6 workers by default (configurable via PARALLEL_TEST_PROCESSORS env var)
  • Automatically discovers all *_spec.rb files in spec/, plugins/, and easy_engines/

Alternative: You can also use the shell script wrapper:

./bin/parallel_rspec_all_unit           # Uses rake task with default 6 workers
./bin/parallel_rspec_all_unit -n 6      # Custom worker count

Run Specific Directory or File

For running a specific directory or file, use ./bin/parallel_rspec directly:

./bin/parallel_rspec easy_engines/easy_extensions/spec/models
./bin/parallel_rspec -n 6 plugins/easy_gantt/spec
./bin/parallel_rspec spec/services/my_service_spec.rb

Run with Custom Options

Pass RSpec options using the -o flag:

./bin/parallel_rspec -o '--tag ~type:feature' easy_engines/easy_extensions/spec

Maintenance

Update All Test Databases After Migration

Critical: After running any database migration, you must update all parallel test databases:

bundle exec rake parallel:prepare

This is equivalent to running db:schema:load on each test database and must be done to keep schemas in sync.

Reset All Test Databases

If you need to completely reset all test databases:

bundle exec rake parallel:drop
bundle exec rake parallel:create
bundle exec rake parallel:prepare

Troubleshooting

Database Not Found

If tests fail with database not found errors, ensure all parallel test databases are created (see Setup step 1).

Uneven Test Distribution

If tests become unbalanced after many changes, delete the runtime log to reset distribution:

rm tmp/parallel_runtime_rspec.log