Roborazzi

The Emerge CLI has native support for Roborazzi . 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:

build/outputs/roborazzi/**/*.png

and you may have to manually remove them from git: git rm -r --cached "build/outputs/roborazzi".

4. Generate your snapshot images

Roborazzi requires you to generate new images via their recordRoborazziDebug Gradle task. We recommend that you record new snapshots on every commit in CI. For example:

./gradlew :app:recordRoborazziDebug

5. Upload to Emerge

With everything now configured, use the CLI to perform the upload on the generated snapshot images:

emerge upload snapshots \
  --name "AwesomeApp Roborazzi" \
  --id "com.emerge.awesomeapp.roborazzi" \
  --repo-name "EmergeTools/AwesomeApp" \
  --client-library roborazzi \
  --project-root /my/awesomeapp/android/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 Roborazzi snapshots.