Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

iOS용 Developer Device Platform 기기 실행

이 가이드에서는 gcloud alpha device-run CLI를 사용하여 iOS XCTest를 실행하고 Google Cloud console에서 결과를 찾는 방법을 설명합니다. Google Cloud 계정 및 프로젝트가 있다고 가정합니다.

Firebase Test Lab에서 Developer Device Platform으로 이전하는 경우 이전 가이드, 명령어 및 플래그 번역, AI 에이전트의 이전 기술을 참고하세요.

device-run CLI를 사용하려면 Google Cloud 프로젝트 ID를 제공해야 합니다. 명령어 요약은 gcloud alpha device-run을 참고하세요.

시작하기 전에

이 단계에서는 다음을 이미 완료했다고 가정합니다.

프로젝트를 Google Cloud 만들었습니다.
빠른 시작에 따라 Developer Device Platform을 설정했습니다.
터미널에서 gcloud로 인증했습니다.
일반 정보는 기기 실행 개요를 검토했습니다.
테스트를 컴파일하고 ZIP으로 패키징했습니다.

1단계: 테스트 실행 구성

다음 선택적 플래그를 사용하여 테스트 실행을 맞춤설정할 수 있습니다(단, --device 플래그의 인스턴스가 하나 이상 필요함).

여러 기기: --device 플래그를 여러 번 지정하여 여러 기기에서 동시에 동일한 테스트를 실행합니다. --device iphonese3-18-4 --device iphonese3-26-3 또는 --device iphonese3-18-4,iphonese3-26-3
추가 앱: --additional-apps를 사용하여 테스트를 실행하기 전에 하나 이상의 추가 .ipa 패키지를 설치합니다. --additional-apps=/path/to/AdditionalApp.ipa
맞춤 .xctestrun 파일: --xctestrun-file을 사용하여 맞춤 구성 파일을 전달합니다. --xctestrun-file=/path/to/CustomTests.xctestrun
Apple Xcode 버전: CLI 지원 Xcode 버전에 --xcode-version 플래그를 사용하여 직접 액세스합니다(예: --xcode-version=xcode-16-4).
테스트 제한시간: 실행 시간을 제한합니다. --xctest-timeout=10m (유효 범위는 1m~1h이며 기본값은 5m임)
라벨: 사용자 정의 메타데이터를 세션에 연결합니다. --labels=env=staging,owner=my-team
Locale(언어): 기기 Locale(언어)을 설정합니다. --locale=en-US
기기에 파일 푸시: 테스트 실행 전에 파일을 앱 데이터 컨테이너에 푸시합니다. 실행: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
기기에서 파일 가져오기: 테스트 실행 후 앱 데이터 컨테이너에서 파일을 가져옵니다. --paths-to-pull=com.example.app:/Documents/output.txt
불안정한 테스트 재시도: 불안정한 테스트를 다시 실행할 최대 시도 횟수를 설정합니다. --flaky-test-attempts=3 (기본값은 1회 시도임)
맞춤 Cloud Storage 버킷: 입력 및 출력을 위한 맞춤 Cloud Storage 버킷을 지정합니다. --bucket-name=my-custom-bucket (기본값은 PROJECT_ID-devicerun임)
용량이 큰 ZIP 또는 IPA 파일을 업로드하는 데 시간이 오래 걸릴 수 있으므로 Cloud Storage gs:// 경로를 사용하여 파일을 직접 참조하여 업로드 시간을 절약할 수 있습니다.

동기 및 비동기 실행

기본적으로 제출 명령어는 차단 (동기) 됩니다. 테스트가 완료될 때까지 기다린 후 결과 요약 표를 출력합니다.

세션을 제출하고 Cloud Storage에 파일을 업로드한 후 즉시 반환하려면 --async 플래그를 추가하세요.

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --async

이렇게 하면 세션 ID가 즉시 반환됩니다. 그런 다음 sessions wait 명령어를 사용하여 기다릴 수 있습니다.

gcloud alpha device-run sessions wait SESSION_ID

작업이 완료될 때까지 명령어는 차단됩니다.

다수의 기기

여러 기기에서 동일한 테스트를 실행하려면 쉼표로 구분된 여러 기기 ID 또는 각각 고유한 기기 ID를 지정하는 여러 --device 플래그와 함께 --device 플래그를 제공합니다.

쉼표로 구분됨

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4,iphonese3-26-3 \
  --test ./IOS_TESTS.zip

여러 플래그

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --device iphonese3-26-3 \
  --test ./IOS_TESTS.zip

테스트 제한시간

테스트 실행 시간을 제한합니다.

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xctest-timeout=10m

유효한 범위는 1m~1h이며 기본값은 5m입니다.

소프트웨어 버전

테스트 실행을 구성하기 전에 사용 가능한 소프트웨어 패키지 및 Apple Xcode 버전을 검색하고 사용하며 수명 주기, 지원되는 버전, 메타데이터를 검사합니다.

먼저 사용 가능한 모든 소프트웨어 패키지와 버전을 나열합니다.

gcloud alpha device-run software-versions list

다음과 유사하게 출력됩니다.

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

그런 다음 목록에서 정확한 리소스 ID를 사용하여 특정 패키지를 설명합니다.

gcloud alpha device-run software-versions describe xcode-16-4

다음과 유사하게 출력됩니다.

id: xcode-16-4
lifecycle:
  state: ACTIVE
name: Xcode 16.4
softwareType: XCODE
supportedIosVersions:

-   '15.0'
-   '15.1'
-   '15.2'
-   '15.4'
-   '15.7'
-   '16.0'
-   '16.1'
-   '16.2'
-   '16.3'
-   '16.5'
-   '16.6'
-   '18.0'
-   '18.3'
-   '18.4'
version: '16.4'

이제 사용 가능한 소프트웨어 버전을 알았으므로 다음과 같이 --xcode-version 플래그를 사용하여 테스트 실행에서 사용할 수 있습니다.

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xcode-version=16.4

2단계: 기기 유형 선택

device-run CLI를 사용하면 사용 가능한 실제 기기에서 iOS 테스트를 실행할 수 있습니다. 사용 가능한 기기의 전체 목록을 보려면 대화형 기기 카탈로그를 방문하거나 다음을 실행하세요.

gcloud alpha device-run devices list

출력 예시:

ID                MAKE   NAME           MODEL        HARDWARE_TYPE  OS_VERSION  CAPACITY  AVAILABILITY  PRODUCTS
iphonese3-18-4    Apple  iPhone SE 3             iphonese3    PHYSICAL       18.4        NONE      NONE          Automation
iphonese3-26-3    Apple  iPhone SE 3             iphonese3    PHYSICAL       26.3        NONE      NONE          Automation

이 목록을 필터링하는 방법을 알아보려면 기기 카탈로그를 참고하세요. 테스트 실행을 위해 특정 기기를 타겟팅하려면 제출 명령어에서 해당 ID (예: iphonese3-18-4)를 사용하세요.

3단계: XCTest 준비 및 패키징

테스트를 실행하기 전에 테스트를 컴파일하고, 서명되었는지 확인하고, 코드 서명을 확인하고, 결과 아티팩트를 .xctestrun 구성 및 애플리케이션 테스트 번들이 포함된 ZIP 파일로 패키징해야 합니다.

1. 실제 iOS 기기용 테스트 빌드

Xcode에서 프로젝트를 열고 테스트를 위한 앱 및 테스트 대상을 빌드합니다.

앱 대상과 테스트 실행기 대상 모두에 대해 Xcode에서 코드 서명이 올바르게 구성되어 있는지 확인합니다 (유효한 프로비저닝 프로필 및 개발자 ID 지정).

Xcode (Product > Build For > Testing) 또는 xcodebuild를 사용하여 테스트를 위해 빌드합니다.

작업공간의 경우:

xcodebuild build-for-testing \
  -workspace YourProject.xcworkspace \
  -scheme YourScheme \
  -derivedDataPath ./build \
  -destination "generic/platform=iOS"

독립형 프로젝트의 경우:

xcodebuild build-for-testing \
  -project YourProject.xcodeproj \
  -scheme YourScheme \
  -derivedDataPath ./build \
  -destination "generic/platform=iOS"

이렇게 하면 ./build/Build/Products 아래에 빌드 제품이 생성됩니다.

2. 빌드 제품 및 서명 확인

빌드 후 애플리케이션, 실행기, .xctestrun 매니페스트가 ./build/Build/Products/ 아래에 생성되었는지 확인합니다. 로컬에서 서명된 경우 codesign을 사용하여 번들 서명을 확인할 수 있습니다.

App Bundle을 확인합니다.

codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp.app

예상 출력: YourApp.app: valid on disk

XCUITest를 실행하는 경우 테스트 실행기 번들도 확인합니다.
```
codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp-Runner.app
```
예상 출력: YourApp-Runner.app: valid on disk

3. ZIP 파일 만들기

빌드 출력 제품 폴더에 있는 Debug-iphoneos 디렉터리와 .xctestrun 파일을 모두 단일 ZIP 파일로 압축합니다.

빌드 제품 디렉터리에서 다음 명령어를 실행합니다.

cd ./build/Build/Products
zip -r MyTests.zip Debug-iphoneos *.xctestrun

이렇게 하면 --test 플래그와 함께 사용할 준비가 된 패키징된 MyTests.zip이 생성됩니다.

4단계. XCTest 실행

다음 플래그가 필요합니다.

기기: --device를 사용하여 기기를 지정합니다. --device iphonese3-18-4
테스트: --test를 사용하여 테스트 ZIP 파일을 지정합니다. --test ./MyTests.zip

XCTest를 실행하려면 gcloud alpha device-run sessions submit xctest 명령어를 사용하세요. 이전 단계에서 컴파일된 테스트 ZIP 파일 (MyTests.zip)을 제공해야 합니다.

기본 테스트 세션을 실행하려면 다음 안내를 따르세요.

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./MyTests.zip

실행이 시작되면 CLI는 생성된 세션 ID와 결과가 저장될 Cloud Storage 대상을 표시합니다.

Creating session [session-ee78b0ed] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/session-ee78b0ed/].

Waiting for session [session-ee78b0ed] to complete....

5단계. 테스트 실행 탐색 및 관리

다음 명령어를 사용하여 활성 실행을 추적하고 이전 세션을 관리할 수 있습니다.

세션 설명: 세션의 실시간 진행률 또는 최종 결과를 쿼리합니다. gcloud alpha device-run sessions describe SESSION_ID 기기 할당, 실행 ID, Cloud Storage 아티팩트 경로를 비롯한 전체 세부정보를 보려면 --full을 추가합니다.
세션 나열: 최근 실행을 봅니다. gcloud alpha device-run sessions list --limit=10
세션 취소: 실행 중인 테스트 세션을 중지합니다. gcloud alpha device-run sessions cancel SESSION_ID
작업 취소: 대기 중이거나 활성 상태인 작업을 중지합니다. gcloud alpha device-run operations cancel OPERATION_ID

다음 단계

다음으로 로그를 찾고 분석합니다.