iOS Snapshots

Upload requirements

Emerge's snapshot testing works by automatically parsing all of the Xcode previews present in your app binary, and then instantiating them on a real simulator to generate images. This means the build must contain all the relevant code and resources needed to render each preview.

If expected previews aren't showing up, we recommend:

  1. Ensure you are submitting a Debug configuration build. By default this disables features like Dead code stripping which can remove previews the linker thinks are unused.
  2. Confirm no linker settings like Dead code stripping are turned on manually for your build configuration.
  3. Check for any conditional preprocessor directives that might be preventing previews from compiling, e.g. #if SOME_FLAG.
  4. If your app is composed of dynamic frameworks, check if any have differing build settings.

Other requirements

The app must support arm64 devices.

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.

Supported types

Snapshot testing works with anything represented by a PreviewProvider or #Preview macro.

This includes SwiftUI's View, and UIKit's UIView and UIViewController.

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()
            .preferredColorScheme(.dark)
            .previewDisplayName("Dark")
    }
}

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

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 default .device layout will result in a full screen preview. We recommend using a .fixed or .sizeThatFits layout 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

Code Coverage

Snapshot tests automatically generate code coverage reports as a ".profdata" file if your uploaded binary is built with code coverage information included. This ".profdata" file can be downloaded via:

http://api.emergetools.com/snapshots?uploadId=[your_upload_id]

Enabling coverage requires settings -profile-generate -profile-coverage-mapping in OTHER_SWIFT_FLAGS and -fprofile-instr-generate in OTHER_LDFLAGS. For an example, see this PR . To check if an app has code coverage information, look for the LLVM_COV segment in the binary.