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

Android용 Developer Device Platform 기기 실행

이 가이드에서는 Android 계측 테스트 또는 독립형 Android 실행 파일을 gcloud beta device-run CLI를 사용하여 실행하고 결과를 콘솔에서 Google Cloud 찾는 방법을 설명합니다. 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용 계측 테스트를 빌드했거나 독립형 Android 실행 파일 (예: 컴파일된 C++ 바이너리, 벤치마크 실행기, 셸 스크립트)을 준비했습니다.

1단계: 테스트 또는 실행 파일 실행 구성

이제 세션을 실행했으므로 몇 가지 구성 옵션을 살펴보세요.

계측 테스트 및 실행 파일 옵션

여러 기기: 여러 기기에서 동일한 테스트 또는 실행 파일을 실행하려면 쉼표로 구분된 여러 기기 ID(예: --device shiba-34,tokay-36) 또는 각각 고유한 기기 ID를 지정하는 여러 --device 플래그(예: --device shiba-34 --device tokay-36)를 사용하여 --device 플래그를 제공합니다.
기기에 파일 푸시: 실행 전에 --other-files-to-push=SOURCE=DEST,...를 사용하여 추가 파일 (예: ML 모델 가중치, 테스트 입력 또는 .so 공유 라이브러리)을 기기에 푸시합니다. SOURCE 는 로컬 경로와 Cloud Storage (gs://...) 경로를 모두 지원하며 DEST는 기기의 대상 경로입니다.
기기에서 파일 가져오기: 실행이 완료된 후 --paths-to-pull=DEVICE_PATH,...를 사용하여 생성된 파일 또는 디렉터리를 기기에서 가져옵니다.
커스텀 Cloud Storage 버킷: 기존 Cloud Storage 버킷 이름 (스키마 또는 경로가 없는 gs://)을 --bucket-name=을 사용하여 지정합니다. 버킷을 지정하지 않으면 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,...

계측 테스트 옵션

추가 앱: 테스트를 실행하기 전에 설치할 APK, AAB 또는 APKS 파일을 하나 이상 선택적으로 지정할 수 있습니다. --apps=path1,path2,...,path_n 플래그를 사용합니다. 지정하는 순서대로 이러한 앱이 설치됩니다.
테스트 제한 시간: 실행 시간 제한: --instrumentation-timeout=10m (유효한 범위는 1m~3h이며 기본값은 5m)

Android 실행 파일 옵션

실행 파일 인수: 쉼표로 구분된 목록으로 또는 플래그를 반복하여 --executable-args=ARG,...를 사용하여 명령줄 인수를 실행 파일에 전달합니다. 각 요소는 하나의 인수가 되므로 공백으로 구분된 명령 줄을 쉼표로 구분된 형식으로 다시 작성합니다 (예: --executable-args="--input=a.file,--threads=4"). 쉼표가 포함된 인수를 전달하려면 다른 구분 기호를 지정하기 위해 값에 ^SEP^를 프리픽스로 사용합니다 (예: --executable-args="^;^--shape=1,224,224,3;--threads=4").
환경 변수: --executable-env-vars=KEY=VALUE,...를 사용하여 기기의 실행 파일 프로세스에 대한 환경 변수를 설정합니다 (예: --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib).
실행 파일 제한 시간: 실행 파일의 실행 시간을 제한합니다. --executable-timeout=10m (유효한 범위는 1m~3h이며 기본값은 5m이며 기기 준비 및 정리 시간은 제외됨)

동기 및 비동기 실행

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

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

Android 계측 테스트

다음의 경우 :

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

Android 실행 파일

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

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

gcloud beta device-run sessions wait SESSION_ID

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

여러 기기

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

Android 계측 테스트

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

Android 실행 파일

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

또는

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

테스트 및 실행 파일 제한 시간

테스트 또는 실행 파일의 실행 시간을 제한합니다.

Android 계측 테스트

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

Android 실행 파일

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

유효한 범위는 Android 실행의 경우 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 사용 설정을 참고하세요.

Orchestrator 사용 설정

계측 테스트의 경우 Developer Device Platform은 Android Test Orchestrator를 지원하므로 앱의 자체 호출 내에서 각 앱의 테스트를 실행할 수 있습니다 Instrumentation.

Orchestrator를 사용하면 다음과 같은 이점이 있습니다.

공유 상태 방지. 각 테스트는 자체 Instrumentation 인스턴스에서 실행됩니다. 따라서 테스트에서 앱 상태를 공유하는 경우 대부분의 공유 상태는 각 테스트 후 기기의 CPU 또는 메모리에서 삭제됩니다. 각 테스트 후 기기의 CPU 및 메모리에서 모든 공유 상태를 삭제하려면 다음과 같이 clearPackageData 설정을 포함합니다. --additional-test-options clearPackageData=true
오류 격리. 테스트 하나가 비정상 종료되더라도 자체 Instrumentation 인스턴스만 중단합니다. 즉, 다른 테스트는 계속 실행되고 완전한 테스트 결과를 제공합니다.

개발자 기기 플랫폼에서 Android Test Orchestrator는 기본적으로 사용 중지되어 있습니다. 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 실행 파일을 제출할 수 있습니다.

계측 테스트 실행

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

Android 실행 파일 실행

APK로 패키징하지 않고 Android 기기에서 직접 독립형 실행 파일 (예: 컴파일된 C++ 바이너리, 기기 내 머신 러닝 벤치마크 실행기 또는 셸 스크립트)을 실행하려면 sessions submit android-executable 명령어를 사용합니다.

Android 실행 파일에는 다음 플래그가 필요합니다.

기기: --device를 사용하여 기기를 지정합니다. --device shiba-35
실행 파일: 실행 파일의 로컬 또는 Cloud Storage 경로를 지정합니다. --executable 사용: --executable /path/to/my_executable

실행 파일을 실행하려면 자체 기기 ID 및 실행 파일 경로를 사용하여 다음과 유사한 명령어를 실행합니다.

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

작업의 결과 보고서 폴더는 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 - 스마트 샤딩을 위해 샤드당 타겟 실행 시간 (예: 2분, 10분, 1시간)을 지정합니다. 유효한 범위는 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 submit android-executable 명령어의 비동기 및 동기 모드 모두에서 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

세션이 취소되도록 표시되기만 하므로 명령어는 즉시 반환됩니다. 취소는 백엔드에서 비동기적으로 발생합니다.

세션이 이미 완료된 경우 현재 상태만 출력됩니다. 완료된 세션의 취소를 요청하는 것은 오류가 아닙니다.

다음 단계

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

Android용 Developer Device Platform 기기 실행 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

1단계: 테스트 또는 실행 파일 실행 구성

계측 테스트 및 실행 파일 옵션

계측 테스트 옵션

Android 실행 파일 옵션

동기 및 비동기 실행

Android 계측 테스트

Android 실행 파일

여러 기기

Android 계측 테스트

Android 실행 파일

테스트 및 실행 파일 제한 시간

Android 계측 테스트

Android 실행 파일

소프트웨어 버전

Orchestrator 사용 설정

2단계: 기기 선택

3단계: 테스트 또는 실행 파일 실행

계측 테스트 실행

Android 실행 파일 실행

4단계. 샤딩 사용

4.1단계: 샤딩 옵션 선택

균일 샤딩

스마트 샤딩

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

다음 단계

Android용 Developer Device Platform 기기 실행