Developer Device Platform Device Run für Android-Instrumentierung

Vorschau

Dieses Produkt oder diese Funktion unterliegt den „Pre-GA-Angebotsbedingungen“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Produkte und -Features sind "im Ist-Zustand" verfügbar und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

In diesem Leitfaden wird beschrieben, wie Sie einen Android-Instrumentierungstest mit der gcloud beta device-run-Befehlszeile ausführen und die Ergebnisse in der Google Cloud Console finden. Es wird davon ausgegangen, dass Sie ein Konto und ein Projekt in Google Cloud haben.

Wenn Sie von Firebase Test Lab zur Developer Device Platform migrieren, lesen Sie unsere Migrationsanleitung, die Übersetzung von Befehlen und Flags und den Migrationsskill für KI-Agenten.

Wenn Sie diese Google Cloud CLI verwenden möchten, müssen Sie Ihre Google Cloud -Projekt-ID angeben. Eine Zusammenfassung der Befehle finden Sie unter gcloud beta device-run.

Hinweis

Bei diesen Schritten wird davon ausgegangen, dass Sie bereits Folgendes getan haben:

1. Sie haben ein Projekt in Google Cloud erstellt.
2. Richten Sie die Developer Device Platform gemäß der Kurzanleitung ein.
3. Im Terminal mit gcloud authentifiziert.
4. Die Device Run-Übersicht mit allgemeinen Informationen gelesen.
5. Instrumentierungstest für Android erstellen

Schritt 1: Testlauf konfigurieren

Tipp: Mit dem Befehl gcloud beta device-run sessions submit instrumentation --help können Sie alle verfügbaren Optionen für die submit-Befehle aufrufen.

Optionen für Android-Instrumentierungstests

• Mehrere Geräte: Wenn Sie denselben Test auf mehreren Geräten ausführen möchten, geben Sie das Flag --device mit mehreren Geräte-IDs an, die durch Kommas getrennt sind, z. B. --device shiba-34,tokay-36, oder mit mehreren --device-Flags, die jeweils eine eindeutige Geräte-ID angeben (z. B. --device shiba-34 --device tokay-36).
• Dateien auf das Gerät übertragen: Übertragen Sie vor der Ausführung mit --other-files-to-push=SOURCE=DEST,... zusätzliche Dateien (z. B. ML-Modellgewichtungen, Testeingaben oder .so gemeinsam genutzte Bibliotheken) auf das Gerät. SOURCE unterstützt sowohl lokale Pfade als auch Cloud Storage-Pfade (gs://...) und DEST ist der Zielpfad auf dem Gerät.
• Dateien vom Gerät abrufen: Generierte Dateien oder Verzeichnisse nach Abschluss der Ausführung mit --paths-to-pull=DEVICE_PATH,... 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 instabiler Tests: Legen Sie die maximale Anzahl von Versuchen pro Job oder Shard fest, um Instabilität zu beheben: --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: Hängen Sie mit --labels=KEY=VALUE,... benutzerdefinierte Schlüssel/Wert-Labels an die Sitzung an.
• Zusätzliche Apps: Sie können optional eine oder mehrere APK-, AAB- oder APKS-Dateien angeben, die vor dem Ausführen der Tests mit dem Flag --apps=path1,path2,...,path_n installiert werden sollen. Die von Ihnen angegebene Reihenfolge ist die Reihenfolge, in der diese Apps installiert werden.
• Testzeitüberschreitung: Begrenzen Sie die Ausführungsdauer: --instrumentation-timeout=10m (gültiger Bereich ist 1m bis 3h, Standardwert ist 5m).

Synchrone und asynchrone Ausführungen

Standardmäßig ist der Befehl „submit“ blockierend (synchron). Es wartet, bis der Test abgeschlossen ist, und gibt eine Übersichtstabelle der Ergebnisse aus.

Wenn Sie die Sitzung senden und sofort nach dem Hochladen von Dateien in Cloud Storage zurückkehren möchten, fügen Sie das Flag --async hinzu:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --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 auf mehreren Geräten ausführen möchten, geben Sie das Flag --device mit mehreren Geräte-IDs durch Kommas getrennt oder mit mehreren Flags --device an, die jeweils eine eindeutige Geräte-ID angeben:

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

Testzeitlimit

Begrenzen Sie die Ausführungsdauer des Tests:

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

Der gültige Bereich liegt zwischen 1m und 3h. Der Standardwert ist 5m.

Softwareversionen

Sie können verfügbare Softwarepakete und Versionen von AndroidX Test Orchestrator finden und verwenden und ihre Lebenszyklen, unterstützten 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

Die Ausgabe sollte in etwa so aussehen:

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 anhand seiner genauen Ressourcen-ID aus der Liste:

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

Die Ausgabe sollte in etwa so aussehen:

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, z. B.:

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

Orchestrator aktivieren

Die Developer Device Platform unterstützt den Android Test Orchestrator, mit dem Sie jeden Test Ihrer App in einem eigenen Aufruf von Instrumentation ausführen können.

Wenn Sie Orchestrator verwenden, gehen Sie so vor:

• Vermeiden Sie einen gemeinsamen Status. Jeder Test wird in einer eigenen Instrumentation-Instanz ausgeführt. Wenn Ihre Tests also den App-Status teilen, wird der größte Teil dieses geteilten Status nach jedem Test von der CPU oder dem Arbeitsspeicher Ihres Geräts entfernt. Wenn Sie nach jedem Test alle freigegebenen Status aus der CPU und dem Arbeitsspeicher Ihres Geräts entfernen möchten, fügen Sie die Einstellung clearPackageData so ein: --additional-test-options clearPackageData=true

• Abstürze isolieren: Wenn ein Test abstürzt, wird nur die eigene Instanz von Instrumentation beendet. Das bedeutet, dass die anderen Tests weiterhin ausgeführt werden und vollständige Testergebnisse liefern.

Android Test Orchestrator ist auf 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 Flag --orchestrator-version=ORCHESTRATOR_VERSION in Ihrem sessions submit instrumentation-Befehl, z. B.:

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 Standard-Orchestrator-Version des Systems zu verwenden.

Hinweis: Da für jeden Orchestrator-Test eine eigene Instrumentation-Instanz ausgeführt wird, können die längeren Laufzeiten zu einer höheren Kontingentnutzung oder abgerechneten Zeit führen und dazu, dass die Zeitlimits Ihrer Geräte überschritten werden. Möglicherweise müssen Sie die Zeitüberschreitungseinstellung für die Instrumentierung mit dem Flag --instrumentation-timeout entsprechend erhöhen.

Schritt 2: Geräte auswählen

Mit der device-run-Befehlszeile können Android-Tests auf verfügbaren physischen und virtuellen Geräten ausgeführt werden. Eine vollständige Liste der verfügbaren Geräte finden Sie im interaktiven Gerätekatalog oder über folgenden 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

Im Gerätekatalog erfährst du, wie du diese Liste filtern kannst. Wenn Sie ein bestimmtes Gerät für die Ausführung verwenden möchten, geben Sie im Befehl zum Senden die entsprechende ID an (z. B. tegu-35).

Schritt 3: Test ausführen

Reiche ein APK für einen Android-Instrumentierungstest ein.

Diese Flags sind für Android-Instrumentierungstests erforderlich:

• Gerät: Geben Sie ein Gerät mit --device an: --device shiba-35
• Test: Geben Sie das Test-APK mit --test an: --test /path/to/test.apk

Führen Sie den Instrumentierungstest mit einem sessions submit instrumentation-Befehl aus, der in etwa so aussieht, wobei Sie Ihre eigenen Geräte-IDs und den Testpfad verwenden:

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

Der Ordner mit dem Ergebnisbericht des Jobs befindet sich in einem Cloud Storage-Pfad wie gs://BUCKET_NAME/automation/sessions/SESSION_ID/. In der Befehlsausgabe finden Sie den Link, der in etwa so aussieht: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Schritt 4: Sharding verwenden

Wenn Sie Developer Device Platform-Instrumentierungstests in einen CI/CD-Workflow (Continuous Integration/Continuous Delivery) einbinden möchten, sollten Sie Ihre Tests fragmentieren. Beim Test-Sharding wird eine Reihe von Instrumentierungstests in Untergruppen (Shards) aufgeteilt, 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.

Achtung: Sharding-Tests können mehr kosten. Durch das Test-Sharding wird zwar die Zeit verkürzt, die für die Ausführung aller Tests benötigt wird, aber der Aufwand für das Starten der App auf jedem Shard kann die Zeiten für einzelne Geräte erhöhen.

Schritt 4.1: Fragmentierungsoption auswählen

Wenn Ihre Jobs nur eine kleine Anzahl von Testläufen haben oder die Gesamtausführungszeit aller Testläufe nicht lang ist, ist die Verwendung von Fragmentierung nicht erforderlich. 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 fragmentieren, die folgenden Optionen:

• Wenn alle Testfälle ähnlich lange dauern, verwenden Sie ein einheitliches Sharding, indem Sie alle Testfälle in n Shards aufteilen.

• Wenn die Ausführungszeit verschiedener Testfälle stark variiert, verwenden Sie Smart Sharding. Die Developer Device Platform verwendet die bisherige Testausführungszeit, um verschiedene Shards zu erstellen, und versucht, alle Shards in einer ähnlichen Zeit abzuschließen.

Hinweis: Die Anzahl der Shards ist konfigurierbar. Wenn die Developer Device Platform viele Shards parallel ausführt, kann es bei Testläufen zu Engpässen bei der Verfügbarkeit von Geräten kommen. Daher empfehlen wir, dass die Anzahl der im Flag --device angegebenen Geräte kleiner oder gleich der Anzahl der Shards ist.

Einheitliche Fragmentierung

Wenn Sie Ihre Tests mit einheitlichem Sharding aufteilen möchten, fügen Sie die Flags --sharding-option=uniform und --uniform-sharding-count= in den 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

Es sollte eine Ausgabe mit Job status: 2 running angezeigt werden. Der Dienst erstellt zwei Jobs, einen für jedes Gerät. Da die Eingaben für beide Jobs identisch sind, werden die Validierungen vom Dienst zentralisiert und nur einmal ausgeführt.

Die beiden Jobs werden in der endgültigen Ausgabe des Befehls 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 Smart Sharding fragmentieren möchten, fügen Sie die Flags --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (in Minuten oder 1h) und --smart-sharding-record-name= in den 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 zeigen, dass drei Jobs ausgeführt wurden:

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 von Shards an, die für Smart Sharding erstellt werden sollen. Wenn nicht festgelegt oder auf 0 gesetzt, werden systemdefinierte Höchstgrenzen 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 Smart 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 Smart Sharding-Eintragsdatei ohne Dateiendung an. Erforderlich, wenn „--sharding-option=smart“. Diese YAML-Datei befindet sich im Storage-Bucket Google Cloud, der durch --bucket-name im Verzeichnis smart-sharding/ angegeben ist. 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 für den asynchronen als auch für den synchronen Modus des Befehls sessions submit instrumentation können Sie den Befehl sessions describe verwenden, um den Jobstatus während der Ausführung abzufragen oder das Ergebnis nach Abschluss abzurufen:

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, die in etwa so aussieht:

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 Standard-Flag-Optionen der Google Cloud CLI. Beispiel:

gcloud beta device-run sessions list --limit 5

Das Ergebnis sieht in etwa 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

Oder führen Sie den folgenden Befehl aus, um alle laufenden Sitzungen aufzulisten:

gcloud beta device-run sessions list --filter RUNNING

Wenn Sie laufende Sitzungen haben, sehen Sie Ergebnisse, die in etwa so aussehen:

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

Andernfalls erhalten Sie 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 ist. Der Abbruch erfolgt asynchron im Backend.

Wenn die Sitzung bereits beendet ist, wird nur der aktuelle Status ausgegeben. Wenn Sie den Abbruch einer abgeschlossenen Sitzung anfordern, ist dies kein Fehler.

Nächste Schritte

Als Nächstes können Sie eine ausführbare Android-Datei ausführen oder Logs suchen und analysieren.