skip to content

In SwiftUI, what does a snapshot test of a login screen's error state check, and why do such tests break when the code has not changed?

level: middleimportance: should knowfreq 45%

answer

  1. pixels against a stored reference
  2. ImageRenderer from iOS 16
  3. everything the environment decides
  4. the toolchain draws text too

basics

~20 s

A snapshot test renders a view in a fixed state and compares the image with a stored reference to catch visual change. It breaks without code changes when the OS, simulator, scale, color scheme, text size or locale differs from the recording.

solid answer

~50 s

A snapshot test puts a view into a known state, renders it to an image and compares that image, pixel by pixel or within a tolerance, with a reference recorded earlier. It catches visual regressions such as a clipped label or a wrong color; it says nothing about behaviour, which the model tests cover. Apple's API for rendering a view to an image is `ImageRenderer` (iOS 16), which gives a `uiImage` or `cgImage`; third-party snapshot libraries add recording and diffing. The tests break with no code change because the image depends on more than your code: the OS and Xcode version that draws text, the simulator's scale, and environment values like `colorScheme`, `dynamicTypeSize` and `locale`. Pin all of those, render at a fixed width and `scale`, feed the view finished data, and re-record deliberately when the toolchain changes.

code

swift · 23 lines
swift
import SwiftUI

struct LoginErrorBanner: View {
    let message: String
    var body: some View {
        Label(message, systemImage: "exclamationmark.triangle")
            .padding()
            .background(.red.opacity(0.15))
    }
}

@MainActor
func renderBanner(dark: Bool, size: DynamicTypeSize) -> Data? {
    let banner = LoginErrorBanner(message: "Email or password is wrong.")
        .environment(\.colorScheme, dark ? .dark : .light)
        .environment(\.dynamicTypeSize, size)
        .environment(\.locale, Locale(identifier: "en_US"))
        .frame(width: 390)

    let renderer = ImageRenderer(content: banner)
    renderer.scale = 3   // fixed, not the device's
    return renderer.uiImage?.pngData()
}

go deeper

for a junior

Recall the three steps of a snapshot test and that it checks appearance, not behaviour.

for a middle

Explain how ImageRenderer renders a view, which environment values to pin, and why the documented placeholder limit matters for complex containers.

for a senior

Diagnose a snapshot that fails only on CI by listing what differs between recording and running, and fix it by pinning rather than loosening tolerance.

for a principal

Weigh the cost of maintaining references against the regressions they catch, and choose which states earn a snapshot.

## What a snapshot test is A **snapshot test** has three parts: 1. **Arrange a state**: build the view with fixed data, for example a login error banner with "Email or password is wrong.", or the whole screen with a fake service that fails. 2. **Render to an image** at a fixed size and scale. 3. **Compare** with a **reference image** recorded earlier and stored with the tests. If they differ beyond a tolerance, the test fails and usually writes a diff image. What it checks is **appearance**: layout, clipping, colors, fonts, spacing, which elements are visible. A wrong rule in the model can still produce a correct-looking screen, so snapshot tests complement model unit tests rather than replace them. ## Rendering a SwiftUI view: `ImageRenderer` Apple's API for turning a view into an image is `ImageRenderer`, available since iOS 16. You create it with `ImageRenderer(content:)`, set `scale` and optionally `proposedSize`, then read `uiImage` or `cgImage`, or call `render(rasterizationScale:renderer:)` to draw into any `CGContext`. Its members are main-actor-isolated, so the rendering code runs on the main actor. Apple's documentation sets one important limit: `ImageRenderer` output only includes views SwiftUI draws with its own primitives, such as text, images, shapes and composites of them. Views whose contents are composited by Core Animation layers, such as **more complex controls and containers, web views, media players and most UIKit-backed views**, come out as a placeholder. The documentation adds that support may change in future releases, but a view that is supported now stays supported. That is why many snapshot libraries instead host the view in a hosting controller inside a window and capture that, and why a component-level snapshot of a banner works better with `ImageRenderer` than a full `Form`. ## Why snapshots break when nothing changed The rendered pixels depend on far more than your Swift code: | Source of drift | Example | How to pin it | |---|---|---| | OS and Xcode version | text antialiasing or a system font revision | record and run on one simulator runtime; re-record on upgrade | | Device scale and size | 2x vs 3x, a different width | set `renderer.scale` and a fixed `frame(width:)` | | Color scheme | the test host is in dark mode | `.environment(\.colorScheme, .light)` | | Dynamic Type | the host has a larger text size | `.environment(\.dynamicTypeSize, .large)` | | Locale and direction | dates, numbers, right-to-left | `.environment(\.locale, ...)`, `.environment(\.layoutDirection, ...)` | | Live data | the current date, a remote image still loading | fixed data and a fake service | The last row matters for SwiftUI in particular: a screen that loads in `.task` or shows an `AsyncImage` is better snapshotted from a **state where loading has already finished**, because a one-shot render is not something to rely on to wait for async work. ## Component or full screen Two granularities are common, and they fail differently: - **Component snapshots** (the error banner, a row, a button style) are small, render well with `ImageRenderer`, and fail for one reason at a time. They suit a design system. - **Screen snapshots** catch how components combine (spacing, overlap, a toolbar hiding content), but they need the whole screen hosted, they change whenever any part changes, and they include containers `ImageRenderer` may not draw. Most teams start with components and add a few screen snapshots for the states where composition is the risk. ## Keeping the suite trustworthy - **Snapshot states, not screens at random**: empty, error, loading, long text, the largest Dynamic Type size, dark mode. Each one is a deliberate case. - **Keep references reviewable**: a failing test should produce the reference, the new image and a diff, and the pull request shows them. - **Use a small tolerance when the pipeline needs it**, but know that a loose tolerance hides real one-pixel regressions such as a hairline border disappearing. - **Re-record on purpose**: after an Xcode or OS upgrade, re-record everything in one change and review the diffs, rather than accepting failures test by test. - **Keep the count small**: dozens of well-chosen states beat hundreds of near-duplicates nobody reviews. ## Common mistakes - Expecting a snapshot to catch a logic bug in the view model. - Recording on one developer's machine and running on CI's different simulator. - Letting the test inherit the host's appearance settings. - Snapshotting a screen while its data is still loading.

  • Why might ImageRenderer produce a placeholder instead of your full login Form?
    Apple's documentation says `ImageRenderer` includes only views SwiftUI draws with its own primitives, like text, images and shapes. Views composited by Core Animation, such as more complex controls and containers and most UIKit-backed views, render as a placeholder. Snapshot a component made of supported views, or use a snapshot approach that captures a hosted window.
  • When should a team re-record its snapshot references?
    When the rendering environment changes on purpose, such as a new Xcode or simulator runtime, or when a design change is intended. Re-record everything in one dedicated change and review the diffs, so an accidental regression is not accepted along with the expected ones.

A snapshot test is like a print shop comparing each new print against the signed-off proof: any difference is caught, but the shop cannot tell whether the change was a mistake or a deliberate redesign. A human reviews the diff.

  • Snapshot tests replace unit tests of the view model
  • ImageRenderer renders any SwiftUI view, including web views, exactly as on screen
  • A failing snapshot after an Xcode upgrade means the code broke
  • Letting the test inherit the simulator's color scheme and text size is fine
  • Raise the tolerance until the flaky snapshot passes