Xcode test sharding

Test sharding for Xcode projects uses tuist xcodebuild build-for-testing to create a shard plan and tuist xcodebuild test to execute each shard.

How it works#

Test sharding follows a two-phase workflow:

1. Build phase: Tuist enumerates your tests and creates a shard plan on the server. The server uses historical test timing data from the last 30 days to distribute tests across shards so each shard takes roughly the same amount of time. The build phase outputs a shard matrix that your CI system uses to spawn parallel runners.
2. Test phase: Each CI runner receives a shard index and executes only the tests assigned to that shard.

Build phase#

Build your tests and create a shard plan:

This command:

1. Builds your tests with xcodebuild build-for-testing
2. Creates a shard plan on the Tuist server using historical timing data
3. Uploads the .xctestproducts bundle or writes a shard archive for use by shard runners
4. Outputs a shard matrix for your CI system

Build options#

Test phase#

Each shard runner executes its assigned tests:

Test options#

Tuist downloads the .xctestproducts bundle and filters it to include only the tests assigned to that shard.

Continuous integration#

Tuist automatically detects the following CI providers:

• GitHub Actions
• GitLab CI
• CircleCI
• Buildkite
• Codemagic
• Bitrise

For other providers, refer to the .tuist-shard-matrix.json file to set up parallel jobs.

GitHub Actions#

Use a matrix strategy to run shards in parallel:

GitLab CI#

Tuist generates a .tuist-shard-child-pipeline.yml that you trigger as a child pipeline. Define a .tuist-shard template job that the generated shard jobs extend:

CircleCI#

Tuist generates a .tuist-shard-continuation.json with parameters for the continuation orb:

Buildkite#

Tuist generates a .tuist-shard-pipeline.yml with one step per shard. Upload it with buildkite-agent pipeline upload:

Each generated step has TUIST_SHARD_INDEX set in its environment. Add the test command to each shard step using a shared script:

Codemagic#

Codemagic does not support dynamic matrix jobs, so define a separate workflow per shard. Tuist writes TUIST_SHARD_MATRIX and TUIST_SHARD_COUNT to the CM_ENV file for use within each workflow:

Bitrise#

On Bitrise, Tuist writes .tuist-shard-matrix.json to the BITRISE_DEPLOY_DIR, making it available as a build artifact for downstream pipeline stages. Use Bitrise Pipelines with pre-defined parallel workflows:

Shared volumes#

By default, the build phase uploads the .xctestproducts bundle to remote storage, and each shard runner downloads it. If your CI provider supports shared volumes (persistent storage mounted across jobs), you can skip this upload/download entirely by passing the test products through a shared filesystem.

This can significantly reduce shard startup time, especially for large test bundles.

To use shared volumes:

1. In the build phase, pass -testProductsPath pointing to a shared volume and add --shard-skip-upload to skip the remote upload:

2. In the test phase, pass the same -testProductsPath so Tuist reads the test products locally instead of downloading them:

Self-managed artifacts#

If your CI provider already has artifact upload and download steps, you can let Tuist handle archive and extraction while your CI handles transport.

1. In the build phase, pass --shard-archive-path so Tuist writes its optimized shard archive locally instead of uploading test products:

2. Upload that archive using your CI's native artifact step.

3. In each test phase job, download the archive and pass the same path back to Tuist:

When --shard-archive-path is set, Tuist skips remote test-products transfer and uses the local archive instead. If you also pass --shard-skip-upload, the archive path takes precedence.

Namespace#

Namespace runners work well with GitHub Actions artifacts. Set TUIST_TEST_SHARD_ARCHIVE_PATH once so the build job writes the shard archive locally, upload it, and download it in each shard job before running tuist xcodebuild test: