Snapshot

Automated App Store Screenshots

Set up Fastlane Snapshot to automatically capture App Store screenshots across multiple devices and languages.

Pre-flight Checks

• Fastlane installed: !fastlane --version 2>/dev/null | grep "fastlane " | head -1 || echo "✗ Not installed - run: brew install fastlane"
• Fastfile exists: !ls fastlane/Fastfile 2>/dev/null && echo "✓ Found" || echo "✗ Not found - run /setup-fastlane first"
• Existing Snapfile: !ls fastlane/Snapfile 2>/dev/null && echo "✓ Already configured" || echo "○ Not configured yet"
• UI Test target: !find . -maxdepth 3 -name "*UITests*" -type d 2>/dev/null | head -1 || echo "○ No UI test target found"
• Simulators available: !xcrun simctl list devices available | grep -E "iPhone|iPad" | head -3

Arguments: ${ARGUMENTS:-setup}

Why Automate Screenshots?

App Store requires screenshots for multiple device sizes. Manual capture means:

• 5+ device sizes × 5+ screenshots × N languages = hours of work
• Risk of inconsistency between screenshots
• Repeat everything for each app update

Snapshot automates this: run once, get all screenshots.

Step 1: Initialize Snapshot

fastlane snapshot init

This creates:

• fastlane/Snapfile - Configuration file
• fastlane/SnapshotHelper.swift - Helper for UI tests

Step 2: Configure Snapfile

Edit fastlane/Snapfile:

# Devices to capture (App Store requirements)
devices([
  "iPhone 15 Pro Max",      # 6.7" display (required)
  "iPhone 15 Pro",          # 6.1" display
  "iPhone SE (3rd generation)", # 4.7" display (if supporting older phones)
  "iPad Pro 13-inch (M4)",  # iPad screenshots (if universal app)
])

# Languages to capture
languages([
  "en-US",
  # "ja",      # Japanese
  # "de-DE",   # German
  # "fr-FR",   # French
  # "es-ES",   # Spanish
])

# UI Test scheme
scheme("YourAppUITests")

# Output directory
output_directory("./fastlane/screenshots")

# Clear old screenshots before capture
clear_previous_screenshots(true)

# Stop on first error (set false to continue despite failures)
stop_after_first_error(true)

# Dark mode variants (iOS 13+)
# dark_mode(true)

# Workspace or project (uncomment one)
# workspace("YourApp.xcworkspace")
# project("YourApp.xcodeproj")

Step 3: Add SnapshotHelper to UI Tests

1. Add SnapshotHelper.swift to your UI test target:

   • Drag fastlane/SnapshotHelper.swift into Xcode
   • Ensure it's added to your UITests target (not main app)

2. Import and configure in your UI test file:

import XCTest

class ScreenshotTests: XCTestCase {

    override func setUpWithError() throws {
        continueAfterFailure = false
        let app = XCUIApplication()
        setupSnapshot(app)  // Initialize snapshot
        app.launch()
    }

    func testTakeScreenshots() throws {
        let app = XCUIApplication()

        // Screenshot 1: Home screen
        snapshot("01_HomeScreen")

        // Navigate to feature and capture
        app.buttons["Feature"].tap()
        snapshot("02_FeatureScreen")

        // Screenshot with content
        app.textFields["Search"].tap()
        app.textFields["Search"].typeText("Example")
        snapshot("03_SearchResults")

        // Settings screen
        app.buttons["Settings"].tap()
        snapshot("04_Settings")

        // Any additional screens...
        snapshot("05_DetailView")
    }
}

Step 4: Run Snapshot

# Capture all screenshots
fastlane snapshot

# Specific device only
fastlane snapshot --devices "iPhone 15 Pro Max"

# Specific language only
fastlane snapshot --languages "en-US"

# Skip launch (use existing simulator state)
fastlane snapshot --skip_open_summary

Screenshots are saved to fastlane/screenshots/{language}/{device}/.

Step 5: Upload to App Store Connect

After capturing, upload with deliver:

# Upload screenshots only (no binary, no metadata)
fastlane deliver --skip_binary_upload --skip_metadata --overwrite_screenshots

deliver reads fastlane/screenshots/<locale>/, maps each PNG to a display size by its pixel dimensions, and orders them by filename sort — so prefix names (01_, 02_, …).

Uploading screenshots you framed yourself

If you frame with your own pipeline (a design tool, a web framer) instead of frameit, deliver can still upload them — stage them into the <locale>/ layout and let dimension-mapping place them:

lane :upload_framed_screenshots do
  framed  = File.expand_path("../path/to/your/framed", __dir__)
  staging = File.expand_path("./screenshots/en-US", __dir__)   # deliver wants <locale>/
  FileUtils.rm_rf(File.dirname(staging)); FileUtils.mkdir_p(staging)
  FileUtils.cp(Dir.glob("#{framed}/*.png"), staging)
  deliver(skip_binary_upload: true, skip_metadata: true,
          skip_screenshots: false, overwrite_screenshots: true, force: true)
end

RGB only — no alpha. App Store rejects screenshots with an alpha channel (ERROR ITMS-90475 / IMAGE_ALPHA_NOT_ALLOWED). Web/toPng framers usually add one — flatten before upload: magick in.png -alpha remove -alpha off out.png.

If your framer is a full editor (not a static page), don't hand-click its browser "Export bundle" button — that isn't repeatable and dumps a zip in the editor's own nested layout. Instead, expose a tiny dev-only export hook on window that reuses the editor's existing capture function (it already knows the exact per-size toPng render), then drive it with headless Chrome:

// in the editor (dev only): loop slides × required sizes through the UI's own
// captureSlide(), return base64 PNGs — no zip, no download dialog.
window.__exportFramed = async () => {/* … returns [{name, dataUrl}] */};

// driver (puppeteer-core → system Chrome): call the hook, flatten, write flat.
const items = await page.evaluate(() => window.__exportFramed());
for (const { name, dataUrl } of items)
  execFileSync("magick", ["png:-","-alpha","remove","-alpha","off", out(name)],
              { input: Buffer.from(dataUrl.split(",")[1], "base64") });

One command regenerates the whole set into your canonical output dir, already RGB — then point the upload_framed_screenshots lane above at that dir. This beats the editor's bundle button (which still emits RGBA in a layout deliver can't read) and keeps the pipeline scriptable.

What deliver does NOT upload

deliver handles app-level metadata + screenshots only. It does not touch:

• In-app-purchase / subscription assets — the per-IAP Review Information → Screenshot and the 1024×1024 Image (Optional) promo. Upload these by hand in App Store Connect (no turnkey fastlane action; the raw ASC API is the only alternative).
• App icon — comes from the uploaded build (the AppIcon asset catalog), never a separate upload.

Auth

deliver needs App Store Connect credentials. For non-interactive/CI runs, configure an App Store Connect API key (.p8) — see the match skill's CI/CD section. With only an Apple ID it falls back to interactive 2FA, which can't be scripted.

App Store Screenshot Requirements

Required Device Sizes

Minimum: 6.9" iPhone screenshots are the primary requirement. 6.5" is only required if 6.9" aren't provided. Smaller iPhone sizes (6.3", 6.1", 5.5", 4.7") auto-scale from the larger ones — only supply them if you want pixel-perfect framing on those displays. iPad screenshots are required if the app runs on iPad.

For exact pixel dimensions, see Apple's screenshot specifications — they update with each new device generation, so always check the current source.

Screenshot Count

• Minimum: 1 per device size
• Maximum: 10 per device size
• Recommended: 5-6 highlighting key features

Optional: Frame Screenshots with Device Bezels

Add device frames around screenshots using frameit:

# Install frameit
brew install imagemagick

# Frame screenshots
fastlane frameit

# Silver device frames
fastlane frameit silver

Create fastlane/screenshots/Framefile.json for custom titles:

{
  "default": {
    "title": {
      "font": "./fonts/MyFont.ttf",
      "color": "#000000"
    },
    "background": "#FFFFFF",
    "padding": 50,
    "show_complete_frame": true
  }
}

Troubleshooting

"SnapshotHelper.swift not found"

Re-run fastlane snapshot init and add the helper to your UI test target.

"Unable to boot simulator"

Reset the simulator:

xcrun simctl shutdown all
xcrun simctl erase all

Screenshots are black/blank

• Ensure setupSnapshot(app) is called before app.launch()
• Add small delays if content loads asynchronously:

sleep(1)  // Wait for content
snapshot("01_HomeScreen")

"No matching device found"

Check available simulators:

xcrun simctl list devices available

Update Snapfile device names to match exactly.

UI test fails to find element

Use accessibility identifiers:

// In your app code
button.accessibilityIdentifier = "settingsButton"

// In UI test
app.buttons["settingsButton"].tap()

Paywall/price screenshots show the wrong currency

Under any automated run (xcodebuild, fastlane snapshot, simctl), StoreKit renders Product.displayPrice from the US storefront — regardless of the device region or the .storekit _storefront/_locale. Only the Xcode IDE Run button honours a configured storefront, and that can't be scripted. To screenshot a price in another currency, render it from your own region/pricing source behind a #if DEBUG, launch-arg-gated hook instead of relying on live StoreKit.

Integrate with Fastfile

Add a dedicated lane for screenshots:

lane :screenshots do
  snapshot(
    scheme: "YourAppUITests",
    devices: ["iPhone 15 Pro Max", "iPad Pro 13-inch (M4)"],
    languages: ["en-US"]
  )
  # Optional: frame screenshots
  # frameit(white: true)
end

lane :upload_screenshots do
  deliver(
    skip_binary_upload: true,
    skip_metadata: true,
    overwrite_screenshots: true
  )
end

Best Practices

1. Use sample data: Pre-populate app with attractive demo content
2. Consistent state: Reset app state before each test run
3. Accessibility IDs: More reliable than text matching
4. Handle async: Add waits for network content to load
5. Dark mode: Capture both light and dark variants
6. Localization: Test with actual translations, not placeholders
7. Landscape: Include landscape screenshots for iPad if relevant

Files Created

fastlane/
├── Snapfile                    # Snapshot configuration
├── SnapshotHelper.swift        # Helper for UI tests (copy to test target)
└── screenshots/
    ├── en-US/
    │   ├── iPhone 15 Pro Max/
    │   │   ├── 01_HomeScreen.png
    │   │   ├── 02_FeatureScreen.png
    │   │   └── ...
    │   └── iPad Pro 13-inch (M4)/
    │       └── ...
    └── ja/
        └── ...

Complete Workflow

# 1. Set up snapshot
fastlane snapshot init

# 2. Write UI tests with snapshot() calls

# 3. Capture screenshots
fastlane snapshot

# 4. Review screenshots in fastlane/screenshots/

# 5. Optional: add device frames
fastlane frameit

# 6. Upload to App Store Connect
fastlane deliver --skip_binary_upload --skip_metadata