Developer Device Platform Device Run für iOS

Vorschau

Dieses Produkt oder Feature unterliegt den "Nutzungsbedingungen für Pre-GA-Angebote" 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. 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 Flags sowie die Migrationsanleitung für KI-Agenten.

Um die device-run-Befehlszeile zu verwenden, 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 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. Ihre Tests kompiliert und in einer ZIP-Datei verpackt.

Schritt 1: Testlauf konfigurieren

Tipp: Wenn Sie alle verfügbaren Optionen für den Befehl submit xctest aufrufen möchten, führen Sie gcloud alpha device-run sessions submit xctest --help aus.

Sie können die Testausführung mit den folgenden optionalen Flags anpassen. Mindestens eine Instanz des Flags --device ist jedoch 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 vor dem Starten des Tests ein oder mehrere zusätzliche .ipa-Pakete mit --additional-apps: --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 über die Befehlszeile direkt auf unterstützte Xcode-Versionen mit dem --xcode-version Flag zu, z. B.: --xcode-version=xcode-16-4
• Testzeitlimit: Begrenzen Sie die Ausführungsdauer: --xctest-timeout=10m (der gültige Bereich liegt zwischen 1m und 1h, der Standardwert ist 5m).
• Labels: Fügen Sie der Sitzung benutzerdefinierte Metadaten hinzu: --labels=env=staging,owner=my-team
• Locale: Legen Sie das Geräte-Locale fest: --locale=en-US
• Dateien auf das Gerät übertragen: Übertragen Sie Dateien vor der Testausführung in den App-Datencontainer: Ausführung: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Dateien vom Gerät abrufen: Rufen Sie nach der Testausführung Dateien aus dem App-Datencontainer ab: --paths-to-pull=com.example.app:/Documents/output.txt
• Wiederholungen bei instabilen Tests: Legen Sie die maximale Anzahl der Versuche 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 (Standardwert: PROJECT_ID-devicerun).
• Da das Hochladen großer ZIP- oder IPA-Dateien zeitaufwendig sein kann, können Sie direkt auf Ihre Dateien verweisen, indem Sie die gs://-Pfade in Cloud Storage verwenden, um Zeit zu sparen.

Synchrone und asynchrone Ausführungen

Standardmäßig ist der Befehl „submit“ blockierend (synchron). Er wartet, bis der Test abgeschlossen ist, und gibt eine Zusammenfassung der Ergebnisse in einer Tabelle 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:

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 an, die durch Kommas getrennt sind, oder mit mehreren --device-Flags, die jeweils eine andere 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 Ihres 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

Suchen 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

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

gcloud alpha device-run software-versions describe xcode-16-4

Sie erhalten eine Ausgabe wie diese:

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:

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. Die vollständige Liste der verfügbaren Geräte finden Sie entweder im interaktiven Geräte Verzeichnis oder durch Ausführen von:

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äte verzeichnis erfahren Sie, wie Sie diese Liste filtern. Wenn Sie ein bestimmtes Gerät für die Testausführung verwenden möchten, geben Sie die entsprechende ID (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, signieren, die Codesignaturen prüfen und die resultierenden Artefakte in einer ZIP-Datei verpacken, die Ihre .xctestrun-Konfiguration und die Test-Bundles der Anwendung enthält.

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

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 Codesignierung in Xcode sowohl für das App-Ziel als auch für das Test-Runner-Ziel richtig konfiguriert ist (geben Sie ein gültiges Bereitstellungsprofil und eine gültige Entwickleridentität an).

2. Erstellen Sie die Tests mit Xcode (Product > Build For > Testing) oder mit xcodebuild.

   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 Geräte-UDIDs von Device Run nicht in Ihrem Apple Developer-Entwicklerkonto registrieren. Die Developer Device Platform signiert Ihre Anwendungs- und Test-Bundles mit einem Bereitstellungsprofil für das Testlabor neu, bevor sie auf dem physischen Gerät installiert werden. Daher sind nur ein gültiges lokales Entwicklungszertifikat und ein gültiges Bereitstellungsprofil erforderlich, um die Build- und Verpackungsschritte abzuschließen.

2. Build-Produkte und Signaturen prüfen

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

1. App-Bundle prüfen:

   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. In der Anwendung gehostete Unit-Tests 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 Ordner mit den Build-Ausgabeprodukten 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 mit den Build-Produkten aus:

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

Dadurch wird die verpackte Datei MyTests.zip erstellt, die 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 Ihren XCTest auszuführen. Sie müssen die im vorherigen Schritt kompilierte ZIP-Datei für den Test (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, werden in der Befehlszeile die erstellte Sitzungs-ID und das Cloud Storage-Ziel angezeigt, 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 diesen Befehlen können Sie aktive Ausführungen verfolgen und frühere Sitzungen verwalten:

• Sitzung beschreiben: Fragen Sie den Live-Fortschritt oder die Endergebnisse einer Sitzung ab: gcloud alpha device-run sessions describe SESSION_ID Fügen Sie --full hinzu, um vollständige Details einschließlich Gerätezuweisungen, Ausführungs-IDs und Cloud Storage-Artefaktpfaden aufzurufen.
• Sitzungen auflisten: Rufen Sie Ihre letzten Ausführungen auf: gcloud alpha device-run sessions list --limit=10
• Sitzung abbrechen: Beenden Sie eine laufende Testsitzung: gcloud alpha device-run sessions cancel SESSION_ID
• Vorgang abbrechen: Beenden Sie einen ausstehenden oder aktiven Vorgang: gcloud alpha device-run operations cancel OPERATION_ID

Nächste Schritte

Als Nächstes müssen Sie Logs suchen und analysieren.