이 가이드에서는 gcloud beta device-run CLI를 사용하여 Android 계측 테스트를 실행하고 Google Cloud Console에서 결과를 확인하는 방법을 설명합니다. Google Cloud 계정과 프로젝트가 있다고 가정합니다.
Firebase Test Lab에서 Developer Device Platform으로 이전하는 경우 AI 에이전트의 이전 가이드, 명령어 및 플래그 변환, 이전 기술을 참고하세요.
이 Google Cloud CLI를 사용하려면 Google Cloud 프로젝트 ID를 제공해야 합니다. 명령어 요약은 gcloud beta device-run를 참조하세요.
시작하기 전에
이 단계에서는 다음 작업을 이미 완료했다고 가정합니다.
- Google Cloud 프로젝트를 만들었습니다.
- 빠른 시작에 따라 Developer Device Platform을 설정합니다.
- 터미널에서
gcloud로 인증했습니다. - 일반적인 정보는 기기 실행 개요를 검토했습니다.
- Android용 계측 테스트를 빌드했습니다.
1단계: 테스트 실행 구성
Android 계측 테스트 옵션
- 여러 기기: 여러 기기에서 동일한 테스트를 실행하려면
--device플래그를 쉼표로 구분된 여러 기기 ID(예:--device shiba-34,tokay-36)와 함께 제공하거나 각각 고유한 기기 ID를 지정하는 여러--device플래그(예:--device shiba-34 --device tokay-36)와 함께 제공합니다. - 기기에 파일 푸시:
--other-files-to-push=SOURCE=DEST,...를 사용하여 실행하기 전에 추가 파일 (예: ML 모델 가중치, 테스트 입력 또는.so공유 라이브러리)을 기기에 푸시합니다.SOURCE는 로컬 경로와 Cloud Storage (gs://...) 경로를 모두 지원하며DEST는 기기의 대상 경로입니다. - 기기에서 파일 가져오기: 실행이 완료된 후
--paths-to-pull=DEVICE_PATH,...를 사용하여 기기에서 생성된 파일 또는 디렉터리를 가져옵니다. - 커스텀 Cloud Storage 버킷:
--bucket-name=를 사용하여 기존 Cloud Storage 버킷 이름 (gs://스키마 또는 경로 없음)을 지정합니다. 버킷을 지정하지 않으면 Google Cloud CLI는PROJECT_ID-devicerun라는 기본 버킷을 사용하거나 만듭니다. - 불안정한 테스트 재시도: 불안정성을 처리하기 위해 작업 또는 샤드당 최대 시도 횟수를 설정합니다.
--flaky-test-attempts=3(기본값은1회 시도) - 기기 환경 및 진단: 기기 방향(
--orientation=portrait또는landscape), 언어 (--locale=en-US), 모의 GPS 위치 (--coordinates=LATITUDE,LONGITUDE), 화면 동영상 녹화(--video=always또는on-failure),dumpsys수집 (--dumpsys=always또는on-failure),bugreport수집 (--bugreport=always또는on-failure)을 구성합니다. - 라벨:
--labels=KEY=VALUE,...를 사용하여 사용자 정의 키-값 라벨을 세션에 연결합니다. - 추가 앱: 원하는 경우
--apps=path1,path2,...,path_n플래그를 사용하여 테스트를 실행하기 전에 설치할 APK, AAB 또는 APKS 파일을 하나 이상 지정할 수 있습니다. 지정한 순서대로 앱이 설치됩니다. - 테스트 제한 시간: 실행 기간을 제한합니다.
--instrumentation-timeout=10m(유효한 범위는1m~3h이며 기본값은5m입니다.)
동기 및 비동기 실행
기본적으로 제출 명령어는 차단 (동기식)입니다. 테스트가 완료될 때까지 기다린 후 결과 요약 표를 출력합니다.
세션을 제출하고 Cloud Storage에 파일을 업로드한 직후에 반환하려면 --async 플래그를 추가합니다.
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--async
그러면 세션 ID가 즉시 반환됩니다. 그런 다음 sessions wait 명령어를 사용하여 기다릴 수 있습니다.
gcloud beta device-run sessions wait SESSION_ID
작업이 완료될 때까지 명령어가 차단됩니다.
다수의 기기
여러 기기에서 동일한 테스트를 실행하려면 --device 플래그에 여러 기기 ID를 쉼표로 구분하여 제공하거나 여러 --device 플래그를 제공하여 각각 고유한 기기 ID를 지정합니다.
gcloud beta device-run sessions submit instrumentation \
--device shiba-34,tokay-36 \
--test ./ANDROID_TESTS.apk
또는
gcloud beta device-run sessions submit instrumentation \
--device shiba-34 \
--device tokay-36 \
--test ./ANDROID_TESTS.apk
테스트 제한시간
테스트 실행 시간을 제한합니다.
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--instrumentation-timeout=10m
유효한 범위는 1m~3h이며 기본값은 5m입니다.
소프트웨어 버전
사용 가능한 소프트웨어 패키지와 AndroidX Test Orchestrator 버전을 검색하여 사용하고 테스트 실행을 구성하기 전에 수명 주기, 지원되는 버전, 메타데이터를 검사합니다.
먼저 사용 가능한 모든 소프트웨어 패키지와 해당 버전을 나열합니다.
gcloud beta 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 beta device-run software-versions describe androidx-test-orchestrator-1-4-1
다음과 유사한 출력이 표시됩니다.
id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1
이제 사용 가능한 소프트웨어 버전을 알았으므로 다음과 같이 --orchestrator-version 플래그를 사용하여 테스트 실행에 사용할 수 있습니다.
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--orchestrator-version=1.4.1
Orchestrator 사용 설정
Developer Device Platform은 Android Test Orchestrator를 지원하므로 자체 Instrumentation 호출 내에서 각 앱의 테스트를 실행할 수 있습니다.
Orchestrator를 사용하면 다음과 같은 이점이 있습니다.
공유 상태를 피합니다. 각 테스트는 자체
Instrumentation인스턴스에서 실행됩니다. 따라서 테스트에서 앱 상태를 공유하는 경우 대부분의 공유 상태는 각 테스트 후에 기기의 CPU 또는 메모리에서 삭제됩니다. 각 테스트 후 기기의 CPU 및 메모리에서 모든 공유 상태를 삭제하려면 다음과 같이clearPackageData설정을 포함합니다.--additional-test-options clearPackageData=true비정상 종료 격리. 테스트 하나가 비정상 종료되더라도 자체
Instrumentation인스턴스만 중단합니다. 즉, 다른 테스트는 계속 실행되고 전체 테스트 결과를 제공합니다.
Android Test Orchestrator는 Developer Device Platform에서 기본적으로 사용 중지되어 있습니다. Orchestrator를 사용 설정하고 테스트 실행 중에 사용할 버전을 지정하려면 다음과 같이 sessions submit
instrumentation 명령어의 --orchestrator-version=ORCHESTRATOR_VERSION 플래그에 선택한 버전을 전달합니다.
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--orchestrator-version=1.4.1
시스템 기본 Orchestrator 버전을 사용하려면 플래그를 auto로 설정합니다.
2단계: 기기 선택
device-run CLI를 사용하면 사용 가능한 실제 기기와 가상 기기에서 Android 테스트를 실행할 수 있습니다. 사용 가능한 기기의 전체 목록을 보려면 대화형 기기 카탈로그를 방문하거나 다음을 실행합니다.
gcloud beta device-run devices list
출력 예시:
ID MAKE NAME MODEL FORM OS_VERSION CAPACITY AVAILABILITY PRODUCTS
tegu-35 Google Pixel 9a tegu PHYSICAL 35 MEDIUM LOW Automation, Streaming
tokay-34 Google Pixel 9 tokay PHYSICAL 34 HIGH HIGH Automation, Streaming
이 목록을 필터링하는 방법을 알아보려면 기기 카탈로그를 참고하세요. 실행할 특정 기기를 타겟팅하려면 제출 명령어에서 해당 ID (예: tegu-35)를 사용합니다.
3단계: 테스트 실행
Android 계측 테스트 APK를 제출합니다.
Android 계측 테스트에는 다음 플래그가 필요합니다.
- 기기:
--device를 사용하여 기기를 지정합니다.--device shiba-35 - 테스트:
--test를 사용하여 테스트 APK를 지정합니다.--test /path/to/test.apk
계측 테스트를 실행하려면 자체 기기 ID와 테스트 경로를 사용하여 다음과 유사한 sessions submit
instrumentation 명령어를 실행합니다.
gcloud beta device-run sessions submit instrumentation \
--device shiba-34 \
--apps /path/to/app.apk \
--test /path/to/test.apk
작업의 결과 보고서 폴더는 gs://BUCKET_NAME/automation/sessions/SESSION_ID/과 같은 Cloud Storage 경로에서 찾을 수 있습니다. https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/와 유사한 링크의 명령어 출력을 확인합니다.
4단계: 샤딩 사용
지속적 통합 및 지속적 배포 (CI/CD) 워크플로에 Developer Device Platform 계측 테스트를 포함하려면 테스트를 샤딩하는 것이 좋습니다. 테스트 샤딩 시 격리되어 개별적으로 실행되는 하위 그룹(샤드)으로 계측 테스트 집합이 분할됩니다. Developer Device Platform은 여러 기기를 사용해 각 샤드를 자동으로 동시 실행하여 전체 테스트 집합의 완료 시간을 단축합니다.
4.1단계. 샤딩 옵션 선택
작업에 테스트 사례가 적거나 모든 테스트 사례의 총 실행 시간이 길지 않은 경우 샤딩을 사용할 필요가 없습니다. 테스트 사례가 많거나 모든 테스트 사례의 총 실행 시간이 긴 경우 샤딩을 사용하는 것이 좋습니다.
Developer Device Platform은 스마트 샤딩과 균일 샤딩을 모두 지원합니다. 테스트를 샤딩하는 방법을 결정할 때 다음 옵션을 고려하세요.
모든 테스트 사례에 비슷한 시간이 소요되는 경우 모든 테스트 사례를
n샤드로 나누어 균일한 샤딩을 사용합니다.여러 테스트 사례의 실행 시간이 크게 다를 때는 스마트 샤딩을 사용합니다. Developer Device Platform은 이전 테스트 실행 시간을 사용하여 다양한 샤드를 만들고 비슷한 시간 내에 모든 샤드를 완료하려고 시도합니다.
균일 샤딩
균일한 샤딩으로 테스트를 샤딩하려면 다음과 같이 sessions submit instrumentation 명령어에 --sharding-option=uniform 및 --uniform-sharding-count= 플래그를 포함합니다.
gcloud beta device-run sessions submit instrumentation \
--test path/to/test.apk \
--device shiba-34,tokay-36 \
--sharding-option=uniform \
--uniform-sharding-count=2
Job status: 2 running를 나타내는 출력이 표시됩니다. 서비스는 기기당 하나씩 두 개의 작업을 만듭니다. 두 작업의 입력이 동일하므로 서비스는 검증을 중앙 집중화하여 한 번만 수행합니다.
완료되면 명령어의 최종 출력에 두 작업이 별도로 나열됩니다.
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 execution-000 PASSED
job-001 execution-000 PASSED
스마트 샤딩
스마트 샤딩으로 테스트를 샤딩하려면 다음과 같이 sessions
submit instrumentation 명령어에 --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (분 또는 1시간), --smart-sharding-record-name= 플래그를 포함합니다.
gcloud beta device-run sessions submit instrumentation \
--test path/to/test.apk \
--device shiba-34,shiba-35,tokay-36 \
--sharding-option=smart \
--smart-sharding-max-shard-count=3 \
--smart-sharding-target-duration=5m \
--smart-sharding-record-name=test.yaml
3개의 작업이 실행되었음을 나타내는 최종 출력이 표시됩니다.
Session [session-3cd0564a] finished with result [ERROR].
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 execution-000 PASSED
job-001 execution-000 PASSED
job-002 execution-000 PASSED
다음은 여기에 사용된 스마트 샤딩 플래그를 요약한 것입니다.
--smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT- 스마트 샤딩을 위해 만들 최대 샤드 수를 지정합니다. 설정하지 않거나 0으로 설정하면 시스템 정의 최댓값이 사용됩니다. 유효한 범위는 실제 기기의 경우 0~20이고 가상 기기의 경우 0~200입니다.--smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION- 스마트 샤딩을 위해 샤드당 타겟팅된 실행 시간 (예: 2m, 10m, 1h)을 지정합니다. 유효한 범위는 2분~1시간입니다.--sharding-option=smart인 경우 필수입니다.--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME- 스마트 샤딩 레코드 파일의 이름을 지정합니다(파일 확장자 제외). --sharding-option=smart인 경우 필수입니다. 이 YAML 파일은smart-sharding/디렉터리 아래의--bucket-name로 지정된 Google Cloud스토리지 버킷에 있습니다. 파일이 없으면 자동으로 생성되고, 파일이 있으면 세션이 완료될 때 파일 내용이 업데이트됩니다.
5단계: 테스트 실행 탐색 및 관리
sessions submit instrumentation 명령어의 비동기 및 동기 모드 모두에서 sessions describe 명령어를 사용하여 실행 중에 작업 상태를 쿼리하거나 완료 후 결과를 가져올 수 있습니다.
gcloud beta device-run sessions describe SESSION_ID
출력에는 테스트 결과 요약과 Google Cloud 콘솔의 결과 링크가 표시됩니다. 예를 들면 다음과 같습니다.
Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 all FAILED: 2 test cases failed, 5 passed
다음 명령어를 사용하여 실행 중인 세션과 완료된 세션을 모두 나열합니다.
gcloud beta device-run sessions list
프로젝트의 세션 목록이 포함된 출력을 받습니다. 다음과 유사합니다.
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
session-911d0763 2026-07-09T00:39:02.051Z DONE
session-4e943fea 2026-07-15T23:08:32.252Z DONE
session-0132e458 2026-08-20T18:33:19.751Z DONE
session-1077f07b 2026-07-28T22:35:43.848Z DONE
session-71b054c6 2026-07-15T01:15:41.643Z DONE
session-4f8b2e45 2026-08-06T23:11:56.161Z DONE
sessions list 명령어는 모든 표준 Google Cloud CLI 플래그 옵션을 지원합니다. 예를 들면 다음과 같습니다.
gcloud beta device-run sessions list --limit 5
그러면 다음과 같은 결과가 표시됩니다.
SESSION_ID START_TIME STATE
session-4825e153 2026-07-28T16:38:43.155Z DONE
session-813ca602 2026-07-28T22:40:32.415Z DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce 2026-07-03T05:10:58.015Z DONE
session-67cd0570 2026-07-16T08:25:55.474Z DONE
session-17cc299c 2026-07-14T14:31:33.649Z DONE
실행 중인 모든 세션을 찾으려면 다음을 실행합니다.
gcloud beta device-run sessions list --filter RUNNING
실행 중인 세션이 있는 경우 다음과 같은 결과가 표시됩니다.
SESSION_ID START_TIME STATE
session-d7ff8b81 RUNNING
그렇지 않으면 Listed 0 items.가 표시됩니다.
실행 중인 세션을 취소하려면 세션 ID를 사용하여 다음 명령어를 실행합니다.
gcloud beta device-run sessions cancel SESSION_ID
세션이 취소된 것으로만 표시되므로 명령어가 즉시 반환됩니다. 취소는 백엔드에서 비동기식으로 이루어집니다.
세션이 이미 완료된 경우 현재 상태만 출력됩니다. 완료된 세션에 대한 취소 요청은 오류가 아닙니다.
다음 단계
다음으로 Android 실행 파일을 실행하거나 로그를 찾아 분석합니다.