跳至内容

Xcode 测试分片

要求
  • 已配置Xcode 测试洞察。分片功能会使用过去 30 天的测试洞察计时数据来平衡各个分片;如果没有洞察数据,每个分片都会像测试套件未知那样运行。

针对 Xcode 项目的测试分片使用 tuist xcodebuild build-for-testing 创建分片计划,并使用 tuist xcodebuild test 执行每个分片。

工作原理#

测试分片遵循两阶段工作流:

  1. 构建阶段: Tuist 从已构建的 .xctestrun 文件中读取测试模块,并在服务器上创建分片计划。服务器利用过去 30 天的历史测试计时数据将测试分配到各个分片,使每个分片的耗时大致相同。构建阶段会输出一个分片矩阵,你的 CI 系统用它来生成并行运行器。
  2. 测试阶段: 每个持续集成运行器会收到一个分片索引和确切的分片计划标识符,然后执行该计划的测试选择。

在套件粒度下,服务器会使用当前 .xctestrun 中各模块在你的分支上最近 CI 运行所报告的套件;对于没有分支历史的模块,则回退到项目的默认分支。合并多次运行可以保留那些被分片运行或选择性运行排除在最新报告之外的套件。

当使用 --shard-granularity suite 时,Tuist 会在请求的分片数量之间平衡已知套件,并将最后一个分片作为兜底分片。例如,--shard-total 5 会生成分片索引 0 到 4,其中分片索引 4 作为兜底分片。常规分片会为其分配的套件使用 -only-testing 运行。最后一个分片在不使用 -only-testing 的情况下运行,并为分配给前面分片的每个套件传入 -skip-testing,因此它会运行其计划内的套件,以及新增的套件或历史清单中缺失的套件。模块粒度不需要兜底分片,因为 .xctestrun 文件提供了模块列表。

构建阶段#

构建你的测试并创建分片计划:

bash
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5

此命令会:

  1. 使用 xcodebuild build-for-testing 构建你的测试
  2. 使用历史计时数据在 Tuist 服务器上创建分片计划
  3. 上传 .xctestproducts 包或写入供分片运行器使用的分片归档
  4. 为你的 CI 系统输出分片矩阵

构建选项#

标志 环境变量 描述
--shard-max <N> TUIST_TEST_SHARD_MAX 最大分片数。与 --shard-max-duration 配合使用以限制分片数量
--shard-min <N> TUIST_TEST_SHARD_MIN 最小分片数
--shard-total <N> TUIST_TEST_SHARD_TOTAL 确切的分片数(与 --shard-min/--shard-max 互斥)。在套件粒度下,最后一个分片为兜底分片
--shard-max-duration <MS> TUIST_TEST_SHARD_MAX_DURATION 每个分片的目标最大持续时间(毫秒)
--shard-granularity <LEVEL> TUIST_TEST_SHARD_GRANULARITY module(默认)将整个测试模块分布到各个分片;suite 将单个测试类分布到各个分片,以实现更细粒度的平衡
--shard-reference <REF> TUIST_SHARD_REFERENCE 分片计划的唯一标识符(在支持的 CI 提供商上自动派生)
--shard-archive-path <PATH> TUIST_TEST_SHARD_ARCHIVE_PATH Tuist 写入优化后的分片归档的路径,而非将测试产物上传到远程存储

测试阶段#

每个分片运行器执行其分配的测试:

bash
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'

测试选项#

标志 环境变量 描述
--shard-index <N> TUIST_SHARD_INDEX 要执行的分片的从零开始索引
--shard-plan-id <IDENTIFIER> TUIST_SHARD_PLAN_ID 构建阶段生成的确切分片计划标识符。生成的提供程序输出会自动包含此值
--shard-reference <REF> TUIST_SHARD_REFERENCE 分片计划的唯一标识符(在支持的 CI 提供程序上自动派生)
--shard-archive-path <PATH> TUIST_TEST_SHARD_ARCHIVE_PATH 本地管理的分片归档路径;Tuist 会提取该归档,而不是从远程存储下载测试产品

Tuist 下载 .xctestproducts 包并对其进行过滤,仅包含分配给该分片的测试。

持续集成#

Tuist 会自动检测以下 CI 提供商:

对于其他提供商,请参考 .tuist-shard-matrix.json 文件来设置并行任务。

GitHub Actions#

使用矩阵策略并行运行分片:

yaml
name: Tests
on: [pull_request]
jobs:
build:
name: Build test shards
runs-on: macos-latest
outputs:
matrix: ${{ steps.build.outputs.matrix }}
steps:
- uses: actions/checkout@v4
- uses: jdx/mise-action@v2
- run: tuist auth login
- id: build
run: |
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5
test:
name: "Shard #${{ matrix.shard }}"
needs: build
runs-on: macos-latest
strategy:
fail-fast: false
matrix: ${{ fromJson(needs.build.outputs.matrix) }}
env:
TUIST_SHARD_INDEX: ${{ matrix.shard }}
TUIST_SHARD_PLAN_ID: ${{ matrix.shard_plan_id }}
steps:
- uses: actions/checkout@v4
- uses: jdx/mise-action@v2
- run: tuist auth login
- run: |
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'

GitLab CI#

Tuist 会生成一个 .tuist-shard-child-pipeline.yml,你可以将其作为子流水线触发。定义一个 .tuist-shard 模板作业,由生成的分片作业继承:

yaml
# .gitlab-ci.yml
stages:
- build
- test
build-shards:
stage: build
tags: [macos]
script:
- tuist auth login
- |
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5
artifacts:
paths:
- .tuist-shard-child-pipeline.yml
test-shards:
stage: test
needs: [build-shards]
trigger:
include:
- artifact: .tuist-shard-child-pipeline.yml
job: build-shards
strategy: depend
yaml
# .gitlab/shard-template.yml
.tuist-shard:
tags: [macos]
script:
- tuist auth login
- |
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'

CircleCI#

Tuist 会生成一个包含 continuation orb 所需参数的 .tuist-shard-continuation.json。shard-plan-id 参数必须在你的延续配置中声明:

yaml
# .circleci/config.yml
version: 2.1
setup: true
orbs:
continuation: circleci/continuation@1
jobs:
build-shards:
macos:
xcode: "16.0"
steps:
- checkout
- run:
name: Build and plan shards
command: |
tuist auth login
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5
- continuation/continue:
configuration_path: .circleci/continue-config.yml
parameters: .tuist-shard-continuation.json
workflows:
setup:
jobs:
- build-shards
yaml
# .circleci/continue-config.yml
version: 2.1
parameters:
shard-indices:
type: string
default: ""
shard-count:
type: integer
default: 0
shard-plan-id:
type: string
default: ""
jobs:
test-shard:
macos:
xcode: "16.0"
parameters:
shard-index:
type: integer
steps:
- checkout
- run:
name: Run shard
command: |
export TUIST_SHARD_INDEX=<< parameters.shard-index >>
export TUIST_SHARD_PLAN_ID=<< pipeline.parameters.shard-plan-id >>
tuist auth login
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'
workflows:
test:
jobs:
- test-shard:
matrix:
parameters:
shard-index: [<< pipeline.parameters.shard-indices >>]

Buildkite#

Tuist 会生成一个 .tuist-shard-pipeline.yml,其中每个分片对应一个步骤。使用 buildkite-agent pipeline upload 上传它:

yaml
# pipeline.yml
steps:
- label: "Build test shards"
command: |
tuist auth login
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5
buildkite-agent pipeline upload .tuist-shard-pipeline.yml
agents:
queue: macos

每个生成的步骤都在其环境中设置了 TUIST_SHARD_INDEX 和 TUIST_SHARD_PLAN_ID。使用共享脚本将测试命令添加到每个分片步骤:

bash
# .buildkite/shard-step.sh
#!/bin/bash
tuist auth login
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'

Codemagic#

Codemagic 不支持动态矩阵作业,因此需要为每个分片定义单独的工作流。Tuist 会将 TUIST_SHARD_MATRIX 和 TUIST_SHARD_COUNT 写入 CM_ENV 文件,以便在构建工作流中使用。Codemagic 的 CM_ENV 是工作流作用域的,因此确切的分片计划标识符不会跨越工作流边界;测试工作流会回退到基于引用的分片查找:

yaml
# codemagic.yaml
workflows:
build-shards:
name: Build test shards
instance_type: mac_mini_m2
environment:
xcode: latest
scripts:
- name: Build and plan shards
script: |
tuist auth login
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5
test-shard-0: &shard-workflow
name: "Shard #0"
instance_type: mac_mini_m2
environment:
xcode: latest
vars:
TUIST_SHARD_INDEX: 0
scripts:
- name: Run shard
script: |
tuist auth login
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'
test-shard-1:
<<: *shard-workflow
name: "Shard #1"
environment:
xcode: latest
vars:
TUIST_SHARD_INDEX: 1
test-shard-2:
<<: *shard-workflow
name: "Shard #2"
environment:
xcode: latest
vars:
TUIST_SHARD_INDEX: 2
test-shard-3:
<<: *shard-workflow
name: "Shard #3"
environment:
xcode: latest
vars:
TUIST_SHARD_INDEX: 3
test-shard-4:
<<: *shard-workflow
name: "Shard #4"
environment:
xcode: latest
vars:
TUIST_SHARD_INDEX: 4

Bitrise#

在 Bitrise 上,Tuist 会将 .tuist-shard-matrix.json(包括 shard_plan_id)写入 BITRISE_DEPLOY_DIR,使其可作为下游流水线阶段的构建构件。每个测试工作流使用 envman 从下载的构件中提取计划 ID,以便将其传递到测试命令的环境中:

yaml
# bitrise.yml
pipelines:
test-pipeline:
stages:
- build-stage: {}
- test-stage: {}
stages:
build-stage:
workflows:
- build-shards: {}
test-stage:
workflows:
- test-shard-0: {}
- test-shard-1: {}
- test-shard-2: {}
- test-shard-3: {}
- test-shard-4: {}
workflows:
build-shards:
steps:
- script:
title: Build and plan shards
inputs:
- content: |
tuist auth login
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5
- deploy-to-bitrise-io: {}
test-shard-0: &shard-workflow
envs:
- TUIST_SHARD_INDEX: 0
steps:
- pull-intermediate-files: {}
- script:
title: Set shard plan ID from artifact
inputs:
- content: |
PLAN_ID=$(jq -r '.shard_plan_id' "$BITRISE_DEPLOY_DIR/.tuist-shard-matrix.json")
envman add --key TUIST_SHARD_PLAN_ID --value "$PLAN_ID"
- script:
title: Run shard
inputs:
- content: |
tuist auth login
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'
test-shard-1:
<<: *shard-workflow
envs:
- TUIST_SHARD_INDEX: 1
test-shard-2:
<<: *shard-workflow
envs:
- TUIST_SHARD_INDEX: 2
test-shard-3:
<<: *shard-workflow
envs:
- TUIST_SHARD_INDEX: 3
test-shard-4:
<<: *shard-workflow
envs:
- TUIST_SHARD_INDEX: 4
Tip

Bitrise 不支持在运行时动态创建并行作业。请在你的流水线阶段中定义固定数量的分片工作流——同一阶段内的工作流会自动并行运行。

共享卷#

默认情况下,构建阶段会将 .xctestproducts 包上传到远程存储,每个分片运行器再下载它。如果你的 CI 提供商支持共享卷(跨作业挂载的持久化存储),你可以通过共享文件系统传递测试产物,从而完全跳过此上传/下载过程。

这可以显著减少分片启动时间,尤其是对于大型测试包。

要使用共享卷:

  1. 在构建阶段中,传入指向共享卷的 -testProductsPath,并添加 --shard-skip-upload 以跳过远程上传:
bash
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5 \
--shard-skip-upload \
-testProductsPath /path/to/shared/volume/$UNIQUE_ID/MyScheme.xctestproducts
  1. 在测试阶段中,传入相同的 -testProductsPath,以便 Tuist 本地读取测试产物而不是下载它们:
bash
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
-testProductsPath /path/to/shared/volume/$UNIQUE_ID/MyScheme.xctestproducts
Important

为每次工作流运行使用唯一路径(例如包含 CI 运行 ID),以避免并发运行之间的冲突。你还应在分片完成后清理测试产物,以免在卷上累积过时数据。

标志 环境变量 描述
--shard-skip-upload TUIST_TEST_SHARD_SKIP_UPLOAD 跳过将测试产物包上传到远程存储

自管理构件#

如果你的 CI 提供商已具备构件上传和下载步骤,你可以让 Tuist 处理归档和解压,而由你的 CI 负责传输。

  1. 在构建阶段中,传入 --shard-archive-path,以便 Tuist 将优化后的分片归档写入本地,而不是上传测试产物:
bash
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5 \
--shard-archive-path /tmp/shards/${UNIQUE_ID}/bundle.aar
  1. 使用你的 CI 的原生构件步骤上传该归档。

  2. 在每个测试阶段作业中,下载归档并将相同的路径传回给 Tuist:

bash
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-archive-path /tmp/shards/${UNIQUE_ID}/bundle.aar

设置 --shard-archive-path 后,Tuist 会跳过远程测试产物传输,转而使用本地归档。如果你还传入 --shard-skip-upload,则归档路径优先。

Namespace#

Namespace 运行器与 GitHub Actions 构件配合良好。只需设置一次 TUIST_TEST_SHARD_ARCHIVE_PATH,让构建作业将分片归档写入本地,上传它,并在每个分片作业中下载它,然后再运行 tuist xcodebuild test:

yaml
name: Tests
on: [pull_request]
env:
TUIST_TEST_SHARD_ARCHIVE_PATH: /tmp/shards/${{ github.run_id }}/bundle.aar
jobs:
build:
name: Build test shards
runs-on: namespace-profile-default-macos
outputs:
matrix: ${{ steps.build.outputs.matrix }}
steps:
- uses: actions/checkout@v4
- uses: jdx/mise-action@v2
- run: tuist auth login
- id: build
run: |
tuist xcodebuild build-for-testing \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16' \
--shard-total 5
- uses: actions/upload-artifact@v4
with:
name: test-shard-archive
path: ${{ env.TUIST_TEST_SHARD_ARCHIVE_PATH }}
- if: always()
run: rm -rf /tmp/shards/${{ github.run_id }}
test:
name: "Shard #${{ matrix.shard }}"
needs: build
runs-on: namespace-profile-default-macos
strategy:
fail-fast: false
matrix: ${{ fromJson(needs.build.outputs.matrix) }}
env:
TUIST_SHARD_INDEX: ${{ matrix.shard }}
TUIST_SHARD_PLAN_ID: ${{ matrix.shard_plan_id }}
steps:
- uses: actions/checkout@v4
- uses: jdx/mise-action@v2
- run: tuist auth login
- uses: actions/download-artifact@v4
with:
name: test-shard-archive
path: /tmp/shards/${{ github.run_id }}
- run: |
tuist xcodebuild test \
-scheme MyScheme \
-destination 'platform=iOS Simulator,name=iPhone 16'
- if: always()
run: rm -rf /tmp/shards/${{ github.run_id }}