How to Run Parallel Tests in CircleCI

CircleCI shards a job across containers with parallelism, and circleci tests split balances files by historical timing.

Set parallelism: N to run N copies of a job, then use the circleci tests split CLI to give each container a balanced slice of test files.

Split tests by timing

Each of the 4 containers gets a balanced subset based on stored timing data.

jobs:
  test:
    docker:
      - image: cimg/node:20.11
    parallelism: 4
    steps:
      - checkout
      - run: npm ci
      - run:
          command: |
            TESTS=$(circleci tests glob "test/**/*.test.js" | circleci tests split --split-by=timings)
            npm test -- $TESTS
      - store_test_results:
          path: ./test-results

Gotchas

• --split-by=timings needs prior store_test_results data; the first run falls back to splitting by name.
• Each parallel container is billed separately - balance speed against credit cost.
• For version matrices (vs. test splitting) use a workflow matrix over a parameterized job instead.

Related guides