Excluding snapshots

Occasionally you might have a snapshot that you only want to use locally and not be tracked by Emerge. We provide multiple options to exclude snapshots from our test results.

iOS

Config file

We support packaging an emerge_config.yaml file inside the top-level directory of your xcarchive uploaded to our site. In this configuration file, you can specify to exclude based on an exact match or regex match. This solution is the most flexible if you want to exclude an entire range of snapshots, say from a third-party dependency you are linking against.

The schema for this YAML file is as follows:

version: 2.0
snapshots:
  ios:
    runSettings:
      - osVersion: 17.2
        excludedPreviews:
          - type: exact
            value: TestModule.TestPreviewProviderType1
          - type: exact
            value: TestModule.TestPreviewProviderType2
          # For preview macros there is a special syntax
          - type: exact
            value: SomePreviewMacroFileId:SomeDisplayName
          - type: exact
            value: AnotherPreviewMacroFileId
          - type: regex
            value: ^TestModule.*$
        envVariables:
          var1: 1
          var2: 2
          var3: 3
        # Use arguments for pseudolanguages like double length strings
        arguments:
          - -NSDoubleLocalizedStrings
          - "YES"

In code

If you want to exclude directly within your Preview code, you can copy the following extension:

extension View {
  @ViewBuilder func emergeDisabled() -> some View {
      if ProcessInfo.processInfo.environment["EMERGE_IS_RUNNING_FOR_SNAPSHOTS"] == "1" {
        EmptyView()
      } else {
        self
      }
  }
}

Note that your the preview's body property will still need to be evaluated without any errors for this to work. If the preview crashes when running it will need to be excluded with the yaml file instead.

Android

Emerge provides the ability to ignore specific snapshots through the @IgnoreEmergeSnapshot annotation. Since these annotations need to live in the source set of the preview (by default the main source set), Emerge ships this annotation as part of a separate, snapshots-annotations library. You'll need to include this as an implementation dependency in whatever soruce set you're intending to ignore snapshots.

As an example, to ignore a Preview in the main source set:

// /src/main/com/myapp/MyComposable.kt

@IgnoreEmergeSnapshot
@Preview
@Composable
fun MyComposablePreview() {  
  MyComposable(  
    text = "Hello, World!"  
  )  
}

And add snapshots-annotations dependency as a debugImplementation dependency, as Previews are only included in debug builds:

dependencies {
  // ...

  debugImplementation("com.emergetools.snapshots:snapshots-annotations:<latest_version>")
}