screenshots-ios: repeatable iOS simulator screenshots from the CLI

Screenshots drift when the clock, battery or sample data change between runs. screenshots-ios handles the simulator side from the command line: it builds and installs the app, sets the status bar, launches with your environment variables and saves the image. Your app still decides which screen and which data to show.

How it works

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.

To upload builds and metadata, see appstore-tools. All projects →