Repeatable iOS simulator screenshots from the CLI

A useful screenshot workflow starts before the capture. The app needs to open on the intended screen, with predictable content and consistent simulator settings. screenshots-ios coordinates that workflow from the command line.

From configuration to capture

The tool resolves a simulator, builds and installs the application, sets up the status bar, launches the app with the configured environment, and captures the screen. A JSON context file holds the capture settings.

The application still owns its screen navigation and sample data. Configure those explicitly so that two captures represent the same state. The repository includes guidance for connecting launch environment variables to preview data and initial screens.

Questions

What runs the capture? The workflow uses the iOS simulator and Xcode command-line tools on macOS.

Can I capture multiple screens? Yes. Use separate context files and reuse a build where appropriate.

Does it create my test data? Your application supplies the deterministic data and navigation hooks; the CLI supplies the launch configuration.

Read the setup and context-file guide.

A repeatable capture

Save a context file for your own workspace and scheme:

{
  "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

The launch variables are a contract with your application: implement preview data and initial-screen selection in the app before relying on repeatable output.

Explore all projects →