Swift examples
These examples assume your UI test target imports VizzlyXCTest.
import XCTestimport Vizzlyimport VizzlyXCTestSwiftUI previews
Keep using regular SwiftUI previews:
#Preview("Home screen") { HomeView()}Capture that preview with:
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 = .portraitapp.vizzlyScreenshot(name: "home", properties: ["orientation": "portrait"])
XCUIDevice.shared.orientation = .landscapeLeftapp.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 Vizzlyimport 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.
npx vizzly tdd run "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'"VIZZLY_TOKEN=vzt_project_token \ npx vizzly run "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" --waitTip
Keep names stable and wait for the UI state you need before capturing.