Skip to content
Vizzly Docs

Swift SDK Overview

Use the Swift SDK to capture screenshots from UI tests or render your SwiftUI #Preview declarations in an iOS Simulator.

Choose the right product

The SDK has three products:

  • Vizzly is the core client. It has no XCTest dependency and accepts PNG data directly.
  • VizzlyXCTest adds XCTest convenience helpers for XCUIApplication, XCUIElement, and XCTestCase.
  • Add VizzlyPreviewRuntime to your app target so vizzly previews can render its SwiftUI previews.

Use VizzlyXCTest from UI test targets. Use Vizzly when you want to capture or generate image data yourself.

Install

Install the CLI:

Terminal window
npm install -D @vizzly-testing/cli

Then add the Swift package to your project.

.package(url: "https://github.com/vizzly-testing/cli", from: "0.1.1")

Add VizzlyXCTest to UI test targets:

.testTarget(
    name: "MyAppUITests",
    dependencies: [
        .product(name: "VizzlyXCTest", package: "cli")
    ]
)

Use Swift Package Manager for native app integration.

To capture SwiftUI previews, also install the Swift CLI plugin. It requires Vizzly CLI 0.36.0 or newer:

Terminal window
npm install -D @vizzly-testing/swift

Then add VizzlyPreviewRuntime to your app target. See SwiftUI Preview Capture for setup and usage.

Basic usage

import XCTest
import VizzlyXCTest


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


    func testHomeScreen() {
        app.launch()
        app.vizzlyScreenshot(name: "home-screen")
    }
}

You can also capture one element:

app.navigationBars.firstMatch.vizzlyScreenshot(name: "navigation-bar")

Direct client usage

Use VizzlyClient when you already have PNG data, or when you do not want to pull XCTest helpers into a target.

import Vizzly
import XCTest


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


    func testHomeScreen() throws {
        app.launch()


        let screenshot = app.screenshot()
        VizzlyClient.shared.screenshot(
            name: "home-screen",
            image: screenshot.pngRepresentation,
            properties: ["surface": "home"],
            buildId: "build-123",
            requestTimeout: 60_000
        )
    }
}

Options

app.vizzlyScreenshot(
    name: "home-dark",
    properties: ["theme": "dark"],
    threshold: 2.0,
    minClusterSize: 3,
    fullPage: false,
    buildId: "build-123",
    requestTimeout: 60_000
)

threshold, minClusterSize, fullPage, and buildId are sent with the screenshot so Vizzly can use the right comparison settings for that capture.

requestTimeout controls the SDK HTTP request timeout and is measured in milliseconds.

The XCTest helpers automatically add platform, deviceName, deviceModel, osName, osVersion, viewport, and elementType for element captures. User-supplied properties win when a key already exists.

Discovery order

The client looks for a server in this order:

  1. VIZZLY_SERVER_URL
  2. project .vizzly/server.json
  3. ~/.vizzly/server.json
  4. http://localhost:47392/health

The SDK also reads VIZZLY_BUILD_ID and VIZZLY_FAIL_ON_DIFF. .vizzly/server.json can supply buildId and failOnDiff; failOnDiff only changes local TDD behavior.

Run it

For local review, start the TDD server and run your tests normally:

Terminal window
vizzly tdd start
xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'

For a one-shot local report, wrap the test command:

Terminal window
vizzly tdd run "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'"

For cloud builds, wrap the same command with vizzly run:

Terminal window
VIZZLY_TOKEN=vzt_project_token \
  vizzly run "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" --wait

Useful client APIs

  • VizzlyClient.shared
  • client.screenshot(...)
  • client.isReady
  • client.info
  • app.vizzlyScreenshot(...) from VizzlyXCTest
  • element.vizzlyScreenshot(...) from VizzlyXCTest

Next steps