Firebase Test Lab에서 개발자 기기 플랫폼 명령 및 플래그 변환

Developer Device Platform(DDP)은 기존 Firebase Test Lab 콘솔 및 Test Lab CLI 워크플로를 통합되고 안전한 고성능Google Cloud우선 테스트 CLI인 gcloud beta device-run로 대체합니다.

이 가이드에서는 Test Lab(또는 Flank)에서 DDP로의 명령줄 변환 및 플래그 매핑을 제공합니다. 이 가이드를 참고하여 테스트를 수동으로 이전하세요. 자동화 도구, 이점, 주요 차이점, 마이그레이션 팁은 Firebase Test Lab에서 Developer Device Platform으로 마이그레이션을 참고하세요.

샤딩 마이그레이션

DDP는 Flank의 복잡한 Cloud Storage 기반 스마트 샤딩과 Test Lab의 균일한 샤딩을 모두 기본적으로 대체하여 샤딩 구성을 현대화합니다.

균일 샤딩

  • --sharding-option=uniform을 설정합니다.

  • --uniform-sharding-count={count}를 설정합니다(실제는 1~20, 가상은 1~200).

  • 기존 Firebase Test Lab: --num-uniform-shards {N}

  • DDP CLI: --sharding-option=uniform --uniform-sharding-count={N}

스마트 샤딩

  • --sharding-option=smart을 설정합니다.
  • --smart-sharding-target-duration={duration}을 설정합니다(예: 2m, 10m, 1h, 유효 범위: 2m~1h).
  • --smart-sharding-record-name={record_name}를 설정합니다(automation/smart-sharding/ 아래의 --bucket-name 내에 있는 YAML 추적 레코드를 가리킴).
  • --smart-sharding-max-shard-count={max_count}를 설정합니다(선택사항인 최대 한도: 실제 기기의 경우 0~20, 가상 기기의 경우 0~200).

지난 30일간의 타이밍 메타데이터 사용:

  • 기존 Flank:

    max-test-shards: 10
shard-time: 120
smart-flank-gcs-path: gs://my-bucket/smart-sharding/timing-record.yaml

  • DDP CLI:

    --sharding-option=smart \
--smart-sharding-max-shard-count=10 \
--smart-sharding-target-duration=2m \
--smart-sharding-record-name=timing-record \
--bucket-name=my-bucket

선언적 YAML 구성(--flags-file)

복잡한 구성이나 긴 터미널 명령어 대신 버전 제어 파일을 유지하는 것을 선호하는 팀의 경우 gcloud는 범용 --flags-file 인수 전처리기를 제공합니다($ gcloud topic flags-file 참조).

Android

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

iOS

gcloud alpha device-run sessions submit xctest --flags-file=device-run-flags.yaml

다음은 다중 값 목록 및 사전 플래그를 보여주는 예입니다.

Android

# device-run-flags.yaml
--device:

    -   mediumphone-arm-32
    -   shiba-36
--apps:
    -   app-debug.apk
    -   test-helper.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record
--paths-to-pull:
    -   /sdcard/screenshots
    -   /sdcard/coverage.ec
--additional-test-options:
  coverage: "true"
  clearPackageData: "true"

iOS

# device-run-flags.yaml
--device:

    -   iphonese3-18-4
    -   iphone16pro-18-3
--test: MyTests.zip
--additional-apps:
    -   helper-app.ipa
--xcode-version: '16.4'
--xctest-timeout: 15m
--other-files-to-push:
  /local/path/test-config.json: com.example.app:/Documents/test-config.json
--paths-to-pull:
    -   com.example.app:/Documents/screenshots
--labels:
  env: staging
  team: mobile-qa

엔드 투 엔드 명령어 변환 예시

구체적인 예는 표준 및 복잡한 번역을 참고하세요.

예: 표준 계측 테스트 실행

기존 Firebase CLI:

gcloud firebase test android run \
  --app=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device model=shiba,version=36 \
  --timeout=5m \
  --num-flaky-test-attempts=2 \
  --directories-to-pull=/sdcard/screenshots \
  --environment-variables key=value

DDP CLI 변환:

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --instrumentation-timeout=5m \
  --flaky-test-attempts=3 \
  --paths-to-pull=/sdcard/screenshots \
  --additional-test-options key=value

예시: 복잡한 Flank YAML 구성 이전

기존 Flank 구성:

app: app-debug.apk
test: app-debug-androidTest.apk
device:
  -   model: shiba
    version: 36
shard-time: 120
smart-flank-gcs-path: gs://my-bucket/smart-sharding/timing-record.yaml

DDP CLI 변환:

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --bucket-name=my-bucket \
  --sharding-option=smart \
  --smart-sharding-target-duration=2m \
  --smart-sharding-record-name=timing-record

실행 후 및 결과 검색

DDP는 기존 Firebase Console과 같은 그래픽 웹 UI로 실행되지 않으므로 개발자는 CLI 또는 프로그래매틱 REST API를 사용하여 결과를 직접 관리, 설명, 검사해야 합니다.

# 1. List active and completed test sessions
gcloud beta device-run sessions list

# 2. Get a summary and direct Cloud Storage bucket link of a session's results
gcloud beta device-run sessions describe session-number

# 3. Get detailed metadata and print full results
gcloud beta device-run sessions describe session-number --full

# 4. Cancel a running session (replaces console cancellation)
gcloud beta device-run sessions cancel session-number

플래그 매핑 참조

다음은 Flank 또는 gcloud firebase test android/ios run에서 새 DDP gcloud beta device-run sessions submit instrumentation 및 gcloud alpha device-run sessions submit xctest 명령어로 테스트 구성을 이전하기 위한 플래그 매핑입니다.

핵심 매개변수 및 애셋

기존 매개변수(Test Lab/Flank) 타겟 DDP 매개변수 형식/변환 로직
--project 측면 --project 표준 Google Cloud 전역 플래그(--project=PROJECT_ID) 또는 활성 Google Cloud CLI 구성입니다.
--client-details --labels 테스트 세션에 연결할 key=value 쌍의 사전입니다.
--other-files --other-files-to-push 사전 테스트 실행 전에 기기로 푸시할 보조 파일입니다. 레거시 DEST=SOURCE 순서를 SOURCE=DEST(Android의 경우 SOURCE=DEVICE_PATH, iOS의 경우 SOURCE=BUNDLE_ID:DEVICE_PATH)로 되돌립니다.

기기 설정 및 타겟팅

기존 매개변수(Test Lab/Flank) 타겟 DDP 매개변수 형식/변환 로직
--device model={M},version={V} --device={M}-{V} 필수사항. 모델 및 OS 버전을 단일 --device ID 문자열에 매핑하는 문자열입니다. DDP의 --device 플래그는 쉼표로 구분된 여러 기기 ID를 허용합니다(예: --device=shiba-34,tokay-36 또는 --device=iphone16pro-18-3) 또는 여러 --device 플래그를 전달할 수 있습니다. 각 플래그는 고유한 기기 ID를 지정합니다(예: --device=shiba-34 --device=tokay-36).

실행 제어 및 불안정성

기존 매개변수(Test Lab/Flank) 타겟 DDP 매개변수 형식/변환 로직
--async --async 불리언. 1:1로 매핑됩니다. 명령어는 기본적으로 동기식으로 실행됩니다. 터미널로 즉시 돌아가려면 이 값을 전달합니다. 파일 업로드 직후 종료되고 작업 및 세션 ID를 출력합니다.
--num-flaky-test-attempts {R} --flaky-test-attempts {A} 정수. 테스트 샤드당 최대 실행 시도 횟수입니다. 재시도 횟수 R을 총 시도 횟수 A 한도로 변환합니다. A = R + 1(기본값은 1)

출력 및 저장

기존 매개변수(Test Lab/Flank) 타겟 DDP 매개변수 형식/변환 로직
--results-bucket --bucket-name 문자열. 로컬 입력 파일, 테스트 출력 파일, 스마트 샤딩 타이밍 레코드를 포함한 테스트 아티팩트가 업로드되는 Cloud Storage 버킷입니다(지정하지 않으면 기본값은 gs://[PROJECT_ID]-devicerun).
--results-dir 자동 관리 지원되지 않음. 하위 경로는 Cloud Storage의 automation/sessions/{session_id}/ 아래에 자동으로 구성됩니다.
--directories-to-pull --paths-to-pull 목록 테스트 실행 후 기기에서 다운로드할 파일 또는 디렉터리입니다(Android의 경우 DEVICE_PATH, iOS의 경우 BUNDLE_ID:DEVICE_PATH).

샤딩 구성

기존 매개변수(Test Lab/Flank) 타겟 DDP 매개변수 형식/변환 로직
--num-uniform-shards {N} --sharding-option=uniform --uniform-sharding-count={N} 문자열 및 정수 결합된 플래그 구성은 균일한 샤딩 전략을 활성화하고 최대 샤드 수를 설정합니다(유효한 개수 범위: 실제 1~20개, 가상 1~200개).
--max-test-shards {N} 측면 --sharding-option=smart --smart-sharding-max-shard-count={N} 문자열 및 정수 결합된 플래그 구성은 스마트 샤딩 전략을 활성화하고 최대 샤드 수를 설정합니다(유효한 개수 범위: 실제 0~20개, 가상 0~200개).
--shard-time {S} 측면 --sharding-option=smart --smart-sharding-target-duration={S} 필수 문자열. 타겟 실행 시간(예: 2m, 10m, 1h). 유효한 범위: 2m~1h.
--smart-flank-gcs-path 측면 --smart-sharding-record-name={name} --bucket-name={bucket} 필수 문자열. Cloud Storage의 smart-sharding/ 아래에 있는 --bucket-name 내 샤딩 레코드 YAML의 이름(파일 확장자 제외)입니다.

Android 관련 플래그

이 표를 사용하여 기존 gcloud firebase test android run 및 Flank Android 플래그를 새로운 gcloud beta device-run sessions submit instrumentation 플래그에 매핑합니다.

테스트 유형 특성 그룹 기존 매개변수(firebase android/Flank) 타겟 DDP 매개변수 형식/변환 로직
일반 Android 핵심 매개변수 및 애셋 --app --apps 목록 여러 애플리케이션 APK/AAB가 제공되는 경우 기기에 설치할 순서대로 모두 --apps에 전달합니다. 경로는 로컬 또는 Cloud Storage(gs://...)에 있을 수 있습니다.
일반 Android 핵심 매개변수 및 애셋 --additional-apks --apps 목록 추가 목록 값을 기본 --apps 목록에 직접 병합합니다.
일반 Android 핵심 매개변수 및 애셋 --obb-files --other-files-to-push SOURCE=DEST 형식의 사전입니다. OBB 파일을 대상 기기 경로(/sdcard/Android/obb/{package_name}/)로 직접 푸시합니다.
일반 Android 기기 설정 및 타겟팅 --device locale={L} --locale={L} 문자열. 기기 언어를 최상위 --locale 플래그(language-region, 예: --locale=en-US)을 지정합니다.
일반 Android 기기 설정 및 타겟팅 --device orientation={O} --orientation={O} 문자열. 기기 방향을 최상위 --orientation 플래그(portrait 또는 landscape)에 매핑합니다.
일반 Android 기기 설정 및 타겟팅 해당 사항 없음 --coordinates 문자열. 기기 GPS 위치 좌표를 모의합니다(예: --coordinates=37.4220,-122.0841).
일반 Android 실행 제어 및 불안정성 --grant-permissions 자동 기본 필터 자동. 런타임 권한은 기본적으로 자동으로 부여됩니다(--grant-permissions=all와 동일).
일반 Android 출력 및 저장 해당 사항 없음 --dumpsys 문자열. dumpsys를 사용하여 시스템 상태를 수집합니다(값: always, on-failure).
일반 Android 출력 및 저장 해당 사항 없음 --bugreport 문자열. 기기에서 전체 bugreport를 수집합니다(값: always, on-failure).
일반 Android 출력 및 저장 --record-video --video 문자열. 테스트 실행 중에 기기 화면의 동영상을 녹화할 시점입니다. 유효한 값은 always 또는 on-failure입니다.
Android 계측 핵심 매개변수 및 애셋 --type=instrumentation sessions submit instrumentation 하위 명령어 구조는 --type 플래그 대신 테스트 유형을 결정합니다.
Android 계측 핵심 매개변수 및 애셋 --test --test 필수 문자열. 계측 테스트가 포함된 테스트 APK의 경로입니다(로컬 또는 Cloud Storage).
Android 계측 실행 제어 및 불안정성 --timeout --instrumentation-timeout 길이(예: 10m, 20s, 1h). 유효한 범위: 1m~3h(기본값: 5m)
Android 계측 실행 제어 및 불안정성 해당 사항 없음 --flaky-test-parallel-retry 불리언. 테스트 실패를 동시에 재시도할지 여부입니다(순차 실행의 경우 기본값은 false).
Android 계측 실행 제어 및 불안정성 해당 사항 없음 --flaky-test-retry-level 문자열. shard 또는 개별 test 수준에서 재시도할지 여부를 정의합니다(기본값은 shard).
Android 계측 테스트 실행기 및 타겟 --test-runner-class --test-runner-class 문자열. 정규화된 계측 테스트 실행기 클래스(예: com.foo.MyRunner)을 선택합니다. 지정하지 않으면 애플리케이션의 매니페스트를 검사하여 기본 실행기 클래스가 결정됩니다.
Android 계측 테스트 실행기 및 타겟 --test-targets --test-targets 실행할 테스트 타겟 또는 타겟 필터의 사전입니다. 각 타겟은 package, notPackage, class, notClass, annotation, notAnnotation, size와 같은 키를 지원하는 패키지 이름 또는 클래스 이름으로 정규화되어야 합니다. testfile 또는 notTestfile 형식은 지원되지 않습니다.
Android 계측 테스트 실행기 및 타겟 --use-orchestrator --orchestrator-version Android Test Orchestrator 사용 여부입니다. auto(기본 조정자) 또는 특정 버전 문자열(예: 1.6). 사용 가능한 버전은 gcloud beta device-run software-versions list를 사용하여 쿼리할 수 있습니다.
Android 계측 테스트 실행기 및 타겟 --environment-variables --additional-test-options 계측 테스트 실행기에 전달된 옵션의 사전입니다. --test-targets에서 지원되는 형식은 여기에서 허용되지 않습니다.

iOS 관련 플래그

이 표를 사용하여 기존 gcloud firebase test ios run 및 Flank iOS 플래그를 새로운 gcloud alpha device-run sessions submit xctest 플래그에 매핑합니다.

테스트 유형 특성 그룹 기존 매개변수(firebase ios/Flank) 타겟 DDP 매개변수 형식/변환 로직
일반 iOS 핵심 매개변수 및 애셋 --additional-ipas --additional-apps 테스트 실행 전에 기기에 설치할 도우미 .ipa 파일의 목록입니다.
iOS XCTest만 해당 핵심 매개변수 및 애셋 --type=xctest sessions submit xctest 하위 명령어 구조는 --type 플래그 대신 테스트 유형을 결정합니다(gcloud alpha 사용).
iOS XCTest만 해당 핵심 매개변수 및 애셋 --test --test 필수 문자열. iOS 앱 및 XCTest 파일이 포함된 ZIP 파일의 경로(로컬 또는 Cloud Storage)입니다.
iOS XCTest만 해당 실행 제어 및 불안정성 --timeout --xctest-timeout 길이(예: 5m, 15m, 1h). 유효한 범위: 1m~1h(기본값: 5m)
iOS XCTest만 해당 출력 및 저장 --record-video --video 동영상 녹화 시점: always 또는 on-failure 각 UI 테스트 사례에 대해 하나의 동영상이 녹화됩니다(iOS 17 이상).
iOS XCTest만 해당 테스트 실행기 및 타겟 --xctestrun-file --xctestrun-file 문자열. 커스텀 .xctestrun 파일의 경로(로컬 또는 Cloud Storage)입니다.
iOS XCTest만 해당 테스트 실행기 및 타겟 --xcode-version --xcode-version 문자열. 사용할 Xcode의 카탈로그 ID 또는 버전 문자열입니다(예: xcode-16-4 또는 16.4). 사용 가능한 버전은 gcloud beta device-run software-versions list를 사용하여 쿼리할 수 있습니다.

의견 및 질문

버그 및 기능 요청을 제출하거나 토론 포럼에 참여하려면 Google에 문의하세요.