A note on using parallel RSpec in CircleCI

Using parallel builds with RSpec in CircleCI? Yeah!

Perhaps you need a way to output what was actually run?

A ready-to-paste CLI invocation.

TL;DR: YAML example for RSpec in parallel on CircleCI with explicit --seed and reproducible CLI invocation.

What’s in the steps?

CircleCI steps start out looking a bit like these:

• Run the tests

When CircleCI runs your tests in parallel, it offers a “split up the test suite” system based on earlier tests’ timings. The timings are gleaned from a JUnit XML format.

• Run the tests
  • with a JUnit XML formatter

When the splitting the test suite selection now can be done by the CircleCI tool, pass the selections to RSpec.

• Run the tests
  • with a JUnit XML-based formatter
  • on a subset of the files

When RSpec starts, you have set it to run in random order, to expose sequence-related bugs. Now, we are going to need to see this value, so in order to do that, we pick a number ourselves. Then you set the --seed to a given value, e.g. an integer between one and a million.

• Run the tests
  • with a JUnit XML-based formatter
  • with a given ordering seed
  • on a subset of the files

Now when a test has failed, you, the human reader, needs a pasteable command-line invocation, to reproduce the error in your local computer environment.

• Output a command of what will run
• Run the tests
  • with a JUnit XML-based formatter
  • with a given ordering seed
  • on a subset of the files

Example YAML steps

This example is real-world: creates the necessary directories, stores artifacts.

      - run: mkdir -p test-results/rspec
      - run:
          name: run rspec tests
          command: |
            TEST_FILES="$(circleci tests glob "spec/**/*_spec.rb" | \
              circleci tests split --split-by=timings)"
            SEED_NUMBER="$(shuf -i 1-1000000 -n 1)"
            TEST_FILES_SPACE_SEPARATED="$(echo $TEST_FILES | paste -s -d ' ' -)"
            echo "INCLUDE_SLOW_SPECS=1 bundle exec rspec --seed ${SEED_NUMBER} ${TEST_FILES_SPACE_SEPARATED}"
            bundle exec rspec \
              --seed $SEED_NUMBER \
              --format progress \
              --format RspecJunitFormatter \
              --out test-results/rspec/results.xml \
              --format progress \
              $TEST_FILES
      - store_test_results:
          path: test-results
      - store_artifacts:
          path: test-results
          destination: test-results
      - store_artifacts:
          path: coverage
          destination: coverage