Skip to content
Vizzly Docs

SwiftUI Preview Capture

Your app’s SwiftUI #Preview declarations already describe the screens you want to review. Run vizzly previews to render them in an iOS Simulator and capture screenshots for local review or Vizzly.

Requirements

  • Xcode 26.6
  • Node.js 22 or newer
  • Vizzly CLI 0.36.0 or newer
  • An arm64 Mac
  • An iOS 17 or newer Simulator
  • A scene-based iOS app
  • A shared Xcode scheme that builds the app in Debug

Preview capture supports fixed-size layouts and portrait or landscape orientation. Other preview traits are not supported. It captures iOS Simulator previews only; macOS and tvOS previews are not supported.

Install

Install the CLI and Swift plugin in your project:

Terminal window
npm install --save-dev @vizzly-testing/cli @vizzly-testing/swift

In Xcode, add this Swift package:

https://github.com/vizzly-testing/cli

Choose Up to Next Major Version, starting at 0.1.1. Add the VizzlyPreviewRuntime product to your app target and set it to Embed & Sign.

Call VizzlyPreviewRuntime.install() once from your app’s initializer:

import SwiftUI
import VizzlyPreviewRuntime


@main
struct MyApp: App {
    init() {
        VizzlyPreviewRuntime.install()
    }


    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Keep writing standard #Preview declarations:

#Preview("Home screen") {
    HomeView()
}

Capture previews

Boot an iOS Simulator and run this from your project directory:

Terminal window
npx vizzly previews

Vizzly selects the project, scheme, and booted Simulator when it can make a clear choice. If it asks you to choose, pass the project or workspace path, --scheme, or --device:

Terminal window
npx vizzly previews MyApp.xcodeproj --scheme MyApp --device "$SIMULATOR_UDID"

List booted Simulator IDs with:

Terminal window
xcrun simctl list devices booted

To capture one preview or a group, match its display name:

Terminal window
npx vizzly previews --include "Home*"

Screenshots are saved to .vizzly/previews by default. If a preview fails, the command reports it and exits with an error. Screenshots from previews that worked are kept.

Review and upload

For local review, start Vizzly TDD and capture your previews:

Terminal window
npx vizzly tdd start --open
npx vizzly previews

The screenshots appear in the local TDD dashboard.

To upload previews to Vizzly Cloud, set your project token:

Terminal window
VIZZLY_TOKEN=your-project-token npx vizzly previews

Vizzly creates a cloud build and prints its review link.

For GitHub Actions, use an arm64 Mac runner with Xcode 26.6. After checking out the project and installing its dependencies, add a step like this. Store VIZZLY_TOKEN as a repository secret and VIZZLY_SIMULATOR_UDID as a repository variable.

- name: Capture SwiftUI previews
  env:
    VIZZLY_TOKEN: ${{ secrets.VIZZLY_TOKEN }}
    VIZZLY_SIMULATOR_UDID: ${{ vars.VIZZLY_SIMULATOR_UDID }}
  run: |
    xcrun simctl boot "$VIZZLY_SIMULATOR_UDID"
    xcrun simctl bootstatus "$VIZZLY_SIMULATOR_UDID" -b
    npx vizzly previews \
      MyApp.xcodeproj \
      --scheme MyApp \
      --device "$VIZZLY_SIMULATOR_UDID"

Without a running TDD server or cloud credentials, screenshots stay on your machine. Pass --no-upload to keep them local even when upload settings are available.

Options

  • --scheme <name>: choose a shared Xcode scheme.
  • --device <UDID>: choose a booted iOS Simulator.
  • --configuration <name>: choose a build configuration. The default is Debug.
  • --include <pattern>: capture previews whose display names match.
  • --output <path>: choose where screenshots are saved.
  • --capture-timeout <ms>: set the maximum time to wait for each preview.
  • --no-upload: save screenshots without sending them to Vizzly.

Run npx vizzly previews --help for the full option list.

Capture launches your app in the selected Simulator. If app startup normally starts network or analytics services, skip those during capture:

init() {
    VizzlyPreviewRuntime.install()


    if !VizzlyPreviewRuntime.isCapturing {
        startAppServices()
    }
}

Troubleshooting

No booted Simulator is found

Boot an iOS Simulator in Xcode or Simulator, then run npx vizzly previews again.

No previews are found

Make sure the selected scheme builds the app target that contains your #Preview declarations.

The scheme is missing

In Xcode, open Product → Scheme → Manage Schemes, mark the app scheme as shared, and commit the scheme file.

Xcode is unsupported

Check your Xcode version with xcodebuild -version. Preview capture requires Xcode 26.6.