Developer Device Platform Device Run für Android

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:

  1. Ein Google Cloud Projekt erstellt.
  2. Die Developer Device Platform gemäß der Kurzanleitung eingerichtet.
  3. Sich im Terminal mit gcloud authentifiziert.
  4. Die Übersicht zu Device Run mit allgemeinen Informationen gelesen.
  5. 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 --device mit mehreren durch Kommas getrennten Geräte-IDs an, z. B. --device shiba-34,tokay-36, oder mit mehreren --device Flags, 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. SOURCE unterstützt sowohl lokale Pfade als auch Cloud Storage-Pfade (gs://...). DEST ist 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 (ohne gs://-Schema oder -Pfad) an. Wenn Sie keinen Bucket angeben, verwendet oder erstellt die Google Cloud CLI einen Standard-Bucket mit dem Namen PROJECT_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 ist 1 Versuch).
  • Geräteumgebung und -diagnose: Konfigurieren Sie die Geräteausrichtung (--orientation=portrait oder landscape), das Gebietsschema (--locale=en-US), den simulierten GPS-Standort (--coordinates=LATITUDE,LONGITUDE), die Bildschirmvideoaufzeichnung (--video=always oder on-failure), die dumpsys-Erfassung (--dumpsys=always oder on-failure) oder die bugreport-Erfassung (--bugreport=always oder on-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_n Flag 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 zwischen 1m und 3h, der Standardwert ist 5m).

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 zwischen 1m und 3h, der Standardwert ist 5m, 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 die clearPackageData Einstellung so ein: --additional-test-options clearPackageData=true

  • Abstürze werden isoliert. Wenn ein Test abstürzt, wird nur die eigene Instanz von Instrumentation beendet. 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 --device an: --device shiba-35
  • Test: Geben Sie die Test-APK mit --test an: --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 --device an: --device shiba-35
  • Ausführbare Datei: Geben Sie den lokalen Pfad oder den Cloud Storage-Pfad zur ausführbaren Datei mit --executable an: --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 n Shards 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-name angegeben wurde, im smart-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.