Ekran Görüntüsü Yakalama

UI testleri kullanarak iOS/iPadOS simülatörlerinden doğrudan App Store ekran görüntüleri yakalayın. fastlane snapshot yerine kullanılır.

Hızlı başlangıç

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

Yapay zeka kodlama ajanıyla kurulum

Yakalama için bir UI test hedefi, ekran görüntüsü helper'ı, uygulamada örnek içerikli bir ekran görüntüsü modu, testlerin kendisi ve yapılandırma gerekir. Bunların hepsini bir kodlama ajanı kurabilir:

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

Talimatları projede çalışan bir kodlama ajanına (Claude Code, Codex, Cursor, Xcode'un kodlama asistanı…) yapıştırın. Talimatlar projede zaten olanlardan (projeler, şemalar, UI test hedefleri, yerelleştirmeler, yapılandırma, helper sürümü, yüklü simülatörler) yola çıkar; komutu yeniden çalıştırmak geriye ne kaldığını gösterir. Cihaz çerçevelerini de kapsar: çerçeveleri Apple'ın tasarım kaynakları sayfasından (Product Bezels) kendiniz indirirsiniz.

--design bunun yerine bir tasarım oluşturucunun talimatlarını yazdırır: app-store-screenshots/ klasöründe, çerçevelenmiş ekran görüntülerini her dilde başlıklı App Store görsellerine dönüştüren ve ascelerate apps media upload için dışa aktaran küçük bir web uygulaması (bkz. Medya).

Komutlar

Çalıştırma

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

Her zaman mevcut dizindeki ascelerate/screenshot.yml dosyasını kullanır.

--json-events, bir çalıştırmayı izleyen diğer araçlar içindir: stdout her satırda bir JSON nesnesi taşır (start, build, language, testing, passed, failed ve collected gibi adımlarıyla device ve tüm sonuçlarıyla finished), okunabilir ilerleme ise stderr'e geçer.

Başlatma

ascelerate screenshot init

ascelerate/ dizininde hem ascelerate/screenshot.yml hem de ascelerate/ScreenshotHelper.swift dosyalarını oluşturur. Yazmadan önce onay ister (-y onayı atlar). Mevcut dosyaların üzerine yazmaz.

Helper oluşturma

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

Çerçeveleme

ascelerate screenshot frame                    # Frame screenshots with device bezels

Yakalanan ekran görüntülerini cihaz çerçeve görüntüleri ile çerçeveler. Yapılandırmadaki frameDevice ve deviceBezel ayarlarını kullanır. Ekran görüntüleri yakalandıktan sonra bağımsız olarak çalıştırılabilir.

Doktor

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

Ekran görüntüsü yapılandırmasını ve ortamı doğrular: yapılandırma dosyası, proje/workspace varlığı, xcodebuild ve simctl erişilebilirliği, simülatör cihazları, helper dosya sürümü, cihaz çerçeve dosyaları ve çıktı dizinlerini kontrol eder. Başarılı/başarısız/uyarı göstergeleri ile bir kontrol listesi gösterir. --json ile yapılandırmayı (şema, cihazlar, diller, çıktı dizini) ve her kontrolü durumuyla (pass, warn ya da fail) JSON olarak yazdırır.

Yapılandırma (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           # İlk açılış sistem uyarıları için ek bekleme
# 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'yi devre dışı bırak (Siri/klavye/ML varlık indirmesi yok; cihaz üstü ML varlıklarını da engeller)
# xcargs: SWIFT_ACTIVE_COMPILATION_CONDITIONS=SCREENSHOTS

UITest'lerde kullanım

ScreenshotHelper.swift dosyasını UITest target'ınıza ekleyin:

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

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

Uygulamanız ekran görüntüsü modunu algılayabilir:

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

Helper ayrıca disableAnimationsIfNeeded() fonksiyonunu da sunar; yapılandırmada disableAnimations etkinleştirildiğinde animasyonları devre dışı bırakır:

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

iPhone Duo

iPhone Duo simülatöründe (Xcode 27.1+) setHinge(.open) cihazı açık konuma, setHinge(.closed) ise katlı konuma getirir. Ardından sistemin uygulamayı ilgili ekrana taşımasını bekler; böylece sonraki screenshot() çağrısı o ekranı yakalar. Simülatör her zaman katlı konumda başlar.

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

Açık konumdayken birçok uygulama iPad'deki gibi bir yerleşim kullanır, ancak test runner'daki UIDevice.current.userInterfaceIdiom yine .phone döndürür. Testlerinizde doğru yolu seçmek için ProcessInfo.processInfo.environment["SIMULATOR_MODEL_IDENTIFIER"] == "iPhone19,4" koşulunu kullanın.

uyarı

Menteşe için resmi bir API yoktur. Helper, Device Hub'daki menteşe kaydırıcısıyla aynı giriş olayını gönderir; bu nedenle gelecekteki bir Xcode sürümü bu özelliği bozabilir.

Nasıl çalışır

1. build-for-testing ile bir kez derler (testWithoutBuilding: true ise atlar)
2. Her dil için: tüm simülatörleri başlatır, iOS 26'daki "Apple Intelligence için hazır" afişini (ve disableAssetDownloads ayarlıysa mobileassetd servisini) susturur, yerelleştirir, durum çubuğunu değiştirir
3. Tüm cihazlarda testleri eş zamanlı çalıştırır
4. numberOfRetries ayarlıysa ve herhangi bir cihaz başarısız olursa: başarısız simülatörleri sıfırlar, yeniden yerelleştirir, yeniden başlatır ve tekrar dener
5. Cihaz bazlı önbellekten çıktı dizinine ekran görüntülerini toplar
6. Ekran görüntülerini cihaz çerçeveleri ile çerçeveler (frameDevice etkinse)
7. Hatalar atlanır ve devam edilir; hata günlükleri çıktıya kaydedilir

Çıktı

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/
    └── ...

Cihaz çerçeveleme

Apple cihaz çerçeveleri ile yakalanan ekran görüntülerini çerçeveleyin.

bilgi

Cihaz çerçeveleri ascelerate ile birlikte gelmez; Apple Product Bezels sayfasından indirin (Apple Developer hesabı gereklidir). İndirme, tüm güncel cihazlar için PNG çerçeveler içeren bir DMG dosyasıdır.

Kurulum

1. Apple Design Resources sayfasından Product Bezels DMG dosyasını indirin
2. Çerçeve PNG dosyalarını projenizde bir klasöre çıkarın (örn. ./bezels/)
3. Yapılandırmada her cihaz için çerçevelemeyi etkinleştirin:

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

Bir cihaz için birden fazla çerçeve listelenebilir. Her ekran görüntüsü, ekran alanı kendi boyutuyla eşleşen çerçeveye yerleştirilir; böylece iPhone Duo'nun katlı konumdaki ekran görüntüleri katlı çerçeveyi, açık konumdakiler ise açık çerçeveyi alır:

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

Yatay ekran görüntüleri, listede yatay bir çerçeve varsa onu, yoksa döndürülmüş dikey çerçeveyi kullanır.

Çıktı

Çerçevelenmiş ekran görüntüleri framedOutputDirectory dizinine kaydedilir (varsayılan: {outputDirectory}/framed):

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

Yalnızca frameDevice: true olan cihazlar çerçevelenir. Çerçeveleme, screenshot run sırasında her dilden sonra otomatik olarak çalışır veya screenshot frame ile bağımsız olarak çalıştırılabilir.

Seçenekler

Seçenek	Açıklama
clearPreviousScreenshots	Toplamadan önce dil klasörünü temizle (yalnızca tüm cihazlar başarılı olursa)
eraseSimulator	Her dilden önce simülatörü sıfırla
localizeSimulator	Her dil için simülatör dilini/locale'ini ayarla
overrideStatusBar	Durum çubuğunu değiştir (9:41, tam çubuklar, Wi-Fi)
statusBarArguments	Özel xcrun simctl status_bar argümanları
darkMode	Simülatörlerde karanlık modu etkinleştir
disableAnimations	Testler sırasında animasyonları devre dışı bırak
waitAfterBoot	Simülatör başlatıldıktan sonra beklenecek saniye (varsayılan: 0)
waitAfterEraseAndReboot	Simülatör taze durumdayken beklenecek ek saniye; çalıştırmanın ilk dilinde veya simülatör silindiğinde (eraseSimulator: true veya yeniden deneme yoluyla) geçerlidir. İlk açılış sistem uyarılarına ekran görüntüleri çekilmeden önce görünme zamanı verir. (iOS 26'daki "Apple Intelligence için hazır" afişi otomatik olarak susturulur; bunun için beklemeye gerek yoktur.)
testWithoutBuilding	Derlemeyi atla, mevcut xctestrun dosyasını kullan
cleanBuild	Derlemeden önce clean çalıştır
headless	Simülatör pencerelerini açma (Xcode 27'de DeviceHub, öncesinde Simulator.app)
helperPath	Versiyon kontrolü için ScreenshotHelper.swift yolu
launchArguments	Uygulamaya aktarılan ek başlatma argümanları
configuration	Derleme yapılandırması (örn. Debug, Release)
testplan	Xcode test planı adı
numberOfRetries	Başarısız diller için tekrar deneme sayısı. Her deneme simülatörü sıfırlar, yeniden yerelleştirir, yeniden başlatır ve testleri tekrar çalıştırır. Yalnızca başarısız cihazları tekrar dener. Tekrar denenen sonuçlar özet tablosunda işaretlenir.
stopAfterFirstError	İlk hatadan sonra tüm cihazları durdur
reinstallApp	Testlerden önce uygulamayı silip yeniden yükle
disableAssetDownloads	Simülatörün mobileassetd servisini devre dışı bırakır; böylece yeni silinmiş simülatörlere gigabaytlarca Siri, klavye ve ML varlığı indirilmez. Bazı uygulamaların ihtiyaç duyduğu cihaz üstü ML varlıklarını da (örn. metin tanıma) engeller; ekran görüntüleriniz bunlara bağlıysa kapalı bırakın. Silme işlemi ayarı sıfırladığından her hazırlıkta yeniden uygulanır.
xcargs	xcodebuild'e aktarılan ek argümanlar
frameDevice	Bu cihaz için çerçevelemeyi etkinleştir (cihaz başına)
deviceBezel	Cihaz çerçeve PNG dosyasının yolu ya da yollardan oluşan bir liste; her ekran görüntüsü boyutuna uyan çerçeveyi kullanır (cihaz başına)
framedOutputDirectory	Çerçevelenmiş ekran görüntüleri için çıktı dizini (varsayılan: {outputDirectory}/framed)