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:
Vizzlyis the core client. It has no XCTest dependency and accepts PNG data directly.VizzlyXCTestadds XCTest convenience helpers forXCUIApplication,XCUIElement, andXCTestCase.- Add
VizzlyPreviewRuntimeto your app target sovizzly previewscan 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:
npm install -D @vizzly-testing/cliThen add the Swift package to your project.
.package(url: "https://github.com/vizzly-testing/cli", exact: "0.1.1")Add VizzlyXCTest to UI test targets:
.testTarget( name: "MyAppUITests", dependencies: [ .product(name: "VizzlyXCTest", package: "cli") ])To capture SwiftUI previews, also install the Swift CLI plugin. It requires Vizzly CLI 0.36.0 or newer:
npm install -D @vizzly-testing/swiftThen add VizzlyPreviewRuntime to your app target. See
SwiftUI preview capture for setup and usage.
Basic usage
import XCTestimport 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 Vizzlyimport 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"], requestTimeout: 60_000 ) }}Options
app.vizzlyScreenshot( name: "home-dark", properties: ["theme": "dark"], threshold: 2.0, minClusterSize: 3, fullPage: false, 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:
VIZZLY_SERVER_URL- project
.vizzly/server.json ~/.vizzly/server.jsonhttp://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
Start the TDD server for local review, then run your UI tests:
npx vizzly tdd startxcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'For a one-shot local report, wrap the test command:
npx vizzly tdd run "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'"For cloud builds, wrap the command with vizzly run. Your Xcode test plan or
launcher must pass VIZZLY_SERVER_URL and VIZZLY_BUILD_ID to the UI test
runner. Wrapping xcodebuild alone doesn’t confirm those values reach it.
Check VizzlyClient.shared.info inside the runner.
VIZZLY_TOKEN=vzt_project_token \ npx vizzly run "xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'" --waitCheck local differences in XCTest
With failOnDiff enabled, a local visual diff returns nil. It doesn’t fail
XCTest by itself. Assert on the result when you want the test to fail:
let client = VizzlyClient(failOnDiff: true)let result = client.screenshot( name: "checkout", image: app.screenshot().pngRepresentation)XCTAssertNotNil(result, "Vizzly capture failed or found a visual difference")Connection errors also return nil. The screenshot helpers use
VizzlyClient.shared; a separate client doesn’t change their settings.
Useful client APIs
VizzlyClient.sharedclient.screenshot(...)client.isReadyclient.infoapp.vizzlyScreenshot(...)fromVizzlyXCTestelement.vizzlyScreenshot(...)fromVizzlyXCTest