Docs Navigation

Boosters for RSpec

Boosters for RSpec enable you to run specs across many parallel jobs. They come out of the box when they are used on Semaphore. Once Boosters are set up, they are ready to take action in optimizing build times.

  1. Supported versions
  2. How Boosters run your RSpec suite
  3. Pass additional flags to RSpec
  4. Customize RSpec configuration used by Boosters

# Supported versions

Boosters officially support following RSpec versions:

3.0 3.1 3.2 3.3 3.4 3.5 3.6

If you encounter an issue when using Boosters with RSpec version other than officially supported, we encourage you to contact our support team.

# How Boosters run your RSpec suite

Test Boosters gem runs your RSpec tests using rspec_booster command:

rspec_booster --job <job>/<job_count>

The command uses split configuration file in order to find the configuration of a job to be run. This file contains distribution of your test files across many jobs. Split configurations for your jobs are located in ~/rspec_split_cofiguration.json file. Semaphore provides this file to each of the Boosted jobs.

More in detail information about split configurations can be found.

Let's assume to have the following split configuration within ~/rspec_split_configuration.json:

  { "files": ["spec/spec_1.rb", "spec/spec_2.rb"] },
  { "files": ["spec/spec_3.rb", "spec/spec_4.rb"] },
  { "files": ["spec/spec_5.rb", "spec/spec_6.rb"] }

And specs are run using the rspec_booster command:

rspec_booster --job 1/3

Previous command results with following RSpec command under the hood:

bundle exec rspec --format documentation \
                  --format json \
                  --out /home/<user>/rspec_report.json \
                  spec/spec_1.rb spec/spec_2.rb

As previously shown, Booster for RSpec builds and runs RSpec command which output is formatted as json and redirected to ~/rspec_report.json file.

The report file created contains durations of your test files. It is used to estimate duration for each job in the next build.

# Pass additional flags to RSpec

If you want to invoke RSpec runner with additional flags you can do it by specifying them within TB_RSPEC_OPTIONS environment variable:

TB_RSPEC_OPTIONS='--fail-fast=3' rspec_booster --job 4/32

This results in following RSpec command under the hood:

bundle exec rspec --fail-fast=3 \
                  --format documentation \
                  --format json \
                  --out /home/<user>/rspec_report.json \

# Customize RSpec configuration used by Boosters

You are able to customize your RSpec configuration in any way you need. Though some of the RSpec options do not work properly when used with Boosters.

RSpec filter_run_when_matching configuration option can cause unexpected behaviour when it's used with Boosters. This option can lead to unbalanced builds, since your specs are distributed across available parallel jobs.

Using rspec-retry to rerun flaky tests can lead to unbalanced builds. Retried tests have big standard deviation, and as such they have unpredictable execution duration. Boosters are having trouble to estimate in which job they should be run in the next build. Read more about Flaky Tests.

If you notice any unexpected behaviour in your test suite with Boosters, we encourage you to contact our support team. There are lot of the RSpec use cases and unfortunately we won't be able to support all of them. Though if you think you've found a bug in Test Boosters gem, don't hesitate to create an issue on GitHub.

Semaphore Docs are open source — Edit on GitHub


Occasional lightweight product and blog updates. Unsubscribe at any time.

2009-%= %> © Rendered Text. All rights reserved. Terms of Service, Privacy policy, Security.