tomsej/dotfiles/swiftui-snapshot-gallery

SwiftUI snapshot gallery

Goal: user browses all UI states as images on a phone/browser, comments in chat, agent edits SwiftUI, regenerates, redeploys. No simulator interaction needed for review.

Architecture (3 pieces, no external dependencies)

1. `PreviewFixtures.swift` in the app target — static sample data shared by

#Preview blocks and the gallery test, so both always show identical states.

1. `SnapshotGalleryTests.swift` in the iOS unit-test target (host app required) —

a hand-maintained scenarios: [(name, AnyView)] registry mirroring the #Preview blocks, rendered to PNG. Skips itself (XCTSkip) unless SNAPSHOT_OUTPUT_DIR is set, so normal test runs are unaffected.

1. `scripts/snapshot-gallery.sh` — runs the test via xcodebuild, assembles

gallery/index.html (responsive grid of PNGs), optionally deploys with --deploy.

Key implementation details (hard-won, do not skip)

• Render via UIWindow attached to the host app's UIWindowScene

(UIApplication.shared.connectedScenes), not a bare window and not ImageRenderer — bare windows and ImageRenderer produce blank images for UIKit-backed views (List, NavigationStack).

• After makeKeyAndVisible(), pump the run loop ~1 s so List/NavigationStack

finish their first layout pass.

• drawHierarchy(in:afterScreenUpdates:true); fall back to layer.render(in:)

when it returns false.

• Guard against silent blank output: downsample to a 32×32 gray bitmap and fail

the test when all pixels are near-white (> 250).

• Pass the output dir through xcodebuild as TEST_RUNNER_SNAPSHOT_OUTPUT_DIR=...

(the TEST_RUNNER_ prefix is stripped inside the test process). The simulator shares the host filesystem, so the test can write directly into the repo.

• The scheme's test configuration must build the app with ENABLE_TESTABILITY: YES

(mandatory when the scheme tests in Release), otherwise @testable import fails with "Compilation search paths unable to resolve module dependency".

• Add gallery/ to .gitignore.

Workflow

1. New UI state to review → add a #Preview block and a matching scenario to

the registry (share sample data via PreviewFixtures).

1. bash scripts/snapshot-gallery.sh → local gallery at gallery/index.html.
2. bash scripts/snapshot-gallery.sh --deploy → deploys to

https://<project>-gallery.surge.sh (domain via SURGE_DOMAIN env).

1. Send the URL to the user; iterate: edit SwiftUI → rerun script → user reloads.

Deploy prerequisites

• One-time interactive: npx surge login (or CI-style env vars

SURGE_LOGIN + SURGE_TOKEN; token from npx surge token).

• Check auth non-interactively: npx surge whoami.

Setting up in a new project

Create the three pieces per the architecture above, adapted to the project:

• test target name in -only-testing:, scheme, and simulator destination in the script;
• scenario registry mirroring the project's #Preview blocks;
• SURGE_DOMAIN default in the script (<project>-gallery.surge.sh).

Script skeleton: render test → assert PNGs exist → emit gallery/index.html (grid of <figure><img></figure>, -apple-system font, dark-mode friendly) → npx --yes surge gallery $SURGE_DOMAIN when --deploy is passed. Verify with: run the script, confirm PNG count > 0 and open gallery/index.html.