Automate localized screenshots with Fastlane

Documentation

Tutorials

ButterKit makes it easy to capture directly from Xcode Simulator in all localizations, however, it can be helpful to automate this with a tool like fastlane.

Prerequisites

macOS 15+ and Xcode installed
A working iOS app project
A UI Test target (we’ll add test code that triggers screenshots)
Ruby + Bundler (recommended)
ButterKit installed

Step 1 — Install Fastlane (project-local)

From your app repo root:

# 1) Add a Gemfile (project-local install is preferred)
cat > Gemfile <<'RUBY'
source "https://rubygems.org"
gem "fastlane"
RUBY

# 2) Install
bundle install

# 3) Initialize Fastlane
bundle exec fastlane init

Step 2 - Add snapshot config (devices, languages)

Create or update fastlane/Snapfile:

# fastlane/Snapfile

# Your app scheme that builds UI tests
scheme("MyAppUITests")

# Devices to target (choose the ones you actually need)
devices([
  "iPhone 16 Pro Max",
  "iPhone 16 Pro"
  # "iPad Pro (13-inch) (M4)"   # add iPad if useful
])

# Locales (match your App Store locales if you plan to localize)
languages(["en-US"])

# Keep the output tidy
output_directory("./fastlane/screenshots")

# Useful options
clear_previous_screenshots(true)
stop_after_first_error(true)

Step 3 — Add UI Test hooks to take screenshots

Now for the important part: add SnapshotHelper.swift to your UI Test target (Fastlane generates one with snapshot init, or copy from Fastlane docs if you have it already).
Create a UI test that navigates to each screen and calls snapshot(“filename”) where you want a PNG:

import XCTest

final class MyAppScreenshots: XCTestCase {
    let app = XCUIApplication()

    override func setUp() {
        super.setUp()
        continueAfterFailure = false
        setupSnapshot(app)         // From SnapshotHelper.swift
        app.launch()
    }

    func test_screenshots() {
        // 01 — Home
        // Ensure the UI is in a deterministic state
        snapshot("01-Home")

        // 02 — Detail
        app.cells.element(boundBy: 0).tap()
        snapshot("02-Detail")

        // 03 — Settings
        app.tabBars.buttons["Settings"].tap()
        snapshot("03-Settings")
    }
}

Step 4 — Run snapshot and add to ButterKit

Now the easy part: run the fastlane snapshot command. When complete, you’ll have PNG images ready to drag right into ButterKit for 3D device renderings, translation, and App Store Connect uploads!

bundle exec fastlane snapshot

When finished, your screenshots are here:

fastlane/
  screenshots/
    en-US/
      iPhone 16 Pro Max/
        01-Home.png
        02-Detail.png
        03-Settings.png
      iPhone 16 Pro/
        01-Home.png
        02-Detail.png
        03-Settings.png

Having trouble? Join us on Discord or the subreddit (/r/butterkit)for quick help.

Tutorials Format text with Markdown