Providing Previews

Snapshot testing automatically finds all SwiftUI previews in your app and generates snapshots for each preview. This process tests your previews to ensure they all render without errors. Ensure your previews are included in uploads to Emerge to support snapshot testing, often this means uploading a debug build. Snapshots require the upload to be an XCArchive and the app to be built for arm64.

The app is re-signed before running for preview extraction, so it needs to be able to run without entitlements. For example, app groups and associated domains entitlements are removed.

UIKit

Snapshots support both SwiftUI and UIKit, to make your snapshots visible to Emerge they need to be accessible from a PreviewProvider. To snapshot a UIKit view, return it from your PreviewProvider using UIViewRepresentable.

Preventing Flakiness

To reliably detect differences in images and prevent flaky diffs, each preview needs to render reproducibly. You can check if the environment variable EMERGE_IS_RUNNING_FOR_SNAPSHOTS is set to 1 to enable overrides such as mocking potentially volatile data. Commonly this applies to build versions, random numbers, or network responses. To help control for flakiness http requests through NSURL are blocked while generating snapshots, and the current time is mocked so NSDate will always return a constant time.

Components and Variants

Each PreviewProvider type is a single component, but can provide multiple variants. For example if your code looks like this:

struct MyComponent_Previews: PreviewProvider {
    static var previews: some View {
        MyView()
            .previewDisplayName("Light")
        MyView()
            .colorScheme(.dark)
            .previewDisplayName("Dark")
    }
}

Then MyComponent will have two variants, named Light and Dark. When a component has multiple variants we recommend specifying the names so they can be easily distinguished when viewing the generated snapshots.

Automatic Variants

If your app supports dark mode or dynamic type, let us know if you want automatic generation of variants. For every variant in your binary, Emerge can create one in dark mode and one in light mode, or any combination of dynamic type settings.

Device Variants

Snapshot Testing has support for 3 devices:

• iPhone 11 Pro Max
• iPhone 8
• iPad Air (5th generation)

You can define the preview device with .previewDevice().

struct MyComponent_Previews: PreviewProvider {
    static var previews: some View {
        MyView()
            .previewDevice("iPhone 8")
        MyView()
            .previewDevice("iPad Air (5th generation)")
    }
}

By default the selected device is the iPhone 11 Pro Max, and if you have a different one, they will be mapped using the following rules:

• Any iPad (mini, Pro, Air) maps to iPad Air (5th generation).
• All iPhones with home button map to iPhone 8.
• Everything else will use the iPhone 11 Pro Max.

Layout

Emerge respects the preview layout in previewLayout() when generating snapshots. The .device layout will result in a full screen preview. An iPhone 11 Pro Max is always used as the device type for previews. Use a .fixed layout or .sizeThatFits to customize the dimensions of your snapshot.

Scroll Views

Scroll views are automatically expanded to a height that fits their contentSize. This only happens for the first scroll view discovered in a preview, and only for the height (not width). Layouts with a fixed size (PreviewLayout.fixed) will not be expanded.

Interface Orientation

Emerge can generate snapshots in both portrait and landscape orientations, respecting the selected orientation with previewInterfaceOrientation(). Keep in mind that interface orientation is different from device orientation, if your code is using the orientation, you must rely on the interface orientation provided by UIWindowsScene instead of UIDevice. A simple way to get it is with this code:

UIApplication.shared.windows
                .first?
                .windowScene?
                .interfaceOrientation

Rendering

Snapshots are rendered using CALayer’s render(in: Context). This doesn’t support all forms of com positioning, so UI elements such as Material blurs may not be visible. The presentationLayer is used when possible.

Code Coverage

Snapshot tests automatically generate code coverage reports as a ".profdata" file if your uploaded binary is built with code coverage information included. To test for code coverage information in the binary, look for the LLVM_COV segment in your binary.

Generate snapshots locally

Emerge also offers a Swift package generate snapshots locally for debugging.

• Install the Swift Package in your project
• Add a UI test target with SnapshottingTests as a dependency.
• Create your test that inherits from SnapshottingTests.PreviewTest

See the repo for full documentation.