Installation

This tool is packaged as a Ruby Gem which can be installed by:

gem install emerge

API Key

Follow our Uploading Basics guide on how to obtain an API key for your organization. The API Token is used by the CLI to authenticate with the Emerge API. The CLI will automatically pick up the API key if configured as an EMERGE_API_TOKEN environment variable, or you can manually pass it into individual commands with the --api-token option.

Git Configuration

For CI diffs to work in our products, Emerge needs the appropriate Git sha and base_sha values set on each command (if required). The CLI will attempt to automatically set these values for you, but depending on your setup you may need to explicitly provide the values.

Emerge will automatically compare a build at sha against the build we find matching the base_sha for a given application id. We also recommend setting pr_number, branch, and repo_name for the best experience. For example:

sha: pr-branch-commit-1
base_sha: main-branch-commit-1
pr_number: 42
branch: my-awesome-feature
repo_name: EmergeTools/hackernews

Commands

Snapshots

Uploads a directory of images to be used in Emerge BYO Snapshots.

Run emerge upload snapshots -h for a full list of supported options.

Example:

emerge upload snapshots \
  --batch \
  --name "Awesome App Snapshots" \
  --id "com.emerge.awesome.snapshots" \
  --repo-name "EmergeTools/AwesomeApp" \
  --client-library swift-snapshot-testing \
  --project-root . \

Client Libraries

We support automatic integrations with popular snapshot testing libraries such as swift-snapshot-testing, paparazzi, and roborazzi.

To get started with these, set the --client-libraryparam with the desired library, and set the --project-rootso we know which directory to begin searching from.

Reaper

Experimental support has been added to interactively examine Reaper results and also delete them from your codebase.

Use the reaper subcommand to get started, e.g.:

emerge reaper --id 40f1dfe7-6c57-47c3-bc52-b621aec0ba8d \
  --project-root /path/to/your/repo

After which it will prompt you to select classes to delete.

How it works

Under the hood we are using Tree Sitter to parse your source files into an AST. Once in an AST, we can associate our Reaper data and begin deleting nodes. There are some obvious limitations to this approach, namely that Tree Sitter is designed for source code editors and only looks at a single file at a time. So while it is good at deleting the type definition, it can struggle deleting code using that type. We are exploring some better long-term approaches to solve this.

Supported languages

We currently support the following languages:

• Swift
• Obj-C
• Kotlin
• Java

Please open an issue if you need an additional language grammar.