Device Run Developer Device Platform untuk Instrumentasi Android

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Panduan ini menjelaskan cara menjalankan uji instrumentasi Android menggunakan gcloud beta device-run CLI dan menemukan hasilnya di Google Cloud console. Panduan ini mengasumsikan bahwa Anda memiliki akun dan project Google Cloud .

Jika Anda bermigrasi dari Firebase Test Lab ke Developer Device Platform, lihat panduan migrasi, terjemahan perintah dan flag, serta kemampuan migrasi untuk agen AI.

Untuk menggunakan Google Cloud CLI ini, Anda harus memberikan project ID Google Cloud . Lihat gcloud beta device-run untuk mengetahui ringkasan perintah.

Sebelum memulai

Langkah-langkah ini mengasumsikan bahwa Anda telah:

1. Membuat project Google Cloud .
2. Siapkan Developer Device Platform dengan mengikuti Panduan memulai.
3. Telah diautentikasi dengan gcloud di terminal.
4. Meninjau Ringkasan Device Run untuk mengetahui informasi umum.
5. Membuat uji instrumentasi untuk Android.

Langkah 1. Mengonfigurasi pengujian

Tips: Untuk melihat semua opsi yang tersedia untuk perintah submit, jalankan gcloud beta device-run sessions submit instrumentation --help.

Opsi untuk uji instrumentasi Android

• Beberapa perangkat: Untuk menjalankan pengujian yang sama di beberapa perangkat, berikan flag --device dengan beberapa ID perangkat yang dipisahkan dengan koma, seperti --device shiba-34,tokay-36, atau dengan beberapa flag --device, yang masing-masing menentukan ID perangkat yang berbeda (misalnya, --device shiba-34 --device tokay-36).
• Kirim file ke perangkat: Kirim file tambahan (seperti bobot model ML, input pengujian, atau pustaka bersama .so) ke perangkat sebelum eksekusi menggunakan --other-files-to-push=SOURCE=DEST,.... SOURCE mendukung jalur lokal dan jalur Cloud Storage (gs://...), dan DEST adalah jalur tujuan di perangkat.
• Ambil file dari perangkat: Ambil file atau direktori yang dihasilkan dari perangkat setelah eksekusi selesai menggunakan --paths-to-pull=DEVICE_PATH,....
• Bucket Cloud Storage kustom: Tentukan nama bucket Cloud Storage yang ada (tanpa skema atau jalur gs://) menggunakan --bucket-name=. Jika Anda tidak menentukan bucket, Google Cloud CLI akan menggunakan atau membuat bucket default bernama PROJECT_ID-devicerun.
• Flaky test retries: Tetapkan jumlah maksimum upaya per tugas atau shard untuk menangani uji tidak stabil: --flaky-test-attempts=3 (defaultnya adalah 1 upaya).
• Lingkungan dan diagnostik perangkat: Konfigurasikan orientasi perangkat (--orientation=portrait atau landscape), lokalitas (--locale=en-US), lokasi GPS tiruan (--coordinates=LATITUDE,LONGITUDE), perekaman video layar (--video=always atau on-failure), pengumpulan dumpsys (--dumpsys=always atau on-failure), atau pengumpulan bugreport (--bugreport=always atau on-failure).
• Label: Lampirkan label nilai kunci yang ditentukan pengguna ke sesi menggunakan --labels=KEY=VALUE,....
• Aplikasi tambahan: Anda dapat menentukan satu atau beberapa file APK, AAB, atau APKS untuk diinstal sebelum menjalankan pengujian menggunakan flag --apps=path1,path2,...,path_n. Urutan yang Anda tentukan adalah urutan penginstalan aplikasi ini.
• Waktu tunggu pengujian: Batasi durasi eksekusi: --instrumentation-timeout=10m (rentang yang valid adalah 1m hingga 3h dan defaultnya adalah 5m).

Operasi sinkron dan asinkron

Secara default, perintah kirim bersifat memblokir (sinkron). Perintah ini akan menunggu pengujian selesai dan mencetak tabel ringkasan hasilnya.

Untuk mengirimkan sesi dan segera kembali setelah mengupload file ke Cloud Storage, tambahkan flag --async:

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

Tindakan ini akan langsung menampilkan ID sesi. Kemudian, Anda dapat menunggunya menggunakan perintah sessions wait:

gcloud beta device-run sessions wait SESSION_ID

Perintah akan diblokir hingga tugas selesai.

Beberapa perangkat

Untuk menjalankan pengujian yang sama di beberapa perangkat, berikan flag --device dengan beberapa ID perangkat yang dipisahkan dengan koma atau dengan beberapa flag --device, yang masing-masing menentukan ID perangkat yang berbeda:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

Atau:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

Waktu tunggu uji

Batasi durasi eksekusi pengujian Anda:

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

Rentang yang valid adalah 1m hingga 3h dan default-nya adalah 5m.

Versi software

Temukan dan gunakan paket software serta versi AndroidX Test Orchestrator yang tersedia, dan periksa siklus proses, versi yang didukung, dan metadatanya sebelum mengonfigurasi uji coba.

Pertama, cantumkan semua paket software yang tersedia dan versinya:

gcloud beta device-run software-versions list

Menerima output yang menyerupai:

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

Kemudian, deskripsikan paket tertentu menggunakan ID resource yang tepat dari daftar:

gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1

Menerima output yang menyerupai:

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

Setelah mengetahui versi software yang tersedia, Anda dapat menggunakannya dalam pengujian dengan flag --orchestrator-version, seperti ini:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Mengaktifkan Orchestrator

Developer Device Platform mendukung Android Test Orchestrator, yang memungkinkan Anda menjalankan setiap pengujian aplikasi dalam pemanggilan Instrumentation-nya sendiri.

Saat menggunakan Orchestrator, Anda:

• Hindari status bersama. Setiap pengujian berjalan dalam instance Instrumentation-nya sendiri. Jadi, jika pengujian Anda berbagi status aplikasi, sebagian besar status bersama tersebut akan dihapus dari CPU atau memori perangkat Anda setelah setiap pengujian. Untuk menghapus semua status bersama dari CPU dan memori perangkat Anda setelah setiap pengujian, sertakan setelan clearPackageData seperti ini: --additional-test-options clearPackageData=true

• Mengisolasi error. Jika satu pengujian mengalami error, hanya instance Instrumentation-nya yang akan dikeluarkan. Artinya, pengujian Anda yang lain tetap berjalan dan memberikan hasil pengujian yang lengkap.

Android Test Orchestrator dinonaktifkan secara default di Developer Device Platform. Untuk mengaktifkan Orchestrator dan menentukan versinya yang akan digunakan selama eksekusi uji, teruskan versi yang Anda pilih ke flag --orchestrator-version=ORCHESTRATOR_VERSION dalam perintah sessions submit instrumentation, seperti ini:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Tetapkan flag ke auto untuk menggunakan versi Orchestrator default sistem.

Catatan: Karena setiap pengujian Orchestrator menjalankan instance Instrumentation-nya sendiri, peningkatan waktu proses dapat meningkatkan penggunaan kuota atau waktu yang ditagih dan menyebabkan Anda melebihi batas waktu tunggu perangkat. Anda mungkin perlu meningkatkan setelan waktu tunggu instrumentasi dengan flag --instrumentation-timeout yang sesuai.

Langkah 2. Pilih perangkat

Dengan menggunakan device-run CLI, pengujian Android dapat dijalankan di seluruh perangkat fisik dan virtual yang tersedia. Untuk melihat daftar lengkap perangkat yang tersedia, buka Katalog Perangkat interaktif atau jalankan:

gcloud beta device-run devices list

Contoh output:

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

Lihat Katalog Perangkat untuk mempelajari cara memfilter daftar ini. Untuk menargetkan perangkat tertentu untuk eksekusi Anda, gunakan ID yang sesuai (misalnya, tegu-35) dalam perintah pengiriman.

Langkah 3. Menjalankan pengujian

Kirim APK uji instrumentasi Android.

Flag ini diperlukan untuk uji instrumentasi Android:

• Perangkat: Tentukan perangkat menggunakan --device: --device shiba-35
• Test: Tentukan APK pengujian menggunakan --test: --test /path/to/test.apk

Untuk menjalankan uji instrumentasi, jalankan perintah sessions submit instrumentation yang mirip dengan berikut, menggunakan ID perangkat dan jalur pengujian Anda sendiri:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --apps /path/to/app.apk \
  --test /path/to/test.apk

Folder laporan hasil tugas dapat ditemukan di jalur Cloud Storage seperti gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Lihat output perintah untuk link, yang menyerupai: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Langkah 4. Menggunakan sharding

Untuk menyertakan uji instrumentasi Developer Device Platform dalam alur kerja Continuous Integration dan Continuous Delivery (CI/CD), sebaiknya lakukan sharding pada pengujian Anda. Sharding pengujian membagi satu set uji instrumentasi menjadi sejumlah subgrup (shard) yang masing-masing berjalan secara terpisah. Developer Device Platform otomatis menjalankan setiap shard secara bersamaan menggunakan beberapa perangkat dan menyelesaikan keseluruhan set pengujian tersebut dalam waktu yang lebih singkat.

Perhatian: Melakukan pengujian dengan sharding dapat dikenai biaya lebih mahal. Meskipun sharding pengujian mengurangi waktu yang diperlukan untuk menjalankan semua pengujian, overhead untuk memulai aplikasi pada setiap shard dapat meningkatkan waktu setiap perangkat.

Langkah 4.1. Memilih opsi sharding

Jika tugas Anda hanya memiliki sedikit kasus pengujian, atau total waktu eksekusi semua kasus pengujian tidak lama, Anda tidak perlu menggunakan sharding. Jika Anda memiliki banyak kasus pengujian, atau total waktu eksekusi semua kasus pengujiannya lama, pertimbangkan untuk menggunakan sharding.

Developer Device Platform mendukung sharding cerdas dan seragam. Saat memutuskan cara melakukan sharding pada pengujian, pertimbangkan opsi berikut:

• Jika semua kasus pengujian akan memerlukan waktu yang sama, gunakan sharding seragam dengan membagi semua kasus pengujian menjadi shard n.

• Jika waktu eksekusi berbagai kasus pengujian sangat bervariasi, gunakan sharding cerdas. Developer Device Platform menggunakan waktu eksekusi uji historis untuk membuat shard yang berbeda dan mencoba menyelesaikan semua shard dalam durasi yang sama.

Catatan: Jumlah shard dapat dikonfigurasi, sehingga saat Developer Device Platform menjalankan banyak shard secara paralel, pengujian dapat terhambat oleh ketersediaan perangkat. Oleh karena itu, sebaiknya jumlah perangkat yang ditentukan dalam flag --device kurang dari atau sama dengan jumlah shard.

Sharding seragam

Untuk melakukan sharding pada pengujian dengan sharding seragam, sertakan flag --sharding-option=uniform dan --uniform-sharding-count= dalam perintah sessions submit instrumentation seperti ini:

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

Anda akan melihat output yang menunjukkan Job status: 2 running. Layanan ini membuat dua tugas, satu untuk setiap perangkat. Karena input untuk kedua tugas tersebut identik, layanan akan memusatkan validasi, dan hanya menjalankannya sekali.

Anda akan melihat dua tugas yang tercantum secara terpisah di output akhir perintah setelah selesai:

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

Smart sharding

Untuk melakukan sharding pada pengujian Anda dengan sharding cerdas, sertakan flag --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (dalam menit atau 1 jam), dan --smart-sharding-record-name= dalam perintah sessions submit instrumentation seperti ini:

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

Anda akan melihat output akhir yang menunjukkan tiga tugas yang dijalankan:

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

Berikut ringkasan flag smart sharding yang digunakan di sini:

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT - Tentukan jumlah maksimum shard yang akan dibuat untuk sharding cerdas. Jika tidak ditetapkan atau ditetapkan ke 0, batas maksimum yang ditentukan sistem akan digunakan. Rentang yang valid adalah 0 hingga 20 untuk perangkat fisik dan 0 hingga 200 untuk perangkat virtual.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION - Tentukan waktu eksekusi yang ditargetkan (misalnya, 2m, 10m, 1h) per shard untuk sharding cerdas. Rentang yang valid adalah 2m hingga 1h. Wajib jika --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - Tentukan nama file data sharding cerdas, tidak termasuk ekstensi file. Diperlukan jika --sharding-option=smart. File YAML ini terletak di bucket Storage Google Cloud yang ditentukan oleh --bucket-name di bagian direktori smart-sharding/. Jika file tidak ada, file akan dibuat secara otomatis; jika tidak, kontennya akan diperbarui setelah sesi selesai.

Langkah 5. Menjelajahi dan mengelola pengujian

Untuk mode asinkron dan sinkron dari perintah sessions submit instrumentation, Anda dapat menggunakan perintah sessions describe untuk mengkueri status tugas selama eksekusi, atau mendapatkan hasilnya setelah selesai:

gcloud beta device-run sessions describe SESSION_ID

Output akan merangkum hasil pengujian dan link ke hasil di konsol Google Cloud . Contoh:

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

Gunakan perintah berikut untuk mencantumkan semua sesi yang sedang berjalan dan yang telah selesai:

gcloud beta device-run sessions list

Terima output yang berisi daftar sesi dalam project Anda, yang menyerupai:

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

Perintah daftar sessions mendukung semua opsi flag Google Cloud CLI standar. Contoh:

gcloud beta device-run sessions list --limit 5

Yang memberikan hasil yang mirip dengan:

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

Atau, untuk menemukan semua sesi yang sedang berjalan, jalankan:

gcloud beta device-run sessions list --filter RUNNING

Dengan asumsi Anda memiliki sesi yang berjalan, Anda akan melihat hasil yang mirip dengan:

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

Jika tidak, Anda akan menerima Listed 0 items.

Untuk membatalkan sesi yang sedang berjalan, jalankan perintah ini dengan ID sesi Anda:

gcloud beta device-run sessions cancel SESSION_ID

Perintah akan segera ditampilkan, karena sesi hanya ditandai untuk dibatalkan. Pembatalan terjadi secara asinkron di backend.

Jika sesi sudah selesai, hanya status saat ini yang dicetak. Meminta pembatalan untuk sesi yang telah selesai bukanlah suatu error.

Langkah berikutnya

Selanjutnya, jalankan file Android yang dapat dieksekusi atau temukan dan analisis log.