In dieser Anleitung wird beschrieben, wie Sie mit der gcloud beta device-run-Befehlszeile einen Android-Instrumentierungstest oder eine eigenständige
ausführbare Android-Datei ausführen und die Ergebnisse
in der Google Cloud Console aufrufen. Dabei wird davon ausgegangen, dass Sie ein Google Cloud Konto und ein Projekt haben.
Wenn Sie von Firebase Test Lab zur Developer Device Platform migrieren, lesen Sie unsere Migrationsanleitung, die Übersetzung von Befehlen und Flagssowie die Migration von Skills für KI-Agenten.
Um diese Google Cloud CLI zu verwenden, müssen Sie Ihre Google Cloud Projekt
-ID angeben. Eine Zusammenfassung der Befehle finden Sie unter gcloud beta device-run für eine
Zusammenfassung der Befehle.
Hinweis
Bei diesen Schritten wird davon ausgegangen, dass Sie Folgendes bereits getan haben:
- Ein Google Cloud Projekt erstellt.
- Die Developer Device Platform gemäß der Kurzanleitung eingerichtet.
- Sich im Terminal mit
gcloudauthentifiziert. - Die Übersicht zu Device Run mit allgemeinen Informationen gelesen.
- Entweder einen instrumentierten Test für Android erstellt oder eine eigenständige ausführbare Android-Datei vorbereitet (z. B. eine kompilierte C++- Binärdatei, einen Benchmark-Runner oder ein Shell-Skript).
Schritt 1: Test oder ausführbare Datei konfigurieren
Nachdem Sie eine Sitzung ausgeführt haben, können Sie einige Konfigurationsoptionen ausprobieren:
Optionen für Instrumentierungstests und ausführbare Dateien
- Mehrere Geräte: Wenn Sie denselben Test oder dieselbe ausführbare Datei auf mehreren
Geräten ausführen möchten, geben Sie das Flag
--devicemit mehreren durch Kommas getrennten Geräte-IDs an, z. B.--device shiba-34,tokay-36, oder mit mehreren--deviceFlags, wobei jedes eine eigene Geräte-ID angibt (z. B.--device shiba-34 --device tokay-36). - Dateien auf das Gerät übertragen: Mit
--other-files-to-push=SOURCE=DEST,...können Sie vor der Ausführung zusätzliche Dateien (z. B. ML-Modellgewichte, Testeingaben oder.sogemeinsam genutzte Bibliotheken) auf das Gerät übertragen.SOURCEunterstützt sowohl lokale Pfade als auch Cloud Storage-Pfade (gs://...).DESTist der Zielpfad auf dem Gerät. - Dateien vom Gerät abrufen: Mit
--paths-to-pull=DEVICE_PATH,...können Sie nach Abschluss der Ausführung generierte Dateien oder Verzeichnisse vom Gerät abrufen. - Benutzerdefinierter Cloud Storage-Bucket: Geben Sie mit
--bucket-name=einen vorhandenen Cloud Storage -Bucket-Namen (ohnegs://-Schema oder -Pfad) an. Wenn Sie keinen Bucket angeben, verwendet oder erstellt die Google Cloud CLI einen Standard-Bucket mit dem NamenPROJECT_ID-devicerun. - Wiederholungen bei instabilen Tests: Legen Sie die maximale Anzahl der Versuche pro Job oder Shard fest, um
Instabilität zu behandeln:
--flaky-test-attempts=3(Standardwert ist1Versuch). - Geräteumgebung und -diagnose: Konfigurieren Sie die Geräteausrichtung
(
--orientation=portraitoderlandscape), das Gebietsschema (--locale=en-US), den simulierten GPS-Standort (--coordinates=LATITUDE,LONGITUDE), die Bildschirmvideoaufzeichnung (--video=alwaysoderon-failure), diedumpsys-Erfassung (--dumpsys=alwaysoderon-failure) oder diebugreport-Erfassung (--bugreport=alwaysoderon-failure). - Labels: Mit
--labels=KEY=VALUE,...können Sie der Sitzung benutzerdefinierte Schlüssel/Wert-Labels zuweisen.
Optionen für Instrumentierungstests
- Zusätzliche Apps: Optional können Sie eine oder mehrere APK-, AAB- oder
APKS-Dateien angeben, die vor dem Ausführen Ihrer Tests installiert werden sollen, indem Sie das
--apps=path1,path2,...,path_nFlag verwenden. Die Reihenfolge, in der Sie sie angeben, ist die Reihenfolge, in der diese Apps installiert werden. - Test-Timeout: Begrenzen Sie die Ausführungsdauer:
--instrumentation-timeout=10m(der gültige Bereich liegt zwischen1mund3h, der Standardwert ist5m).
Optionen für ausführbare Android-Dateien
- Ausführbare Argumente: Übergeben Sie Befehlszeilenargumente an die ausführbare Datei, indem Sie
--executable-args=ARG,...als durch Kommas getrennte Liste angeben oder das Flag wiederholen. Jedes Element wird zu einem Argument. Schreiben Sie daher durch Leerzeichen getrennte Befehlszeilen in kommagetrennter Form um (z. B.--executable-args="--input=a.file,--threads=4"). Wenn Sie ein Argument übergeben möchten, das selbst ein Komma enthält, stellen Sie dem Wert^SEP^voran, um ein anderes Trennzeichen anzugeben (z. B.--executable-args="^;^--shape=1,224,224,3;--threads=4"). - Umgebungsvariablen: Legen Sie Umgebungsvariablen für den ausführbaren
Prozess auf dem Gerät mit
--executable-env-vars=KEY=VALUE,...fest (z. B.--executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib). - Ausführbares Timeout: Begrenzen Sie die Ausführungsdauer der ausführbaren Datei:
--executable-timeout=10m(der gültige Bereich liegt zwischen1mund3h, der Standardwert ist5m, ohne Gerätevorbereitung und Bereinigungszeit).
Synchrone und asynchrone Ausführungen
Standardmäßig ist der Befehl „submit“ blockierend (synchron). Er wartet, bis der Test oder die ausführbare Datei abgeschlossen ist, und gibt eine Zusammenfassung der Ergebnisse aus.
Wenn Sie die Sitzung senden und sofort zurückkehren möchten, nachdem Sie Dateien in Cloud Storage hochgeladen haben, fügen Sie das Flag --async hinzu:
Android-Instrumentierungstest
Für einen :
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--async
Ausführbare Android-Datei
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--async
Dadurch wird sofort eine Sitzungs-ID zurückgegeben. Sie können dann mit dem Befehl sessions wait darauf warten:
gcloud beta device-run sessions wait SESSION_ID
Der Befehl wird blockiert, bis der Job abgeschlossen ist.
Mehrere Geräte
Wenn Sie denselben Test oder dieselbe ausführbare Datei auf mehreren Geräten ausführen möchten, geben Sie das Flag --device mit mehreren durch Kommas getrennten Geräte-IDs an oder verwenden Sie mehrere --device-Flags, wobei jedes eine eigene Geräte-ID angibt.
Android-Instrumentierungstest
gcloud beta device-run sessions submit instrumentation \
--device shiba-34,tokay-36 \
--test ./ANDROID_TESTS.apk
oder:
gcloud beta device-run sessions submit instrumentation \
--device shiba-34 \
--device tokay-36 \
--test ./ANDROID_TESTS.apk
Ausführbare Android-Datei
gcloud beta device-run sessions submit android-executable \
--device shiba-34,tokay-36 \
--executable ./MY_EXECUTABLE
oder:
gcloud beta device-run sessions submit android-executable \
--device shiba-34 \
--device tokay-36 \
--executable ./MY_EXECUTABLE
Test- und ausführbares Timeout
Begrenzen Sie die Ausführungsdauer Ihres Tests oder Ihrer ausführbaren Datei:
Android-Instrumentierungstest
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--instrumentation-timeout=10m
Ausführbare Android-Datei
gcloud beta device-run sessions submit android-executable \
--device shiba-35 \
--executable ./MY_EXECUTABLE \
--executable-timeout=10m
Der gültige Bereich liegt zwischen 1m und 3h für Android-Ausführungen, der Standardwert ist 5m.
Softwareversionen
Sie können verfügbare Softwarepakete und Versionen von AndroidX Test Orchestrator ermitteln und verwenden sowie deren Lebenszyklen, unterstützte Versionen und Metadaten prüfen, bevor Sie Testläufe konfigurieren.
Listen Sie zuerst alle verfügbaren Softwarepakete und ihre Versionen auf:
gcloud beta device-run software-versions list
Sie erhalten eine Ausgabe wie diese:
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
Beschreiben Sie dann ein bestimmtes Paket mit seiner genauen Ressourcen-ID aus der Liste:
gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1
Sie erhalten eine Ausgabe wie diese:
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
Nachdem Sie nun wissen, welche Softwareversionen verfügbar sind, können Sie sie in Ihren Testläufen mit dem Flag --orchestrator-version verwenden:
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--orchestrator-version=1.4.1
Weitere Informationen finden Sie unter Orchestrator aktivieren.
Orchestrator aktivieren
Für Instrumentierungstests unterstützt die Developer Device Platform Android Test
Orchestrator,
mit dem Sie jeden Test Ihrer App in einer eigenen Aufrufung von
Instrumentation ausführen können.
Wenn Sie Orchestrator verwenden, gilt Folgendes:
Gemeinsam genutzter Status wird vermieden. Jeder Test wird in einer eigenen
Instrumentation-Instanz ausgeführt. Wenn Ihre Tests also einen gemeinsamen App-Status haben, wird der größte Teil dieses gemeinsamen Status nach jedem Test von der CPU oder dem Arbeitsspeicher Ihres Geräts entfernt. Wenn Sie den gesamten gemeinsamen Status nach jedem Test von der CPU und dem Arbeitsspeicher Ihres Geräts entfernen möchten, fügen Sie dieclearPackageDataEinstellung so ein:--additional-test-options clearPackageData=trueAbstürze werden isoliert. Wenn ein Test abstürzt, wird nur die eigene Instanz von
Instrumentationbeendet. Das bedeutet, dass Ihre anderen Tests weiterhin ausgeführt werden und vollständige Testergebnisse liefern.
Android Test Orchestrator ist in der Developer Device Platform standardmäßig deaktiviert. Wenn Sie den Orchestrator aktivieren und die Version angeben möchten, die während der Testausführung verwendet werden soll, übergeben Sie die
ausgewählte Version an das
--orchestrator-version=ORCHESTRATOR_VERSION Flag in Ihrem sessions submit
instrumentation Befehl:
gcloud beta device-run sessions submit instrumentation \
--device shiba-35 \
--test ./ANDROID_TESTS.apk \
--orchestrator-version=1.4.1
Setzen Sie das Flag auf auto, um die Standardversion des Orchestrators zu verwenden.
Schritt 2: Geräte auswählen
Mit der device-run-Befehlszeile können Android-Tests und ausführbare Dateien auf verfügbaren physischen und virtuellen Geräten ausgeführt werden. Die vollständige Liste der verfügbaren
Geräte finden Sie entweder im interaktiven Geräte
Katalog oder mit folgendem Befehl:
gcloud beta device-run devices list
Beispielausgabe:
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
Informationen zum Filtern dieser Liste finden Sie im Geräte
Katalog. Wenn Sie ein bestimmtes Gerät für die Ausführung verwenden möchten, geben Sie die entsprechende ID (z. B. tegu-35) im Befehl „submit“ an.
Schritt 3: Test oder ausführbare Datei ausführen
Sie können entweder eine Android-Instrumentierungstest-APK oder eine eigenständige ausführbare Android-Datei senden.
Instrumentierungstest ausführen
Diese Flags sind für Android-Instrumentierungstests erforderlich:
- Gerät: Geben Sie ein Gerät mit
--devicean:--device shiba-35 - Test: Geben Sie die Test-APK mit
--testan:--test /path/to/test.apk
Führen Sie den sessions submit
instrumentation
Befehl aus, um Ihren Instrumentierungstest auszuführen. Verwenden Sie dabei Ihre eigenen Geräte-IDs und den Testpfad:
gcloud beta device-run sessions submit instrumentation \
--device shiba-34 \
--apps /path/to/app.apk \
--test /path/to/test.apk
Ausführbare Android-Datei ausführen
Wenn Sie eine eigenständige ausführbare Datei (z. B. eine kompilierte C++-Binärdatei, einen Benchmark-Runner für maschinelles Lernen auf dem Gerät wie LiteRT oder ein Shell-Skript) direkt auf einem Android-Gerät ausführen möchten, ohne sie in eine APK zu packen, verwenden Sie den sessions submit
android-executable
Befehl.
Diese Flags sind für ausführbare Android-Dateien erforderlich:
- Gerät: Geben Sie ein Gerät mit
--devicean:--device shiba-35 - Ausführbare Datei: Geben Sie den lokalen Pfad oder den Cloud Storage-Pfad zur ausführbaren Datei
mit
--executablean:--executable /path/to/my_executable
Führen Sie den folgenden Befehl aus, um Ihre ausführbare Datei auszuführen. Verwenden Sie dabei Ihre eigenen Geräte-IDs und den Pfad zur ausführbaren Datei:
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
Der Ordner mit dem Ergebnisbericht des Jobs befindet sich unter einem Cloud Storage-Pfad wie gs://BUCKET_NAME/automation/sessions/SESSION_ID/. Den Link finden Sie in der Befehlsausgabe, z. B. https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.
Schritt 4: Sharding verwenden
Wenn Sie Instrumentierungstests der Developer Device Platform in einen CI/CD-Workflow (Continuous Integration und Continuous Delivery) einbeziehen möchten, sollten Sie Ihre Tests aufteilen. Beim Test-Sharding wird eine Reihe von Instrumentierungstests in Untergruppen (Shards) unterteilt, die separat und isoliert ausgeführt werden. Die Developer Device Platform führt jeden Shard automatisch parallel auf mehreren Geräten aus und schließt die gesamte Testreihe in kürzerer Zeit ab.
Schritt 4.1: Sharding-Option auswählen
Wenn Ihre Jobs nur eine kleine Anzahl von Testfällen haben oder die Gesamtausführungszeit aller Testfälle nicht lang ist, ist es nicht erforderlich, Sharding zu verwenden. Wenn Sie eine große Anzahl von Testfällen haben oder die Gesamtausführungszeit aller Testfälle lang ist, sollten Sie Sharding verwenden.
Die Developer Device Platform unterstützt sowohl intelligentes als auch einheitliches Sharding. Berücksichtigen Sie bei der Entscheidung, wie Sie Ihre Tests aufteilen, die folgenden Optionen:
Wenn alle Testfälle ungefähr gleich viel Zeit in Anspruch nehmen, verwenden Sie einheitliches Sharding, indem Sie alle Testfälle in
nShards aufteilen.Wenn die Ausführungszeit der verschiedenen Testfälle stark variiert, verwenden Sie intelligentes Sharding. Die Developer Device Platform verwendet die bisherige Testausführungszeit, um verschiedene Shards zu erstellen, und versucht, alle Shards in einer ähnlichen Zeit zu bearbeiten.
Einheitliches Sharding
Wenn Sie Ihre Tests mit einheitlichem Sharding aufteilen möchten, fügen Sie die Flags --sharding-option=uniform und --uniform-sharding-count= im Befehl sessions submit instrumentation ein:
gcloud beta device-run sessions submit instrumentation \
--test path/to/test.apk \
--device shiba-34,tokay-36 \
--sharding-option=uniform \
--uniform-sharding-count=2
Die Ausgabe sollte Job status: 2 running enthalten. Der Dienst erstellt zwei Jobs, einen für jedes Gerät. Da die Eingaben für beide Jobs identisch sind, zentralisiert der Dienst die Validierung und führt sie nur einmal aus.
Die beiden Jobs werden in der endgültigen Ausgabe des Befehls nach Abschluss separat aufgeführt:
JOB NAME EXECUTION NAME EXECUTION RESULT
job-000 execution-000 PASSED
job-001 execution-000 PASSED
Intelligentes Sharding
Wenn Sie Ihre Tests mit intelligentem Sharding aufteilen möchten, fügen Sie die --sharding-option=smart,
--smart-sharding-max-shard-count=, --smart-sharding-target-duration= (in
Minuten oder 1h) und --smart-sharding-record-name= Flags im sessions
submit instrumentation Befehl ein:
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
Die endgültige Ausgabe sollte drei ausgeführte Jobs enthalten:
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
Hier ist eine Zusammenfassung der hier verwendeten Flags für intelligentes Sharding:
--smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT: Geben Sie die maximale Anzahl der Shards an, die für intelligentes Sharding erstellt werden sollen. Wenn diese Option nicht festgelegt oder auf 0 gesetzt ist, werden vom System definierte Höchstwerte verwendet. Der gültige Bereich liegt zwischen 0 und 20 für physische Geräte und zwischen 0 und 200 für virtuelle Geräte.--smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION: Geben Sie die Zielausführungszeit (z.B. 2m, 10m, 1h) pro Shard für intelligentes Sharding an. Der gültige Bereich liegt zwischen 2 Minuten und 1 Stunde. Erforderlich, wenn--sharding-option=smart.--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME: Geben Sie den Namen der Aufzeichnungsdatei für intelligentes Sharding ohne Dateiendung an. Erforderlich, wenn `--sharding-option=smart`. Diese YAML-Datei befindet sich im Google Cloud Storage-Bucket, der mit--bucket-nameangegeben wurde, imsmart-sharding/Verzeichnis. Wenn die Datei nicht vorhanden ist, wird sie automatisch erstellt. Andernfalls wird ihr Inhalt nach Abschluss der Sitzung aktualisiert.
Schritt 5: Testlauf ansehen und verwalten
Sowohl im asynchronen als auch im synchronen Modus der sessions submit instrumentation und
sessions submit android-executable Befehle können Sie mit dem sessions
describe Befehl den Jobstatus während der Ausführung abfragen oder das
Ergebnis nach Abschluss abrufen:
gcloud beta device-run sessions describe SESSION_ID
Die Ausgabe fasst die Testergebnisse zusammen und enthält Links zu den Ergebnissen in der Google Cloud Console. Beispiel:
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
Verwenden Sie den folgenden Befehl, um alle laufenden und abgeschlossenen Sitzungen aufzulisten:
gcloud beta device-run sessions list
Sie erhalten eine Ausgabe mit der Liste der Sitzungen in Ihrem Projekt, z. B.:
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
Der Befehl sessions list unterstützt alle Standardflagoptionen der Google Cloud CLI. Beispiel:
gcloud beta device-run sessions list --limit 5
Das Ergebnis sieht dann so aus:
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
Führen Sie folgenden Befehl aus, um alle laufenden Sitzungen zu finden:
gcloud beta device-run sessions list --filter RUNNING
Wenn Sie laufende Sitzungen haben, sehen Sie Ergebnisse wie diese:
SESSION_ID START_TIME STATE
session-d7ff8b81 RUNNING
Andernfalls erhalten Sie die Meldung Listed 0 items.
Führen Sie diesen Befehl mit Ihrer Sitzungs-ID aus, um eine laufende Sitzung abzubrechen:
gcloud beta device-run sessions cancel SESSION_ID
Der Befehl wird sofort zurückgegeben, da die Sitzung nur zum Abbrechen markiert wird. Der Abbruch erfolgt asynchron im Back-End.
Wenn die Sitzung bereits beendet ist, wird nur der aktuelle Status ausgegeben. Das Anfordern des Abbruchs für eine abgeschlossene Sitzung ist kein Fehler.
Nächste Schritte
Als Nächstes können Sie Logs suchen und analysieren.