Documentation

Bring Your Own

Suggest Edits

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 .

Supported libraries

The CLI has special native support for the following libraries, follow the specific guides for each.

📘

Swift Snapshot Testing

📘

Roborazzi

📘

Paparazzi

Getting started

If you aren't using one of the specific libraries, the CLI also supports uploading an arbitrary directory of images. First, install the CLI following the instructions in the repository .

Once installed, snapshots can be uploaded via the emerge upload snapshotscommand. Here's an example:

emerge upload snapshots \
  --name "AwesomeApp Snapshots" \
  --id "com.emerge.awesomeapp.customsnapshots" \
  --repo-name "EmergeTools/FakeRepo2" \
  /path/to/snapshot/images

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.

CI example

To understand how this all comes together in CI, we recommend checking out the Github Workflows for our HackerNews app.

iOS Workflow

Android Workflow

Each workflow has a job to upload a set of Emerge generated snapshots and non-Emerge snapshots. After snapshots have been uploaded you will see a status check summarizing them:

And viewing the Details shows a full breakdown by app ID:

Updated 1 day ago