콘텐츠로 이동

생성된 Xcode 프로젝트

생성된 프로젝트의 테스트 샤딩은 빌드 단계와 테스트 단계 모두에서 tuist test를 사용합니다.

작동 방식#

테스트 샤딩은 두 단계 워크플로를 따릅니다:

  1. 빌드 단계: Tuist는 빌드된 .xctestrun 파일에서 테스트 모듈을 읽어 서버에 샤드 계획을 생성합니다. 서버는 지난 30일 간의 히스토리컬 테스트 타이밍 데이터를 사용하여 각 샤드가 대략 동일한 시간이 소요되도록 테스트를 샤드에 분배합니다. 빌드 단계는 CI 시스템이 병렬 러너를 생성하는 데 사용하는 샤드 매트릭스를 출력합니다.
  2. 테스트 단계: 각 지속적 통합(CI) 러너는 샤드 인덱스와 정확한 샤드 계획 식별자를 받은 후, 해당 계획의 테스트 선택을 실행합니다.

--shard-granularity suite가 사용되면, 서버는 현재 .xctestrun의 각 모듈에 대해 브랜치의 최근 CI 실행에서 보고된 스위트들을 사용하며, 브랜치 히스토리가 없는 모듈의 경우 프로젝트의 기본 브랜치를 폴백으로 사용합니다. 여러 실행을 결합하면 샤딩되거나 선택적 실행에서 최신 보고서에 포함되지 않았던 스위트들이 유지됩니다. 서버는 지난 30일 간의 스위트 타이밍을 사용하여 기간을 추정합니다.

Tuist는 요청된 샤드 수에 맞춰 알려진 스위트들을 균형 있게 분배하고 마지막 샤드를 catch-all로 사용합니다. 예를 들어, --shard-total 5는 샤드 인덱스 0부터 4까지를 생성하며, 샤드 인덱스 4가 catch-all 역할을 합니다. 일반 샤드는 할당된 스위트에 대해 -only-testing를 사용하여 실행됩니다. 마지막 샤드는 -only-testing 없이 실행되고 이전 샤드에 할당된 모든 스위트에 대해 -skip-testing를 전달하므로, 새로 추가된 스위트, 이름이 변경된 스위트, 또는 히스토리컬 인벤토리에 누락된 스위트도 실행합니다. .xctestrun 파일이 모듈 목록을 제공하므로 모듈 단위의 세분화에는 catch-all이 필요하지 않습니다.

빌드 단계#

프로젝트를 생성하고, 테스트를 빌드하며, 샤드 계획을 생성하세요:

bash
tuist test --build-only --shard-total 5

--build-only 플래그는 Tuist에게 테스트를 실행하지 않고 빌드하도록 지시합니다. --build-only 없이 샤드 계획 플래그(--shard-min/--shard-max/--shard-total)를 전달하면 Tuist는 오류를 발생시킵니다.

이 명령어는 다음을 수행합니다:

  1. 매니페스트에서 Xcode 프로젝트를 생성합니다
  2. 테스트를 빌드합니다
  3. 히스토리컬 타이밍 데이터를 사용하여 Tuist 서버에 샤드 계획을 생성합니다
  4. .xctestproducts 번들을 업로드하거나 샤드 러너가 사용할 샤드 아카이브를 작성합니다
  5. CI 시스템을 위한 샤드 매트릭스를 출력합니다
  6. 샤드 러너가 프로젝트를 다시 생성할 필요가 없도록 선택적 테스팅 그래프를 지속합니다(해당되는 경우)

빌드 옵션#

플래그 환경 변수 설명
--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 test --without-building

--without-building 플래그는 Tuist에게 다시 빌드하는 대신 이전에 빌드된 산출물을 사용하여 테스트를 실행하도록 지시합니다. --without-building 없이 TUIST_SHARD_INDEX / --shard-index가 설정되면 Tuist는 오류를 발생시킵니다.

테스트 옵션#

플래그 환경 변수 설명
--shard-index <N> TUIST_SHARD_INDEX 실행할 샤드의 0부터 시작하는 인덱스
--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 test --build-only --shard-total 5
test:
name: "Shard #${{ matrix.shard }}"
needs: build
if: toJSON(fromJSON(needs.build.outputs.matrix).shard) != '[]'
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 test --without-building

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 test --build-only --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 test --without-building

CircleCI#

Tuist는 continuation orb용 매개변수가 포함된 .tuist-shard-continuation.json을 생성합니다. shard-plan-id 매개변수는 계속 구성(continued configuration)에서 선언되어야 합니다:

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 test --build-only --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 test --without-building
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 test --build-only --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 test --without-building

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 test --build-only --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 test --without-building
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가 BITRISE_DEPLOY_DIR에 .tuist-shard-matrix.json(shard_plan_id 포함)를 기록하여 하위 파이프라인 단계에서 빌드 아티팩트로 사용할 수 있게 합니다. 각 테스트 워크플로는 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 test --build-only --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 test --without-building
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 test \
--build-only \
--shard-total 5 \
--shard-skip-upload \
-- \
-testProductsPath /path/to/shared/volume/$UNIQUE_ID/MyScheme.xctestproducts
  1. 테스트 단계에서 동일한 -testProductsPath를 전달하여 Tuist가 테스트 산출물을 다운로드하지 않고 로컬에서 읽도록 하세요:
bash
tuist test --without-building -- -testProductsPath /path/to/shared/volume/$UNIQUE_ID/MyScheme.xctestproducts
플래그 환경 변수 설명
--shard-skip-upload TUIST_TEST_SHARD_SKIP_UPLOAD 테스트 산출물 번들을 원격 스토리지에 업로드하지 않음

직접 관리하는 아티팩트#

CI 제공자가 이미 아티팩트 업로드 및 다운로드 단계를 갖추고 있다면, Tuist가 아카이브 생성과 압축 해제를 처리하고 CI가 전송을 담당하도록 할 수 있습니다.

  1. 빌드 단계에서 --shard-archive-path를 전달하여 Tuist가 테스트 산출물을 업로드하는 대신 최적화된 샤드 아카이브를 로컬에 작성하도록 하세요:
bash
tuist test \
--build-only \
--shard-total 5 \
--shard-archive-path /tmp/shards/${UNIQUE_ID}/bundle.aar
  1. 해당 아카이브를 CI의 기본 아티팩트 단계를 사용하여 업로드하세요.

  2. 각 테스트 단계 작업에서 아카이브를 다운로드하고 동일한 경로를 Tuist에 다시 전달하세요:

bash
tuist test \
--without-building \
--shard-archive-path /tmp/shards/${UNIQUE_ID}/bundle.aar

--shard-archive-path가 설정되면 Tuist는 원격 테스트 산출물 전송을 건너뛰고 로컬 아카이브를 사용합니다. --shard-skip-upload도 함께 전달하면 아카이브 경로가 우선 적용됩니다.

선택적 테스팅으로 모든 테스트 대상이 건너뛰어져 실행할 테스트가 없는 경우 등에는 빌드 단계가 빈 샤드 매트릭스를 출력하고 아카이브를 작성하지 않습니다. 매트릭스에 샤드가 있을 때만 업로드 단계를 실행하세요.

Important

동시 실행 간 충돌을 방지하기 위해 워크플로 실행마다 고유한 경로(예: CI 실행 ID 포함)를 사용하세요. 또한 러너에 오래된 데이터가 누적되지 않도록 샤딩 완료 후 샤드 아카이브를 정리해야 합니다.

Namespace#

Namespace 러너는 GitHub Actions 아티팩트와 잘 연동됩니다. 빌드 작업이 샤드 아카이브를 로컬에 작성하도록 TUIST_TEST_SHARD_ARCHIVE_PATH를 한 번 설정하고, 이를 업로드한 뒤 각 샤드 작업에서 tuist 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 test --build-only --shard-total 5
- if: toJSON(fromJSON(steps.build.outputs.matrix).shard) != '[]'
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
if: toJSON(fromJSON(needs.build.outputs.matrix).shard) != '[]'
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 test --without-building
- if: always()
run: rm -rf /tmp/shards/${{ github.run_id }}