screenshots-ios

Capture iOS simulator screenshots from the command line.

Build, install, launch with deterministic data, and capture — one command. Designed for App Store screenshots, regression testing, and CI pipelines.

Quick Start

# Run directly with npx (no install needed)
npx screenshots-ios --context screenshots/home.json

# Or install globally
npm install -g screenshots-ios
screenshots-ios --context screenshots/home.json

Run from your app's repo root. The tool handles the full pipeline:

1. Resolve simulator device
2. Boot simulator
3. Build app (xcodebuild)
4. Install on simulator
5. Override status bar (9:41, full signal, 100% battery)
6. Launch app with environment variables
7. Wait for UI to settle
8. Capture screenshot

Requirements

• macOS with Xcode installed
• xcrun, xcodebuild, and simctl available in PATH
• Node.js >= 18

Usage

Single Screenshot

Create a JSON context file that describes what to capture:

{
  "workspace": "MyApp.xcworkspace",
  "scheme": "MyApp",
  "screenshotName": "home",
  "outputDir": "docs/screenshots",
  "launchEnv": {
    "APP_USE_PREVIEW_DATA": "1",
    "APP_INITIAL_SCREEN": "home"
  }
}

npx screenshots-ios --context screenshots/home.json

Multiple Screenshots

Build once, then --skip-build the rest:

npx screenshots-ios --context screenshots/home.json
npx screenshots-ios --context screenshots/settings.json --skip-build
npx screenshots-ios --context screenshots/profile.json --skip-build

List Available Simulators

npx screenshots-ios --list-devices
npx screenshots-ios --list-devices --simulator "iPhone" --os "26"

CLI Flags

Flags override values from the context file:

npx screenshots-ios --context screenshots/home.json \
  --skip-build \
  --simulator "iPhone 17 Pro Max" \
  --wait 5 \
  --name home-dark \
  --launch-env THEME=dark \
  --open

Context File Reference

All fields except scheme are optional.

Field	Type	Default	Description
workspace	string	auto-detected	.xcworkspace path
project	string	auto-detected	.xcodeproj path (if no workspace)
scheme	string	required	Xcode build scheme
configuration	string	"Debug"	Build configuration
appName	string	auto-detected	Product name (to find .app bundle)
bundleId	string	from Info.plist	Bundle identifier
simulator	string	"iPhone 17 Pro"	Simulator device name
simulatorOS	string	any	Runtime filter (e.g. "26.2")
simulatorUdid	string	—	Exact UDID (bypasses name lookup)
derivedDataPath	string	"Derived/Screenshots"	xcodebuild derived data
outputDir	string	"docs/screenshots"	Where screenshots are saved
screenshotName	string	"app"	File prefix: {name}-{timestamp}.png
waitSeconds	number	2	Seconds to wait before capture
statusBar.enabled	boolean	true	Override status bar
statusBar.time	string	"09:41"	Status bar clock time
skipBuild	boolean	false	Skip xcodebuild
cleanBuild	boolean	false	Run clean build
openAfterCapture	boolean	false	Open screenshot in Preview
testBeforeCapture	boolean	false	Run tests first
testScheme	string	same as scheme	Test scheme
launchEnv	object	{}	Env vars passed to the app
launchArgs	string[]	[]	Launch arguments

CLI Reference

Usage: screenshots-ios [options]

Required:
  --scheme <name>              Build scheme (or set in context file)

Container:
  --workspace <path>           .xcworkspace path
  --project <path>             .xcodeproj path
  --context <path>             JSON context file

Build:
  --configuration <name>       Build configuration (default: Debug)
  --derived-data <path>        DerivedData path
  --skip-build                 Reuse existing build
  --clean-build                Clean before building

Simulator:
  --simulator <name>           Device name (default: iPhone 17 Pro)
  --os <value>                 Runtime filter (e.g. "26.2")
  --udid <uuid>                Exact simulator UDID

Output:
  --name <value>               Screenshot file prefix
  --output-dir <path>          Output directory
  --wait <seconds>             Delay before capture
  --open                       Open after capture

App context:
  --launch-env KEY=VALUE       Environment variable (repeatable)
  --launch-arg <arg>           Launch argument (repeatable)
  --app-name <name>            Product name
  --bundle-id <id>             Bundle identifier

Status bar:
  --status-bar-time <HH:MM>    Clock time (default: 09:41)
  --no-status-bar              Disable override

Testing:
  --test-before-capture        Run tests first
  --test-scheme <name>         Test scheme

General:
  --list-devices               List available simulators
  -h, --help                   Show help

Wiring Your App for Deterministic Screenshots

The tool handles build/install/launch/capture. Your app handles showing the right screen with the right data. Here's the contract:

1. Preview Mode

Read an environment variable at launch to switch to deterministic data:

let usePreview = ProcessInfo.processInfo.environment["APP_USE_PREVIEW_DATA"] == "1"

2. Screen Navigation

Read an environment variable to jump to a specific screen:

@State private var selectedTab: Tab = {
    if let tab = ProcessInfo.processInfo.environment["APP_INITIAL_TAB"] {
        return Tab(rawValue: tab) ?? .home
    }
    return .home
}()

3. In-Memory Repositories

Replace real data sources with seeded in-memory implementations:

actor PreviewRepository: SomeRepository {
    private var items: [Item]
    init(seed: [Item]) { self.items = seed }
    func fetchAll() async -> [Item] { items }
}

4. Static Seed Data

Use hardcoded data with fixed IDs — no random values, no Date():

enum PreviewData {
    static let items: [Item] = [
        Item(id: "fixed-uuid-1", name: "Groceries", amount: 25000),
        Item(id: "fixed-uuid-2", name: "Transport", amount: 37000),
    ]
}

5. Modal Screens (Optional)

For screens triggered by user actions, add env var hooks:

.onAppear {
    if ProcessInfo.processInfo.environment["APP_OPEN_REVIEW_FLOW"] == "1" {
        showReviewFlow = true
    }
}

Environment Variable Flow

context.json → launchEnv → SIMCTL_CHILD_ prefix → simulator → ProcessInfo.processInfo.environment

The tool automatically adds the SIMCTL_CHILD_ prefix. Your app reads the original key name.

Recommended Project Layout

your-app/
├── screenshots/              # Context files (one per screenshot)
│   ├── capture-all.sh        # Batch script
│   ├── home.json
│   ├── settings.json
│   └── profile.json
├── docs/screenshots/         # Output
├── MyApp.xcworkspace
└── ...

Batch Script Template

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"

cd "$REPO_ROOT"

CONTEXTS=(home settings profile)

for i in "${!CONTEXTS[@]}"; do
  ctx="${CONTEXTS[$i]}"
  skip=""
  [[ "$i" -gt 0 ]] && skip="--skip-build"
  npx screenshots-ios --context "$SCRIPT_DIR/${ctx}.json" $skip
done

License

MIT