✨ Harden Swift SDK package (#252)

## Why

The Swift SDK was doing the right high-level job, but its package shape
made native app integration heavier than it needed to be. The core
`Vizzly` product pulled in XCTest helpers, and Swift comparison options
were sent at the top level even though the TDD server reads
per-screenshot comparison settings from `properties`.

We also did not have the same real E2E confidence for Swift that the
other SDKs have. A green unit test could still miss server discovery,
actual PNG upload, local baseline creation, repeated screenshot
matching, or the cloud CI path.

## What changed

- Split XCTest convenience APIs into a new `VizzlyXCTest` product while
keeping the core `Vizzly` client lightweight.
- Updated Swift screenshot payload construction so `threshold`,
`minClusterSize`, and `fullPage` flow through `properties`, matching the
server contract.
- Added focused Swift tests for payload shaping and default
server-config behavior.
- Added `VizzlyE2ETests`, which upload real PNG bytes through
`VizzlyClient` against a real local TDD server.
- Added `npm run test:swift:e2e`, which builds the CLI, starts an
isolated TDD run in a temp directory, and runs the Swift E2E suite.
- Added the Swift SDK to `.github/workflows/sdk-e2e.yml` with both
TDD-mode and cloud-mode runs.
- Wired cloud-mode Swift E2E through the repo secret
`VIZZLY_SWIFT_CLIENT_TOKEN`, matching the per-SDK token pattern used by
the other SDKs.
- Simplified the synchronous upload path with a small request-state
helper for timeout/cancel handling.
- Updated Swift SDK docs and examples for the SPM product split, E2E
command, direct-client usage, and current integration guidance.

## Validation

- `swift test`
- `npm run test:swift:e2e`
- `swift build --sdk
/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator26.5.sdk
--triple arm64-apple-ios13.0-simulator`
- `swift package describe --type json`
- `git diff --check`
- `ruby -e 'require "yaml";
YAML.load_file(".github/workflows/sdk-e2e.yml"); puts "ok"'`
- Confirmed `VIZZLY_SWIFT_CLIENT_TOKEN` exists in repo Actions secrets.

Author: Robdel12

.github/workflows/sdk-e2e.yml

@@ -376,11 +376,51 @@ jobs:
           VIZZLY_COMMIT_MESSAGE: ${{ github.event.pull_request.head.commit.message || github.event.head_commit.message }}
           VIZZLY_COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
 
+  # Swift SDK
+  swift:
+    name: Swift SDK
+    runs-on: macos-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+
+      - name: Install CLI dependencies
+        run: npm ci
+
+      - name: Build CLI
+        run: npm run build
+
+      - name: Build Swift package
+        working-directory: ./clients/swift
+        run: swift build
+
+      - name: Run E2E tests (TDD mode)
+        working-directory: ./clients/swift
+        run: ../../bin/vizzly.js tdd run "VIZZLY_E2E=1 swift test --filter VizzlyE2ETests"
+        env:
+          CI: true
+
+      - name: Run E2E tests (Cloud mode)
+        working-directory: ./clients/swift
+        run: ../../bin/vizzly.js run "VIZZLY_E2E=1 swift test --filter VizzlyE2ETests"
+        env:
+          CI: true
+          VIZZLY_TOKEN: ${{ secrets.VIZZLY_SWIFT_CLIENT_TOKEN }}
+          VIZZLY_COMMIT_MESSAGE: ${{ github.event.pull_request.head.commit.message || github.event.head_commit.message }}
+          VIZZLY_COMMIT_SHA: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
+
   # Status check for branch protection
   check:
     name: E2E Status
     runs-on: ubuntu-latest
-    needs: [core-js, vitest, storybook, static-site, ember, ruby]
+    needs: [core-js, vitest, storybook, static-site, ember, ruby, swift]
     if: always()
     steps:
       - name: Check all SDK E2E tests passed
@@ -409,4 +449,8 @@ jobs:
             echo "Ruby SDK E2E tests failed"
             exit 1
           fi
+          if [[ "${{ needs.swift.result }}" == "failure" ]]; then
+            echo "Swift SDK E2E tests failed"
+            exit 1
+          fi
           echo "All SDK E2E tests passed"

clients/swift/Example/ExampleUITests.swift

@@ -1,5 +1,6 @@
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 /// Example UI tests demonstrating Vizzly integration
 ///
@@ -133,15 +134,13 @@ final class ExampleUITests: XCTestCase {
     func testResponsiveLayout() throws {
         // Test different device orientations
         XCUIDevice.shared.orientation = .portrait
-        sleep(1) // Wait for orientation change
 
         app.vizzlyScreenshot(
             name: "home-portrait",
             properties: ["orientation": "portrait"]
         )
 
         XCUIDevice.shared.orientation = .landscapeLeft
-        sleep(1)
 
         app.vizzlyScreenshot(
             name: "home-landscape",
@@ -187,7 +186,7 @@ final class ExampleUITests: XCTestCase {
     // MARK: - Custom Threshold Example
 
     func testWithCustomThreshold() throws {
-        // Allow up to 5% pixel difference
+        // Allow a higher comparison threshold for animated content
         app.vizzlyScreenshot(
             name: "animation-test",
             threshold: 5,

clients/swift/INTEGRATION.md

@@ -21,7 +21,10 @@ In Xcode:
 1. **File → Add Package Dependencies**
 2. Enter URL: `https://github.com/vizzly-testing/cli`
 3. Select version/branch
-4. **Important**: Add the package to your **UI Test target** (not the main app target)
+4. Add the `VizzlyXCTest` product to your **UI Test target**
+
+Use the core `Vizzly` product directly only when you need to send PNG data from
+app or test-support code without the XCTest convenience extensions.
 
 #### Option B: Local Package
 
@@ -78,6 +81,7 @@ Create or update your UI test file:
 ```swift
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 final class MyAppUITests: XCTestCase {
 
@@ -265,13 +269,13 @@ For views with animations or timing-sensitive content:
 func testAnimatedView() {
     app.launch()
 
-    // Wait for animation to complete
-    sleep(1) // Or use expectations
+    let finishedState = app.otherElements["AnimatedBannerReady"]
+    XCTAssertTrue(finishedState.waitForExistence(timeout: 5))
 
     // Use threshold for slight variations
     app.vizzlyScreenshot(
         name: "animated-banner",
-        threshold: 5  // Allow 5% difference
+        threshold: 5
     )
 }
 ```

clients/swift/Package.swift

@@ -13,13 +13,22 @@ let package = Package(
         .library(
             name: "Vizzly",
             targets: ["Vizzly"]),
+        .library(
+            name: "VizzlyXCTest",
+            targets: ["VizzlyXCTest"]),
     ],
     targets: [
         .target(
             name: "Vizzly",
             dependencies: []),
+        .target(
+            name: "VizzlyXCTest",
+            dependencies: ["Vizzly"]),
         .testTarget(
             name: "VizzlyTests",
+            dependencies: ["Vizzly", "VizzlyXCTest"]),
+        .testTarget(
+            name: "VizzlyE2ETests",
             dependencies: ["Vizzly"]),
     ]
 )

clients/swift/QUICKSTART.md

@@ -13,7 +13,7 @@ npm install -g @vizzly-testing/cli
 1. Open your iOS project in Xcode
 2. **File → Add Package Dependencies**
 3. Paste: `https://github.com/vizzly-testing/cli`
-4. Add to your **UI Test target** (not main app)
+4. Add the `VizzlyXCTest` product to your **UI Test target**
 
 ## 3. Start TDD Server
 
@@ -28,6 +28,7 @@ vizzly tdd start
 ```swift
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 class MyAppUITests: XCTestCase {
     let app = XCUIApplication()
@@ -96,7 +97,7 @@ button.vizzlyScreenshot(name: "submit-button")
 ### Custom Threshold
 
 ```swift
-// Allow 5% pixel difference (useful for animations)
+// Allow a higher comparison threshold for animated content
 app.vizzlyScreenshot(
     name: "animated-view",
     threshold: 5

clients/swift/README.md

@@ -7,7 +7,7 @@ Unlike tools that render components in isolation, Vizzly captures screenshots di
 ## Features
 
 - **Zero Configuration** - Auto-discovers Vizzly TDD server
-- **Native XCTest Integration** - Simple extensions for `XCUIApplication` and `XCUIElement`
+- **Native XCTest Integration** - Simple extensions for `XCUIApplication` and `XCUIElement` via the `VizzlyXCTest` helper product
 - **iOS & macOS Support** - Works on both platforms
 - **Automatic Metadata** - Captures device, screen size, and platform info
 - **TDD Mode** - Local visual testing with instant feedback
@@ -22,21 +22,29 @@ Add Vizzly to your test target using Xcode:
 
 1. File → Add Package Dependencies
 2. Enter repository URL: `https://github.com/vizzly-testing/cli`
-3. Select version and add to your UI test target
+3. Select version and add the `VizzlyXCTest` product to your UI test target
+
+The core `Vizzly` product has no XCTest dependency and can also be used from
+native app or test-support code when you want to send PNG data directly.
 
 Or add to your `Package.swift`:
 
 ```swift
 dependencies: [
     .package(url: "https://github.com/vizzly-testing/cli", from: "1.0.0")
+],
+targets: [
+    .testTarget(
+        name: "MyAppUITests",
+        dependencies: [
+            .product(name: "VizzlyXCTest", package: "cli")
+        ]
+    )
 ]
 ```
 
-### CocoaPods
-
-```ruby
-pod 'Vizzly', :git => 'https://github.com/vizzly-testing/cli', :branch => 'main'
-```
+Vizzly does not currently ship a CocoaPods podspec. Use Swift Package Manager
+for native app integration.
 
 ## Quick Start
 
@@ -54,6 +62,7 @@ This starts a local server at `http://localhost:47392` that receives screenshots
 ```swift
 import XCTest
 import Vizzly
+import VizzlyXCTest
 
 class MyUITests: XCTestCase {
     let app = XCUIApplication()
@@ -128,14 +137,17 @@ func testNavigationBar() {
 
 ```swift
 func testAnimatedContent() {
-    // Allow up to 5% pixel difference (useful for animations)
+    // Allow a higher comparison threshold for animated content
     app.vizzlyScreenshot(
         name: "animated-banner",
         threshold: 5
     )
 }
 ```
 
+If `threshold` or `minClusterSize` is omitted, the server's configured
+comparison settings are used.
+
 ### Multiple Device Orientations
 
 ```swift
@@ -187,7 +199,8 @@ extension XCUIApplication {
     func vizzlyScreenshot(
         name: String,
         properties: [String: Any]? = nil,
-        threshold: Int = 0,
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil,
         fullPage: Bool = false
     ) -> [String: Any]?
 }
@@ -200,7 +213,8 @@ extension XCUIElement {
     func vizzlyScreenshot(
         name: String,
         properties: [String: Any]? = nil,
-        threshold: Int = 0
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil
     ) -> [String: Any]?
 }
 ```
@@ -213,15 +227,17 @@ extension XCTestCase {
         name: String,
         app: XCUIApplication,
         properties: [String: Any]? = nil,
-        threshold: Int = 0,
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil,
         fullPage: Bool = false
     ) -> [String: Any]?
 
     func vizzlyScreenshot(
         name: String,
         element: XCUIElement,
         properties: [String: Any]? = nil,
-        threshold: Int = 0
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil
     ) -> [String: Any]?
 }
 ```
@@ -236,7 +252,8 @@ class VizzlyClient {
         name: String,
         image: Data,
         properties: [String: Any]? = nil,
-        threshold: Int = 0,
+        threshold: Double? = nil,
+        minClusterSize: Int? = nil,
         fullPage: Bool = false
     ) -> [String: Any]?
 
@@ -254,8 +271,9 @@ class VizzlyClient {
 The SDK automatically discovers a running Vizzly TDD server using this priority order:
 
 1. **VIZZLY_SERVER_URL environment variable** - Explicitly set server URL
-2. **Global server file** - `~/.vizzly/server.json` written by CLI
-3. **Default port health check** - Tests `http://localhost:47392/health`
+2. **Project server file** - `.vizzly/server.json` in the current directory
+3. **Global server file** - `~/.vizzly/server.json` written by CLI
+4. **Default port health check** - Tests `http://localhost:47392/health`
 
 When you run `vizzly tdd start`, the CLI automatically writes server info to `~/.vizzly/server.json` in your home directory, enabling zero-config discovery from iOS tests.
 
@@ -440,6 +458,18 @@ Check out the `Example/` directory for:
 - Custom properties and thresholds
 - Direct client usage
 
+## SDK E2E Tests
+
+The Swift SDK has an end-to-end test path that runs against a real local
+Vizzly TDD server and uploads real PNG bytes through `VizzlyClient`:
+
+```bash
+npm run test:swift:e2e
+```
+
+This command builds the CLI, starts an isolated TDD run in a temp directory,
+and executes the `VizzlyE2ETests` SwiftPM suite.
+
 ## Contributing
 
 Bug reports and pull requests are welcome at https://github.com/vizzly-testing/cli