Jalankan Perangkat Developer Device Platform untuk 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 atau executable Android mandiri menggunakan gcloud beta device-run CLI dan menemukan hasil Anda di Google Cloud konsol. Panduan ini mengasumsikan bahwa Anda memiliki Google Cloud akun dan project.

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

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

Sebelum memulai

Langkah-langkah ini mengasumsikan bahwa Anda telah:

1. Membuat Google Cloud project.
2. Menyiapkan Platform Perangkat Developer dengan mengikuti Panduan Memulai.
3. Mengautentikasi dengan gcloud di terminal.
4. Meninjau Ringkasan Device Run untuk informasi umum.
5. Membuat uji instrumentasi untuk Android, atau menyiapkan executable Android mandiri (seperti biner C++ yang dikompilasi, runner benchmark, atau skrip shell).

Langkah 1. Mengonfigurasi pengujian atau eksekusi yang dapat dijalankan

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

Setelah menjalankan sesi, jelajahi beberapa opsi konfigurasi:

Opsi untuk uji instrumentasi dan executable

• Beberapa perangkat: Untuk menjalankan pengujian atau executable yang sama di beberapa perangkat, berikan flag --device dengan beberapa ID perangkat yang dipisahkan 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).
• Mendorong file ke perangkat: Dorong file tambahan (seperti bobot model ML, input pengujian, atau .so pustaka bersama) 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.
• Mengambil 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.
• Upaya coba ulang uji tidak stabil: Tetapkan jumlah maksimum upaya per tugas atau shard untuk menangani ketidakstabilan: --flaky-test-attempts=3 (defaultnya adalah 1 upaya).
• Lingkungan dan diagnostik perangkat: Konfigurasi 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,....

Opsi uji instrumentasi

• Aplikasi tambahan: Anda dapat secara opsional menentukan satu atau beberapa file APK, AAB, atau APKS untuk diinstal sebelum menjalankan pengujian menggunakan --apps=path1,path2,...,path_n flag. Urutan yang Anda tentukan adalah urutan penginstalan aplikasi ini.
• Batas waktu pengujian: Batasi durasi eksekusi: --instrumentation-timeout=10m (rentang yang valid adalah 1m hingga 3h dan defaultnya adalah 5m).

Opsi executable Android

• Argumen executable: Teruskan argumen command line ke executable menggunakan --executable-args=ARG,... sebagai daftar yang dipisahkan koma atau dengan mengulangi flag. Setiap elemen menjadi satu argumen, jadi tulis ulang command line yang dipisahkan spasi dalam bentuk yang dipisahkan koma (misalnya, --executable-args="--input=a.file,--threads=4"). Untuk meneruskan argumen yang berisi koma, awali nilai dengan ^SEP^ untuk menentukan pemisah yang berbeda (misalnya, --executable-args="^;^--shape=1,224,224,3;--threads=4").
• Variabel lingkungan: Tetapkan variabel lingkungan untuk proses executable di perangkat menggunakan --executable-env-vars=KEY=VALUE,... (misalnya, --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib).
• Batas waktu executable: Batasi durasi eksekusi executable: --executable-timeout=10m (rentang yang valid adalah 1m hingga 3h dan defaultnya adalah 5m, tidak termasuk waktu persiapan dan pembersihan perangkat).

Eksekusi sinkron dan asinkron

Secara default, perintah pengiriman bersifat blocking (sinkron). Perintah ini akan menunggu pengujian atau executable selesai dan mencetak tabel ringkasan hasil.

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

Uji instrumentasi Android

Untuk :

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

Executable Android

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

Tindakan ini akan segera 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 atau executable yang sama di beberapa perangkat, berikan flag --device dengan beberapa ID perangkat yang dipisahkan koma atau dengan beberapa flag --device, yang masing-masing menentukan ID perangkat yang berbeda.

Uji instrumentasi Android

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

Executable Android

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

Atau:

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

Batas waktu pengujian dan executable

Batasi durasi eksekusi pengujian atau executable Anda:

Uji instrumentasi Android

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

Executable Android

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

Rentang yang valid adalah 1m hingga 3h untuk eksekusi Android dan defaultnya adalah 5m.

Versi software

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

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, jelaskan paket tertentu menggunakan ID resource persisnya 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 berikut:

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

Lihat Mengaktifkan Orchestrator untuk mengetahui informasi selengkapnya.

Mengaktifkan Orchestrator

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

Saat menggunakan Orchestrator, Anda:

• Menghindari 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 berikut: --additional-test-options clearPackageData=true

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

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

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, waktu proses yang lebih lama dapat meningkatkan penggunaan kuota atau waktu yang ditagih dan menyebabkan Anda melebihi batas waktu tunggu perangkat. Anda mungkin perlu meningkatkan setelan batas waktu instrumentasi dengan flag --instrumentation-timeout yang sesuai.

Langkah 2. Memilih perangkat

Dengan device-run CLI, pengujian dan executable 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. Jalankan pengujian atau file yang dapat dieksekusi

Anda dapat mengirim APK uji instrumentasi Android atau executable Android mandiri.

Menjalankan uji instrumentasi

Perhatikan bahwa flag ini diperlukan untuk uji instrumentasi Android:

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

Untuk menjalankan uji instrumentasi, keluarkan sessions submit instrumentation yang menyerupai hal 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

Menjalankan executable Android

Untuk menjalankan executable mandiri (seperti biner C++ yang dikompilasi, runner benchmark machine learning di perangkat seperti LiteRT, atau skrip shell) langsung di perangkat Android device tanpa mengemasnya ke dalam APK, gunakan sessions submit android-executable perintah.

Perhatikan bahwa flag ini diperlukan untuk executable Android:

• Perangkat: Tentukan perangkat menggunakan --device: --device shiba-35
• Executable: Tentukan jalur lokal atau Cloud Storage ke executable menggunakan --executable: --executable /path/to/my_executable

Untuk menjalankan executable, keluarkan perintah yang menyerupai hal berikut, menggunakan ID perangkat dan jalur executable Anda sendiri:

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

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

Langkah 4. Menggunakan sharding

Untuk menyertakan uji instrumentasi Platform Perangkat Developer dalam alur kerja Continuous Integration dan Continuous Delivery (CI/CD), Anda harus mempertimbangkan untuk melakukan sharding pada pengujian. Sharding pengujian membagi satu set uji instrumentasi menjadi sejumlah subgrup (shard) yang masing-masing berjalan secara terpisah. Platform Perangkat Developer 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 sejumlah kecil 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.

Platform Perangkat Developer mendukung sharding pintar 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 n shard.

• Jika waktu eksekusi kasus pengujian yang berbeda sangat bervariasi, gunakan sharding pintar. 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 Platform Perangkat Developer menjalankan banyak shard secara paralel, pengujian dapat mengalami bottleneck pada 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 berikut:

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 ini memusatkan validasi, dan hanya melakukannya sekali.

Anda akan melihat dua tugas yang tercantum secara terpisah dalam output akhir perintah saat selesai:

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

Sharding pintar

Untuk melakukan sharding pada pengujian dengan sharding pintar, 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 berikut:

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 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 sharding pintar yang digunakan di sini:

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT - Tentukan jumlah maksimum shard yang akan dibuat untuk sharding pintar. Jika tidak disetel atau disetel 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 pintar. Rentang yang valid adalah 2m hingga 1h. Diperlukan jika --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - Tentukan nama file rekaman sharding pintar, tidak termasuk ekstensi file. Diperlukan jika --sharding-option=smart. File YAML ini terletak di Google Cloud bucket Storage yang ditentukan oleh --bucket-name di smart-sharding/ direktori. 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 sessions submit instrumentation dan sessions submit android-executable perintah, Anda dapat menggunakan sessions describe perintah untuk membuat kueri status tugas selama eksekusi, atau mendapatkan hasilnya setelah selesai:

gcloud beta device-run sessions describe SESSION_ID

Output ini meringkas hasil pengujian dan link ke hasil di Google Cloud konsol. 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

Menerima output yang berisi daftar sesi di 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 menghasilkan hasil 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
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 sedang berjalan, Anda akan melihat hasil yang menyerupai:

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 akan dicetak. Meminta pembatalan untuk sesi yang sudah selesai bukanlah error.

Langkah berikutnya

Selanjutnya, temukan dan analisis log.