Skip to content
Latest

Swift examples

These examples assume your UI test target imports VizzlyXCTest.

import XCTest
import Vizzly
import VizzlyXCTest

SwiftUI previews

Keep using regular SwiftUI previews:

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

Capture that preview with:

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

See SwiftUI preview capture for setup and options.

Full screen

app.vizzlyScreenshot(name: "home-screen")

Element capture

app.buttons["Submit"].vizzlyScreenshot(name: "submit-button")

Variants with stable properties

Use stable metadata for variants. Add those keys to local signatureProperties or the cloud project’s matching settings for separate baselines.

Avoid helper-owned keys like platform, deviceName, deviceModel, osName, osVersion, viewport, and elementType unless you intentionally want to override the automatic XCTest metadata.

app.vizzlyScreenshot(
name: "login-form",
properties: ["state": "empty"]
)
app.vizzlyScreenshot(
name: "login-form",
properties: ["state": "filled"]
)

Per-screenshot comparison settings

Set shared cloud comparison settings in your Vizzly project. Use vizzly.config.js for local settings or deliberate overrides. Override a single screenshot when that screen needs different sensitivity.

app.vizzlyScreenshot(
name: "dashboard-chart",
properties: ["theme": "dark"],
threshold: 2.5,
minClusterSize: 4,
fullPage: true,
requestTimeout: 60_000
)

Orientation variants

XCUIDevice.shared.orientation = .portrait
app.vizzlyScreenshot(name: "home", properties: ["orientation": "portrait"])
XCUIDevice.shared.orientation = .landscapeLeft
app.vizzlyScreenshot(name: "home", properties: ["orientation": "landscape"])

Check readiness first

The SDK skips captures when Vizzly isn’t running. You can check readiness first in a helper:

if VizzlyClient.shared.isReady {
app.vizzlyScreenshot(name: "settings")
}

Use the core client directly

Use VizzlyClient when you already have PNG data or when your target should avoid the XCTest helper module.

import Vizzly
import XCTest
let screenshot = app.screenshot()
VizzlyClient.shared.screenshot(
name: "settings",
image: screenshot.pngRepresentation,
properties: [
"surface": "settings",
"mode": "signed-in"
]
)

Wrap native UI tests in CI

The CLI starts a capture server and passes VIZZLY_SERVER_URL and VIZZLY_BUILD_ID to its child command. Configure your Xcode test plan or launcher to forward both to the UI test runner. Check VizzlyClient.shared.info from the runner; the wrapper alone doesn’t confirm that forwarding works.

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

Tip

Keep names stable and wait for the UI state you need before capturing.

Next steps