Vizzly Swift SDK

Vizzly brings visual testing to Swift in two ways:

| Workflow | Use it for | Runs on | | --- | --- | --- | | SwiftUI previews | Render the #Preview declarations in your app | arm64 iOS Simulator | | XCTest screenshots | Capture an app or element during a UI test | iOS or macOS |

Both workflows send screenshots to the same local TDD and cloud review tools. You can use either one or both.

Already use Vizzly from UI tests? Nothing changes. Keep VizzlyXCTest on the UI test target. VizzlyPreviewRuntime is a separate product that you only add to the app target when you want preview capture.

SwiftUI previews

Install the CLI and Swift plugin in your iOS project:

pnpm add --save-dev @vizzly-testing/cli @vizzly-testing/swift

Add this repository as a Swift Package dependency, then add VizzlyPreviewRuntime to the app target with Embed & Sign:

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

Choose Exact Version and enter 0.1.1.

Install the runtime once from the app initializer:

import VizzlyPreviewRuntime

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

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

Boot an iOS Simulator, then run:

pnpm exec vizzly previews

Vizzly builds the app, renders its #Preview declarations, and writes the screenshots to .vizzly/previews.

See PREVIEWS.md for requirements, configuration, CI, and troubleshooting.

XCTest screenshots

Add this repository as a Swift Package dependency:

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

Choose Exact Version and enter 0.1.1.

Add the VizzlyXCTest product to your UI test target. Then capture the app or a single element from a test:

import XCTest
import Vizzly
import VizzlyXCTest

final class HomeScreenTests: XCTestCase {
    func testHomeScreen() {
        let app = XCUIApplication()
        app.launch()

        XCTAssertTrue(app.navigationBars["Home"].waitForExistence(timeout: 5))
        app.vizzlyScreenshot(name: "home")
    }
}

Start a local review session before running the test:

pnpm exec vizzly tdd start --open

See QUICKSTART.md for the shortest setup path and INTEGRATION.md for options and CI.

Support

| Capability | XCTest SDK | Preview capture | | --- | --- | --- | | iOS | iOS 13+ | iOS 17+ Simulator | | macOS | macOS 10.15+ | Not supported | | Local TDD | Yes | Yes | | Cloud builds | Yes | Yes | | Exact Xcode requirement | No | Xcode 26.6 | | Fixed layout and orientation traits | Not applicable | Yes | | Other SwiftUI preview traits | Not applicable | Not supported | | App integration | UI test target | One app initializer call |

Preview capture requires Xcode 26.6. Other Xcode versions stop with a setup error.

More

• XCTest quick start
• XCTest integration guide
• SwiftUI preview guide
• Example UI test
• Changelog