이 가이드에서는 gcloud beta device-run CLI를 사용하여 Android 계측 테스트를 실행하고 Google Cloud Console에서 결과를 확인하는 방법을 설명합니다. Google Cloud 계정과 프로젝트가 있다고 가정합니다.
이 Google Cloud CLI를 사용하려면 Google Cloud 프로젝트 ID를 제공해야 합니다. 명령어 요약은 gcloud beta device-run을 참고하세요.
시작하기 전에
다음 단계에서는 다음 작업을 이미 완료했다고 가정합니다.
- Google Cloud 프로젝트를 만들었습니다.
- 빠른 시작에 따라 개발자 기기 플랫폼을 설정합니다.
- 터미널에서
gcloud로 인증했습니다. - 일반 정보를 위해 기기 실행 개요를 검토했습니다.
- Android용 계측 테스트를 빌드했습니다.
1단계: 기기 선택
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)를 제출 명령어에 추가합니다.
2단계: 계측 테스트 실행
Android 테스트에는 다음 플래그가 필요합니다.
- 기기:
--device를 사용하여 기기를 지정합니다.--device shiba-35 - 테스트:
--test를 사용하여 테스트 APK를 지정합니다.--test /path/to/test.apk
테스트를 실행하려면 다음 명령어를 실행하되, 자신의 기기 ID와 테스트 경로를 사용하세요.
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/
3단계: 테스트 실행 구성
이제 테스트를 실행했으므로 몇 가지 구성 옵션을 살펴보세요.
- 여러 기기: 여러 기기에서 동일한 테스트를 실행하려면
--device플래그에--device shiba-34,tokay-36와 같이 쉼표로 구분된 여러 기기 ID를 제공하거나 각각 고유한 기기 ID를 지정하는 여러--device플래그 (예:--device shiba-34 --device tokay-36)를 제공합니다. - 추가 앱:
--apps=path1,path2,...,path_n플래그를 사용하여 테스트를 실행하기 전에 설치할 APK를 하나 이상 지정할 수 있습니다. 지정한 순서대로 이러한 앱이 설치됩니다. - 테스트 시간 제한: 실행 기간을 제한합니다.
--instrumentation-timeout=10m(유효한 범위는1m~1h이며 기본값은5m) - 커스텀 Cloud Storage 버킷:
--bucket-name=플래그를 사용하여 Cloud Storage 버킷을 지정하지 않으면 Google Cloud CLI에서PROJECT_ID-devicerun라는 기본 버킷을 사용합니다. - 불안정한 테스트 재시도: 불안정한 테스트를 다시 실행할 최대 시도 횟수를 설정합니다.
--flaky-test-attempts=3(기본값은 1회 시도)
4단계: 샤딩 사용
지속적 통합 및 지속적 배포(CI/CD) 워크플로에 개발자 기기 플랫폼을 포함하려면 테스트를 샤딩하는 것이 좋습니다. 테스트 샤딩은 격리되어 개별적으로 실행되는 하위 그룹 (샤드)으로 테스트 집합을 분할합니다. 개발자 기기 플랫폼은 여러 기기를 사용해 각 샤드를 자동으로 동시 실행하여 전체 테스트 집합의 완료 시간을 단축합니다.
4.1단계 샤딩 옵션 선택
작업에 테스트 사례가 몇 개만 있거나 모든 테스트 사례의 총 실행 시간이 길지 않은 경우 샤딩을 사용할 필요가 없습니다. 테스트 사례가 많거나 모든 테스트 사례의 총 실행 시간이 긴 경우 샤딩을 사용하는 것이 좋습니다.
개발자 기기 플랫폼은 스마트 샤딩과 균일한 샤딩을 모두 지원합니다. 테스트를 샤딩하는 방법을 결정할 때는 다음 옵션을 고려하세요.
모든 테스트 사례에 비슷한 시간이 걸리는 경우 모든 테스트 사례를
n샤드로 나누어 균일한 샤딩을 사용합니다.다양한 테스트 사례의 실행 시간이 크게 다른 경우 스마트 샤딩을 사용하세요. 개발자 기기 플랫폼은 이전 테스트 실행 시간을 사용하여 다양한 샤드를 만들고 비슷한 기간에 모든 샤드를 완료하려고 시도합니다.
균일 샤딩
균일한 샤딩으로 테스트를 샤딩하려면 다음과 같이 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 목록 명령어는 모든 표준 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
세션이 취소된 것으로 표시되기만 하므로 명령어는 즉시 반환됩니다. 취소는 백엔드에서 비동기적으로 발생합니다.
세션이 이미 종료된 경우 현재 상태만 출력됩니다. 완료된 세션의 취소를 요청하는 것은 오류가 아닙니다.
다음 단계
다음으로 로그를 찾아 분석합니다.