Parallel RSpec setup¶

Run RSpec in parallel with the parallel_tests gem. Each process uses its own test database.

Workers: 6 by default (lib/tasks/rspec_parallel.rake), configurable with PARALLEL_TEST_PROCESSORS or a task argument
Databases: Named with suffix pattern: {base_name}_test, {base_name}_test1, {base_name}_test2, etc.

Prerequisites¶

MySQL/Percona server running (via Docker Compose or locally)
Database credentials in environment variables (see .env.development.local.example; run commands through direnv exec . when .envrc exists)
Application must be fully set up with migrations and assets compiled

Configuration¶

Database configuration¶

The test environment in config/database.yml supports 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¶

.rspec_parallel records test runtimes to distribute tests evenly across workers:

tmp/spec_parallel_runtime.log

.rspec_parallel writes this file after each run, and parallel_tests uses it to balance the load. On the first run, tests are distributed by file size.

Running parallel tests¶

Run all unit tests (recommended)¶

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
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           # 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¶

Run the normal migration or Easy8 installation workflow first so that db/schema.rb contains the current schema. Then load that schema into all parallel test databases:

bundle exec rake parallel:prepare

parallel_tests 5.7 does not run db:schema:dump during parallel:prepare. The command purges and loads each parallel test database from the existing db/schema.rb, so the schema file must already be current.

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, create the parallel test databases with bundle exec rake parallel:create, then run bundle exec rake parallel:prepare.

Uneven test distribution¶

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

rm tmp/spec_parallel_runtime.log