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.


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: 1.0
      - 17.2
      - 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.*$
      var1: 1
      var2: 2
      var3: 3

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" {
      } else {

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.


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

fun MyComposablePreview() {  
    text = "Hello, World!"  

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

dependencies {
  // ...