Documentation structure for LLMs (llms.txt)
CircleCI Logo

Use static test splitting

1 minute ago
Cloud

Static test splitting reduces overall job time by dividing your tests across parallel execution nodes. It is built in to circleci testsuite run and is free, with no extra configuration in test-suites.yml.

How it works

When parallelism is set on your job, circleci testsuite run splits your tests across the parallel nodes up front, using the durations reported in your JUnit results from previous runs.

Because the split is assigned before the tests run, it cannot account for fixed costs such as runner startup and per-node setup. Nodes can still finish at noticeably different times. To keep nodes evenly loaded as they run, use Dynamic Test Splitting, which has a credit charge above your plan’s allowance.

Prerequisites

Before using static test splitting, ensure you have completed the Getting Started With Smarter Testing guide and have:

  • Configured your .circleci/test-suites.yml with discover and run commands.

  • Verified your tests run successfully with the testsuite command.

  • Added a store_test_results step to your job, so CircleCI has the JUnit timing data it uses to split your tests. See Upload Test Results.

1. Set parallelism on your job

Set parallelism to a value greater than 1 on the job that runs circleci testsuite run. See the Configuration Reference for more information.

jobs:
  build-and-test:
    parallelism: 4
    # ...
    steps:
      - checkout
      - run:
          name: Run tests
          command: circleci testsuite run "ci tests"
      - store_test_results:
          # Must match outputs.junit in test-suites.yml
          path: test-reports

2. Verify the split

Commit your configuration to your feature branch and push to your VCS. Then verify that your tests are split across nodes by looking at the Timing tab in the UI:

  1. Navigate to your pipeline in the CircleCI web app and open the test job.

  2. Open the Timing tab.

  3. Confirm that each parallel node ran a share of your tests.

The first run on a branch might split less evenly, because timing data from earlier runs is not yet available.

Next steps