Developer Device Platform Device Run für iOS

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 iOS-XCTest mit der gcloud alpha 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 Migrations-Skill für KI-Agenten.

Wenn Sie die device-run-Befehlszeile verwenden möchten, müssen Sie Ihre Google Cloud-Projekt-ID angeben. Eine Zusammenfassung der Befehle finden Sie unter gcloud alpha 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. Sie haben Ihre Tests kompiliert und in einer ZIP-Datei verpackt.

Schritt 1: Testlauf konfigurieren

Tipp: Mit dem Befehl gcloud alpha device-run sessions submit xctest --help können Sie alle verfügbaren Optionen für den Befehl submit xctest aufrufen.

Sie können die Testausführung mit den folgenden optionalen Flags anpassen. Es ist jedoch mindestens eine Instanz des Flags --device erforderlich:

• Mehrere Geräte: Geben Sie das Flag --device mehrmals an, um denselben Test gleichzeitig auf mehreren Geräten auszuführen: --device iphonese3-18-4 --device iphonese3-26-3 oder --device iphonese3-18-4,iphonese3-26-3.
• Zusätzliche Apps: Installieren Sie ein oder mehrere zusätzliche .ipa-Pakete, bevor Sie den Test mit --additional-apps starten: --additional-apps=/path/to/AdditionalApp.ipa
• Benutzerdefinierte .xctestrun-Datei: Übergeben Sie eine benutzerdefinierte Konfigurationsdatei mit --xctestrun-file: --xctestrun-file=/path/to/CustomTests.xctestrun
• Apple Xcode-Versionen: Greifen Sie mit dem Flag --xcode-version direkt über die Befehlszeile auf unterstützte Xcode-Versionen zu, z. B.: --xcode-version=xcode-16-4
• Testzeitlimit: Begrenzen Sie die Ausführungsdauer: --xctest-timeout=10m (gültiger Bereich ist 1m bis 1h, Standardwert ist 5m).
• Labels: Hängen Sie benutzerdefinierte Metadaten an die Sitzung an: --labels=env=staging,owner=my-team
• Sprache: Legen Sie die Sprache des Geräts fest: --locale=en-US
• Dateien auf das Gerät übertragen: Übertragen Sie Dateien vor der Testausführung in den App-Datencontainer: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Dateien vom Gerät abrufen: Dateien nach der Testausführung aus dem App-Datencontainer abrufen: --paths-to-pull=com.example.app:/Documents/output.txt
• Wiederholungen instabiler Tests: Legen Sie die maximale Anzahl von Versuchen fest, instabile Tests noch einmal auszuführen: --flaky-test-attempts=3 (Standardwert: 1 Versuch).
• Benutzerdefinierter Cloud Storage-Bucket: Geben Sie einen benutzerdefinierten Cloud Storage-Bucket für Ein- und Ausgaben an: --bucket-name=my-custom-bucket (Standard ist PROJECT_ID-devicerun).
• Da das Hochladen großer ZIP- oder IPA-Dateien zeitaufwendig sein kann, können Sie Ihre Dateien direkt über ihre Cloud Storage-gs://-Pfade referenzieren, um Uploadzeit zu sparen.

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 alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --async

Dadurch wird sofort eine Sitzungs-ID zurückgegeben. Sie können dann mit dem Befehl sessions wait darauf warten:

gcloud alpha 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 --device-Flags an, die jeweils eine eindeutige Geräte-ID angeben.

Durch Kommas getrennt

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4,iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Mehrere Flags

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --device iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Testzeitlimit

Begrenzen Sie die Ausführungsdauer des Tests:

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xctest-timeout=10m

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

Softwareversionen

Entdecken und verwenden Sie verfügbare Softwarepakete und Versionen von Apple Xcode und prüfen Sie deren Lebenszyklen, unterstützte Versionen und Metadaten, bevor Sie Testläufe konfigurieren.

Listen Sie zuerst alle verfügbaren Softwarepakete und ihre Versionen auf:

gcloud alpha 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 alpha device-run software-versions describe xcode-16-4

Die Ausgabe sollte in etwa so aussehen:

id: xcode-16-4
lifecycle:
  state: ACTIVE
name: Xcode 16.4
softwareType: XCODE
supportedIosVersions:

-   '15.0'
-   '15.1'
-   '15.2'
-   '15.4'
-   '15.7'
-   '16.0'
-   '16.1'
-   '16.2'
-   '16.3'
-   '16.5'
-   '16.6'
-   '18.0'
-   '18.3'
-   '18.4'
version: '16.4'

Nachdem Sie nun wissen, welche Softwareversionen verfügbar sind, können Sie sie in Ihren Testläufen mit dem Flag --xcode-version verwenden, z. B.:

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xcode-version=16.4

Schritt 2: Gerätetypen auswählen

Mit der device-run-Befehlszeile können iOS-Tests auf verfügbaren physischen Geräten ausgeführt werden. Eine vollständige Liste der verfügbaren Geräte finden Sie im interaktiven Gerätekatalog oder mit folgendem Befehl:

gcloud alpha device-run devices list

Beispielausgabe:

ID                MAKE   NAME           MODEL        HARDWARE_TYPE  OS_VERSION  CAPACITY  AVAILABILITY  PRODUCTS
iphonese3-18-4    Apple  iPhone SE 3             iphonese3    PHYSICAL       18.4        NONE      NONE          Automation
iphonese3-26-3    Apple  iPhone SE 3             iphonese3    PHYSICAL       26.3        NONE      NONE          Automation

Im Gerätekatalog erfährst du, wie du diese Liste filtern kannst. Wenn Sie ein bestimmtes Gerät für die Testausführung verwenden möchten, geben Sie die entsprechende ID an (z. B. iphonese3-18-4) im Befehl „submit“ an.

Schritt 3: XCTest vorbereiten und verpacken

Bevor Sie Ihre Tests ausführen, müssen Sie sie kompilieren, dafür sorgen, dass sie signiert sind, die Codesignaturen prüfen und die resultierenden Artefakte in einer ZIP-Datei verpacken, die Ihre .xctestrun-Konfiguration und die Anwendungstest-Bundles enthält.

Tipp: Migrieren Sie von Firebase Test Lab? Device Run akzeptiert dasselbe Testpaket wie Firebase Test Lab: das Verzeichnis Debug-iphoneos/ und die Datei .xctestrun aus Build/Products, wie unter XCTest ausführen beschrieben. Wenn Sie bereits eine Build- und Paketierungspipeline für Firebase Test Lab haben, können Sie diese unverändert wiederverwenden und die resultierende .zip an --test übergeben. Informationen zum Rest der Migration finden Sie im iOS-Abschnitt von Flag- und Befehlsübersetzung.

1. Tests für physische iOS-Geräte erstellen

Öffnen Sie Ihr Projekt in Xcode und erstellen Sie Ihre App und Testziele für Tests:

1. Achten Sie darauf, dass die Codesignatur in Xcode sowohl für das App-Ziel als auch für das Test-Runner-Ziel richtig konfiguriert ist (mit einem gültigen Bereitstellungsprofil und einer gültigen Entwickleridentität).

2. Erstellen Sie mit Xcode (Product > Build For > Testing) oder mit xcodebuild einen Build für Tests.

   Für einen Arbeitsbereich:

   xcodebuild build-for-testing \
     -workspace YourProject.xcworkspace \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

   Für ein eigenständiges Projekt:

   xcodebuild build-for-testing \
     -project YourProject.xcodeproj \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

Dadurch werden die Build-Produkte unter ./build/Build/Products generiert.

Hinweis: Sie müssen die UDIDs der Device Run-Geräte nicht in Ihrem Apple-Entwicklerkonto registrieren. Die Developer Device Platform signiert Ihre Anwendung und Test-Bundles mit einem Lab-Bereitstellungsprofil neu, bevor sie auf dem physischen Gerät installiert werden. Daher sind nur ein gültiges lokales Entwicklungszertifikat und ein Bereitstellungsprofil erforderlich, um die Build- und Paketierungsschritte abzuschließen.

2. Build-Produkte und Signaturen prüfen

Prüfen Sie nach dem Erstellen, ob die Anwendung, der Runner und das Manifest .xctestrun unter ./build/Build/Products/ generiert wurden. Wenn die Signatur lokal erfolgt, können Sie Bundle-Signaturen mit codesign prüfen:

1. Überprüfen Sie das App-Bundle:

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp.app
   

   Erwartete Ausgabe: YourApp.app: valid on disk

2. Wenn Sie einen XCUITest ausführen, prüfen Sie auch das Test-Runner-Bundle:

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp-Runner.app
   

   Erwartete Ausgabe: YourApp-Runner.app: valid on disk

Hinweis: Ein separates YourApp-Runner.app-Bundle wird nur für UI-Testziele (XCUITest) erstellt. Anwendungshost-Unittests sind stattdessen in die Host-App eingebettet und werden durch die Überprüfung von YourApp.app abgedeckt.

3. ZIP-Archiv erstellen

Komprimieren Sie sowohl das Verzeichnis Debug-iphoneos als auch die Datei .xctestrun im Ausgabeordner des Builds in ein einzelnes ZIP-Archiv.

Achtung: Das Verzeichnis „Debug-iphoneos/“ und die Datei „.xctestrun“ müssen sich direkt im Stammverzeichnis des ZIP-Archivs befinden. Komprimieren Sie NICHT den äußeren Ordner „Products/“ oder „build/“.

Führen Sie den folgenden Befehl im Verzeichnis der Build-Produkte aus:

cd ./build/Build/Products
zip -r MyTests.zip Debug-iphoneos *.xctestrun

Dadurch wird das gepackte MyTests.zip erstellt, das mit dem Flag --test verwendet werden kann.

Schritt 4: XCTest ausführen

Diese Flags sind erforderlich:

• Gerät: Geben Sie ein Gerät mit --device an: --device iphonese3-18-4
• Test: Geben Sie die ZIP-Datei für den Test mit --test an: --test ./MyTests.zip

Verwenden Sie den Befehl gcloud alpha device-run sessions submit xctest, um den XCTest auszuführen. Sie müssen die im vorherigen Schritt kompilierte ZIP-Testdatei (MyTests.zip) angeben.

So führen Sie eine einfache Testsitzung aus:

gcloud alpha device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./MyTests.zip

Wenn die Ausführung beginnt, zeigt die Befehlszeile die erstellte Sitzungs-ID und das Cloud Storage-Ziel an, in dem die Ergebnisse gespeichert werden:

Creating session [session-ee78b0ed] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/session-ee78b0ed/].

Waiting for session [session-ee78b0ed] to complete....

Schritt 5: Testlauf ansehen und verwalten

Mit den folgenden Befehlen können Sie aktive Ausführungen verfolgen und frühere Sitzungen verwalten:

• Sitzung beschreiben: Fragen Sie den aktuellen Fortschritt oder die Endergebnisse einer Sitzung ab: gcloud alpha device-run sessions describe SESSION_ID Fügen Sie --full hinzu, um vollständige Details wie Gerätezuweisungen, Ausführungs-IDs und Cloud Storage-Artefaktpfade aufzurufen.
• Sitzungen auflisten: Letzte Ausführungen ansehen: gcloud alpha device-run sessions list --limit=10
• Sitzung abbrechen: Laufende Testsitzung beenden: gcloud alpha device-run sessions cancel SESSION_ID
• Vorgang abbrechen: Ausstehenden oder aktiven Vorgang beenden: gcloud alpha device-run operations cancel OPERATION_ID

Nächste Schritte

Als Nächstes Logs suchen und analysieren.