Screenshots aufnehmen

Erfassen Sie App Store Screenshots direkt von iOS/iPadOS-Simulatoren mithilfe von UI-Tests. Ersetzt fastlane snapshot.

Schnellstart

ascelerate screenshot init                  # Create config and helper in ascelerate/
ascelerate screenshot                       # Capture screenshots

Mit einem KI-Coding-Agenten einrichten

Für die Aufnahme braucht es ein UI-Test-Target, den Screenshot-Helper, einen Screenshot-Modus mit Demo-Inhalten in der App, die Tests selbst und die Konfiguration. Ein Coding-Agent kann all das einrichten:

ascelerate screenshot setup-prompt          # Print the setup instructions
ascelerate screenshot setup-prompt --copy   # Copy them to the clipboard

Fügen Sie die Anleitung in einen Coding-Agenten ein, der im Projekt arbeitet (Claude Code, Codex, Cursor, der Coding-Assistent von Xcode …). Sie geht von dem aus, was das Projekt schon hat (Projekte, Schemes, UI-Test-Targets, Lokalisierungen, Konfiguration, Helper-Version, installierte Simulatoren), ein erneuter Aufruf zeigt also, was noch fehlt. Sie behandelt auch Geräterahmen, die Sie selbst aus Apples Design Resources (Product Bezels) herunterladen.

--design gibt stattdessen die Anleitung für einen Design-Generator aus: eine kleine Web-App in app-store-screenshots/, die die gerahmten Screenshots in App Store-Bilder mit Überschriften in jeder Sprache verwandelt und für ascelerate apps media upload exportiert (siehe Medien).

Befehle

Ausführen

ascelerate screenshot                       # Capture screenshots
ascelerate screenshot run                   # Same as above
ascelerate screenshot --json-events         # Progress as JSON Lines events on stdout

Verwendet immer ascelerate/screenshot.yml im aktuellen Verzeichnis.

--json-events ist für andere Tools gedacht, die einen Lauf verfolgen: stdout enthält ein JSON-Objekt pro Zeile (start, build, language, device mit Schritten wie testing, passed, failed und collected sowie finished mit allen Ergebnissen), der lesbare Fortschritt wandert nach stderr.

Initialisieren

ascelerate screenshot init

Erstellt sowohl ascelerate/screenshot.yml als auch ascelerate/ScreenshotHelper.swift im Verzeichnis ascelerate/. Fragt vor dem Schreiben um Bestätigung (-y überspringt sie). Überschreibt keine bestehenden Dateien.

Helper erstellen

ascelerate screenshot create-helper         # Generates ScreenshotHelper.swift
ascelerate screenshot create-helper -o CustomHelper.swift
ascelerate screenshot create-helper -o UITests/ScreenshotHelper.swift -y   # Overwrite without asking

Rahmen

ascelerate screenshot frame                    # Frame screenshots with device bezels

Rahmt aufgenommene Screenshots mit Geräterahmen-Bildern. Verwendet die frameDevice- und deviceBezel-Einstellungen aus der Konfiguration. Kann nach der Aufnahme unabhängig ausgeführt werden.

Diagnose

ascelerate screenshot doctor                   # Check config and environment
ascelerate screenshot doctor --json            # The same as JSON

Überprüft die Screenshot-Konfiguration und Umgebung: Konfigurationsdatei, Projekt-/Workspace-Existenz, xcodebuild- und simctl-Verfügbarkeit, Simulatorgeräte, Helper-Dateiversion, Geräterahmen-Dateien und Ausgabeverzeichnisse. Zeigt eine Checkliste mit Bestanden/Fehlgeschlagen/Warnung-Indikatoren. Mit --json gibt er die Konfiguration (Scheme, Geräte, Sprachen, Ausgabeverzeichnis) und jede Prüfung mit ihrem Status (pass, warn oder fail) aus.

Konfiguration (ascelerate/screenshot.yml)

workspace: MyApp.xcworkspace
# project: MyApp.xcodeproj               # Use project instead of workspace
scheme: AppUITests
devices:
  - simulator: iPhone 17 Pro Max
    # frameDevice: true
    # deviceBezel: ./bezels/iPhone 17 Pro Max.png
  - simulator: iPad Pro 13-inch (M5)
    # frameDevice: true
    # deviceBezel: ./bezels/iPad Pro 13-inch (M5).png
languages:
  - en-US
  - de-DE
outputDirectory: ./screenshots
# framedOutputDirectory: ./screenshots/framed
clearPreviousScreenshots: true
eraseSimulator: false
localizeSimulator: true
overrideStatusBar: true
darkMode: false
disableAnimations: true
waitAfterBoot: 0
# waitAfterEraseAndReboot: 30           # Zusätzliches Warten auf Erstausführungs-Systemwarnungen
# statusBarArguments: "--time '9:41' --dataNetwork wifi"
# testWithoutBuilding: true               # Skip build, use existing xctestrun
# cleanBuild: false
# headless: false                         # Don't open simulator windows (DeviceHub / Simulator.app)
# helperPath: AppUITests/ScreenshotHelper.swift
# launchArguments:
#   - -ui_testing
# configuration: Debug                    # Build configuration
# testplan: MyTestPlan                    # Xcode test plan name
# numberOfRetries: 0                     # Retry failed languages (erase + reboot simulator)
# stopAfterFirstError: false             # Stop all devices on first failure
# reinstallApp: false                    # Delete and reinstall app before tests
# disableAssetDownloads: false           # mobileassetd deaktivieren (keine Siri-/Tastatur-/ML-Asset-Downloads; blockiert auch On-Device-ML-Assets)
# xcargs: SWIFT_ACTIVE_COMPILATION_CONDITIONS=SCREENSHOTS

Verwendung in UITests

Fügen Sie ScreenshotHelper.swift zu Ihrem UITest-Target hinzu:

override func setUp() {
    setupScreenshots(app)
    app.launch()
}

func testScreenshots() {
    screenshot("01-home")
    app.buttons["Settings"].tap()
    screenshot("02-settings")
}

Ihre App kann den Screenshot-Modus erkennen:

if ProcessInfo.processInfo.arguments.contains("-ASC_SCREENSHOT") {
    // Show demo data, hide debug UI, etc.
}

Der Helper bietet auch disableAnimationsIfNeeded(), um Animationen zu deaktivieren, wenn disableAnimations in der Konfiguration aktiviert ist:

override func setUp() {
    setupScreenshots(app)
    disableAnimationsIfNeeded()
    app.launch()
}

iPhone Duo

Im iPhone-Duo-Simulator (Xcode 27.1+) klappt setHinge(.open) das Gerät auf und setHinge(.closed) zu. Anschließend wartet der Helper, bis das System die App auf das passende Display verschoben hat, sodass der nächste screenshot()-Aufruf dieses Display erfasst. Der Simulator startet immer zugeklappt.

func testScreenshots() {
    screenshot("01-folded")
    setHinge(.open)
    screenshot("02-unfolded")
}

Aufgeklappt verwenden viele Apps dasselbe Layout wie auf dem iPad, doch UIDevice.current.userInterfaceIdiom meldet im Test-Runner weiterhin .phone. Um in Ihren Tests den passenden Codepfad zu wählen, prüfen Sie stattdessen ProcessInfo.processInfo.environment["SIMULATOR_MODEL_IDENTIFIER"] == "iPhone19,4".

vorsicht

Für das Scharnier gibt es keine offizielle API. Der Helper sendet dasselbe Eingabeereignis wie der Scharnier-Schieberegler in Device Hub, daher kann eine künftige Xcode-Version diese Funktion unbrauchbar machen.

Funktionsweise

1. Baut einmal mit build-for-testing (oder überspringt, wenn testWithoutBuilding: true)
2. Für jede Sprache: startet alle Simulatoren, unterdrückt das iOS-26-Banner „Bereit für Apple Intelligence“ (und mobileassetd, wenn disableAssetDownloads gesetzt ist), lokalisiert, überschreibt die Statusleiste
3. Führt Tests parallel auf allen Geräten aus
4. Wenn numberOfRetries gesetzt ist und ein Gerät fehlschlägt: setzt fehlgeschlagene Simulatoren zurück, lokalisiert neu, startet neu und wiederholt die Tests
5. Sammelt Screenshots aus dem gerätespezifischen Cache ins Ausgabeverzeichnis
6. Rahmt Screenshots mit Geräterahmen (wenn frameDevice aktiviert ist)
7. Fehler werden übersprungen — Fehlerprotokolle werden in der Ausgabe gespeichert

Ausgabe

screenshots/
├── en-US/
│   ├── iPhone 17 Pro Max-01-home.png
│   ├── iPhone 17 Pro Max-02-settings.png
│   └── iPad Pro 13-inch (M5)-01-home.png
└── de-DE/
    └── ...

Geräterahmen

Rahmen Sie aufgenommene Screenshots mit Apple-Geräterahmen.

info

Geräterahmen sind nicht in ascelerate enthalten — laden Sie sie von Apple Product Bezels herunter (Apple Developer Account erforderlich). Der Download ist eine DMG-Datei mit PNG-Rahmen für alle aktuellen Geräte.

Einrichtung

1. Laden Sie die Product Bezels DMG von Apple Design Resources herunter
2. Extrahieren Sie die Rahmen-PNG-Dateien in einen Ordner in Ihrem Projekt (z.B. ./bezels/)
3. Aktivieren Sie das Rahmen pro Gerät in der Konfiguration:

devices:
  - simulator: iPhone 17 Pro Max
    frameDevice: true
    deviceBezel: ./bezels/iPhone 17 Pro Max.png
  - simulator: iPad Pro 13-inch (M5)
    frameDevice: false

Ein Gerät kann mehrere Geräterahmen auflisten. Jeder Screenshot erhält den Rahmen, dessen Bildschirmbereich zu seiner Größe passt. So bekommen die zugeklappten Screenshots eines iPhone Duo den geschlossenen Rahmen und die aufgeklappten den geöffneten:

devices:
  - simulator: iPhone Duo
    frameDevice: true
    deviceBezel:
      - ./bezels/iPhone Duo - Outer Closed Portrait.png
      - ./bezels/iPhone Duo - Inner Open Landscape.png

Querformat-Screenshots verwenden einen Querformat-Rahmen, sofern einer aufgeführt ist, andernfalls den gedrehten Hochformat-Rahmen.

Ausgabe

Gerahmte Screenshots werden im framedOutputDirectory gespeichert (Standard: {outputDirectory}/framed):

screenshots/framed/
├── en-US/
│   └── iPhone 17 Pro Max-01-home.png
└── de-DE/
    └── ...

Nur Geräte mit frameDevice: true werden gerahmt. Das Rahmen erfolgt automatisch nach jeder Sprache während screenshot run oder eigenständig über screenshot frame.

Optionen

Option	Beschreibung
clearPreviousScreenshots	Sprachordner vor dem Sammeln leeren (nur wenn alle Geräte erfolgreich sind)
eraseSimulator	Simulator vor jeder Sprache zurücksetzen
localizeSimulator	Simulator-Sprache/-Locale pro Sprache setzen
overrideStatusBar	Statusleiste überschreiben (9:41, volle Balken, WLAN)
statusBarArguments	Benutzerdefinierte xcrun simctl status_bar-Argumente
darkMode	Dunkelmodus auf Simulatoren aktivieren
disableAnimations	Animationen während Tests deaktivieren
waitAfterBoot	Sekunden nach dem Simulatorstart warten (Standard: 0)
waitAfterEraseAndReboot	Zusätzliche Sekunden, wenn der Simulator in einem frischen Zustand ist — bei der ersten Sprache des Laufs oder wann immer der Simulator gelöscht wurde (über eraseSimulator: true oder einen Wiederholungsversuch). Gibt Erstausführungs-Systemwarnungen Zeit zu erscheinen, bevor Screenshots erstellt werden. (Das iOS-26-Banner „Bereit für Apple Intelligence“ wird automatisch unterdrückt und braucht keine Wartezeit.)
testWithoutBuilding	Build überspringen, vorhandene xctestrun-Datei verwenden
cleanBuild	clean vor dem Bauen ausführen
headless	Simulator-Fenster nicht öffnen (DeviceHub ab Xcode 27, davor Simulator.app)
helperPath	Pfad zu ScreenshotHelper.swift für Versionsprüfung
launchArguments	Zusätzliche Startargumente für die App
configuration	Build-Konfiguration (z.B. Debug, Release)
testplan	Name des Xcode-Testplans
numberOfRetries	Anzahl der Wiederholungsversuche bei fehlgeschlagenen Sprachen — setzt den Simulator zurück, lokalisiert neu, startet neu und führt Tests erneut aus. Nur fehlgeschlagene Geräte werden wiederholt. Wiederholte Ergebnisse werden in der Übersichtstabelle markiert.
stopAfterFirstError	Alle Geräte nach dem ersten Fehler stoppen
reinstallApp	App vor den Tests löschen und neu installieren
disableAssetDownloads	Deaktiviert mobileassetd im Simulator, damit er keine Gigabytes an Siri-, Tastatur- und ML-Assets in frisch gelöschte Simulatoren lädt. Blockiert auch On-Device-ML-Assets, die manche Apps brauchen (z. B. Texterkennung); lassen Sie es daher ausgeschaltet, wenn Ihre Screenshots davon abhängen. Wird bei jeder Vorbereitung erneut angewendet, da ein Löschen die Einstellung zurücksetzt.
xcargs	Zusätzliche Argumente für xcodebuild
frameDevice	Geräterahmen für dieses Gerät aktivieren (pro Gerät)
deviceBezel	Pfad zur Geräterahmen-PNG-Datei oder eine Liste von Pfaden; jeder Screenshot verwendet den Rahmen, der zu seiner Größe passt (pro Gerät)
framedOutputDirectory	Ausgabeverzeichnis für gerahmte Screenshots (Standard: {outputDirectory}/framed)