✨ Render SwiftUI #Previews with Vizzly - #351
Merged
Merged
Conversation
Render existing stock #Preview declarations from the built app target through a Simulator-injected Swift runtime. Add the Vizzly CLI plugin, two-preview fixture, manifest output, and repeatable end-to-end coverage.
Select the device automatically when exactly one available iOS Simulator is booted. Keep ambiguous and stale-device cases explicit, actionable, and covered by the real preview capture path.
Harden the native renderer for real app targets, repeatable output, scheme selection, capture timeouts, and explicit compatibility failures. Ship the npm plugin through Swift releases, add CI coverage and complete fixture metadata, and verify package auto-discovery against a real iOS project.
Route native preview captures through the existing screenshot client for local TDD and cloud builds. Record upload outcomes, preserve explicit local-only capture, and cover the real HTTP boundary plus stock-preview naming and metadata.
Tighten managed output and plugin capability checks, run the native preview fixture during Swift releases, and replace duplicated Swift docs with focused XCTest and #Preview guides.
Move preview capture to a normal dynamic Swift Package dependency so Xcode owns building, embedding, and signing the runtime. Remove CLI injection and app mutation, add setup diagnostics, and prove the public integration on Simulator and device builds.
The macos-latest label moved to macOS 26, which no longer includes Xcode 16.2 or 16.4. Keep the existing compatibility matrix on the macOS 15 arm64 image where both toolchains are installed.
Keep successful captures when individual previews fail, support common layout traits, and make the beta installable through exact npm and SwiftPM release tags. Also repair the Swift CI runner and rebase drift against the current upload contract.
Robdel12
force-pushed
the
rd/swift-preview-sdk
branch
from
September 11, 2026 05:04
71f2aaf to
d39b206
Compare
The preview plugin uses the isolated screenshot service introduced in this branch. Require and document the matching CLI beta so a fresh PitStop install cannot silently select the older public CLI.
Remove the Swift-only screenshot service and use the CLI's established public client for local and cloud uploads. This keeps the plugin compatible with the published 0.36.0 CLI.
Robdel12
changed the title
Robdel12
changed the title
Let Xcode use its normal build products so repeated preview captures are incremental instead of paying for a clean build on every run.
Add the shared --include glob convention and resolve preview names in one lightweight app launch so local iteration renders only the requested previews.
Render preview registries in one Simulator process and relaunch only after a crash or timeout. Keep filtering in the same launch, preserve completed screenshots across recovery, and verify the workflow with an intentional crashing preview.
Document batched process reuse, progress-based timeouts, and the deterministic-data requirement for async preview content.
Clarify that preview capture is opt-in and leaves the existing XCTest products unchanged. Keep the preview guide direct, trim unreleased implementation history, and include every linked guide in the npm package.
Keep plugin documentation in the Swift package, remove prerelease installation language, and describe only the implementation that ships. The Swift release workflow now publishes a normal stable release.
Use the production 0.1.1 package version in the Swift guides. An exact rule prevents Xcode from selecting unrelated CLI tags from the shared repository.
Remove renderer internals and exploration context from the public guides. Keep the install, capture, upload, CI, safety, and troubleshooting steps users need.
Show Swift preview defaults inside the normal Vizzly config and keep shared comparison settings at the top level.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Vizzly's Swift SDK can capture screenshots from UI tests, but it cannot render an app's SwiftUI
#Previewdeclarations directly. This adds that workflow while keeping the existingVizzlyandVizzlyXCTestAPIs and target dependencies unchanged.Approach
The
@vizzly-testing/swiftpackage registersvizzly previews. The command builds the selected app in Xcode's normal DerivedData, reads its generated preview registries, and usesVizzlyPreviewRuntimeto render them in a booted Simulator. Apps add the runtime as a dynamic Swift Package product and install it once from the app initializer.Project, shared scheme, and Simulator selection are automatic when there is one clear choice.
--include <pattern>limits a run to one preview or a small group. Previews render in one app process, and Vizzly relaunches the app with the remaining work if a preview crashes or times out.Captured screenshots use the existing Vizzly paths: a project-local TDD server receives local runs, configured credentials create a cloud build, and
--no-uploadkeeps the PNGs and manifest local.Safety and support
Xcode builds, embeds, and signs the runtime as a normal package dependency. The CLI does not modify the built app or pass Vizzly credentials into the app process.
The app initializer and some scene lifecycle code can run during capture.
VizzlyPreviewRuntime.isCapturinglets apps skip services that should not run in that environment. Preview capture currently supports Xcode 26.6 on arm64 Macs, iOS 17 or newer Simulators, scene-based apps, fixed layouts, and portrait or landscape orientation traits.Evidence
The checked-in iOS fixture verifies preview discovery, name filtering, fixed-layout dimensions, repeat captures, safe output replacement, failure recovery, and uploads through the local Vizzly server. The JavaScript suite, Swift package suite, package checks, and real Simulator workflow pass.