Running Tests in Parallel

Overview

One of the most powerful features of CircleCI is the ability to run your tests in parallel. This section describes how to use circleci commands in your config.yml file to merge and split tests with the hosted CircleCI CLI for faster builds. See Writing Jobs with Steps for information about setting the parallelism key in your configuration file.

Use the circle tests glob command to specify multiple globs to merge using a pattern, for example:
circleci tests glob "tests/unit/*.java" "tests/functional/*.java"

[abc]: matches any character (excluding path separators) against characters in braces

{foo,bar,...}: matches a sequence of characters if any of the alternatives in braces matches

For example:

circleci tests glob "**/*.java"

Splitting Patterns

The circleci CLI can be used to split a list of test files or classnames when running parallel builds on 2.0. The CLI uses the environment to look up the total number of containers, along with the current container index. Then, it uses deterministic splitting algorithms to return a distinct subset of the input filenames or classnames on each container.

The list of items to split can be provided via standard input or as a file argument, as follows:

--index: set the container index for this invocation of circleci tests split

--total: set the total number of containers to consider

When running on CircleCI, these values will be automatically picked up from environment variables.

Balancing Libraries

The following libraries have built-in support for the CircleCI environment variables:

3rd Party Library or Application Notice: Knapsack
Knapsack is not developed or supported by CircleCI. Please check with the owner if you have issues using it with CircleCI. If you're unable to resolve the issue you can search and ask on our forum, Discuss.

Knapsack Pro - Dynamic optimal test suite split. Knapsack Pro is a more advanced version of knapsack gem. It has automated recording of tests time execution across branches, commits and it can distribute tests across parallel CI nodes with predetermine split (regular mode) or in a dynamic way (queue mode) to get most optimal test suite split.

# some tests that are not balanced and executed only on first CI node
- run: case $CIRCLE_NODE_INDEX in 0) npm test ;; esac
# auto-balancing CI build time execution to be flat and optimal (as fast as possible).
# Queue Mode does dynamic tests allocation so the previous not balanced run command won't
# create a bottleneck on the CI node
- run: bundle exec rake knapsack_pro:queue:rspec

Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.