Documentation

Swift Snapshot Testing

Suggest Edits

The Emerge CLI has native support for PointFree's swift-snapshot-testing library. It's common for teams to have a preexisting set of snapshots from other tools such as swift-snapshot-testing, paparazzi, roborazzi, etc. While we recommend migrating to Emerge Snapshots for everything, we also don't want you to lose what you already have! Uploading your own set of snapshot images is supported using the Emerge CLI .

Getting started

1. Install the Emerge CLI

Follow the installation steps in our CLI repository.

2. Get an API token

Follow the instructions on how to obtain an API token to the Emerge API. We recommend storing this token in an EMERGE_API_TOKEN environment variable for automatic detection by our tooling.

3. Update your .gitignore

Once you start uploading snapshot images to Emerge, you no longer have to track them in your repository since we store them for you. You can update your .gitignore file with a rule to exclude them:

**/__Snapshots__/**/*.png

and you may have to manually remove them from git: git rm -r --cached "your/project/__Snapshots__"

4. Generate your snapshot images

swift-snapshot-testing requires you to run your tests in "record" mode in order to generate new images. We recommend that you record new snapshots on every commit in CI. For example, in your XCTestCase you can always record snapshots by overriding how tests are invoked:

  override func invokeTest() {
    // Always record new snapshots
    withSnapshotTesting(record: .all) {
      super.invokeTest()
    }
  }

One important note is that recording will cause all snapshot test cases to fail, which might terminate your CI workflow early. In Github you can work around this by enabling continue-on-error: true:

- name: Generate new snapshots
  run: |
    xcodebuild test \
      -scheme HackerNews \
      -destination 'platform=iOS Simulator,name=iPhone 14' \
      -only-testing:HackerNewsTests/SwiftSnapshotTest
  continue-on-error: true

5. Upload to Emerge

With everything now configured, use the CLI to perform the upload:

emerge upload snapshots \
  --name "AwesomeApp swift-snapshot-testing" \
  --id "com.emerge.awesomeapp.swift-snapshot-testing" \
  --repo-name "EmergeTools/AwesomeApp" \
  --client-library swift-snapshot-testing \
  --project-root /my/awesomeapp/ios/repo

A full list of options can be displayed by calling emerge upload snapshots -h, but there are a few worth calling out:

  • --namecontrols the display name of the job and is what will appear in our status check and website
  • --idneeds to be a unique identifier for your snapshots different than your regular app ID, since we use this ID as a lookup to distinguish between apps within your organization. We recommend adding a suffix to your regular app ID. For example, com.emerge.awesomeapp becomes com.emerge.awesomeapp.customsnapshots
  • --repo-nameis the full name of your repo, e.g. EmergeTools/AwesomeApp. This allows us to post pull request comments and status checks.
  • --shaspecifies the current Git commit SHA. This field is important for snapshot diffs to work properly. By default we attempt to autodetect this for you.
  • --base-sha specifies the Git SHA for the main branch commit used as the merge-base for the current branch. This field is important for snapshot diffs to work properly. By default we attempt to autodetect this for you.

Example workflow

You can explore our open-source HackerNews repo for a full working example. For example, this workflow uploads both Emerge snapshots and swift-snapshot-testing snapshots.

Updated 9 days ago