Emerge's Snapshots product allows mobile teams to confidently ship UI changes in their app and be notified of regressions before they make it to production — without maintaining any extra test suites or code — by re-using the same Previews you write in Android Studio for regular feature development.

This guide shows how to get started with Emerge's Snapshots Testing for Android using Github and Github Actions so you can easily and visually see the changes you are making to your app's UI.

Integration Steps

1. Create free account at emergetools.com

2. 1. Go to your Emerge profile by clicking your email in the bottom left corner of the sidebar on emergetools.com.

      

   2. Add the Emerge App your Github repository by clicking Connect under GitHub Connection.

      

      More details on configuring the GitHub app and for GitHub enterprise.

   3. Create an Emerge API key by clicking the Generate API Key button in the Organization Settings section of your Emerge profile.

   4. Add EMERGE_API_TOKEN as a Repository Secret to your Github repository in the repo setting.
      https://github.com/<your-org>/<your-repo>/settings/secrets/actions

   
   

   

3. Apply the Emerge Gradle Plugin to the plugins block of your application module's build.gradle(.kts) file:

   build.gradle.ktsbuild.gradle

   plugins {
    id("com.emergetools.android") version "x.y.z"
   }

   plugins {
    id 'com.emergetools.android' version 'x.y.z'
   }

   Latest Emerge Android Gradle Plugin

   For more information on the Emerge Gradle Plugin, see our our documentation.

4. Execute the emergeUploadSnapshotBundleDebug task with the EMERGE_API_TOKEN environment variable in your Github Actions workflow in order to run the task on both PR builds and master builds.

   Configure your workflow to execute this task with the push trigger for your base branch and the pull_request trigger for your pull request. Here is a full example

   .github/workflows/android-emerge-snapshots.yml

   name: Upload Emerge Snapshot Bundle
   run: ./gradlew emergeUploadSnapshotBundleDebug
   env:
     EMERGE_API_TOKEN: ${{ secrets.EMERGE_API_TOKEN }}

5. Submit those changes as a pull request. The pull request will run a check that creates snapshots. Click on the Checks tab in the GitHub pull requests and click on Emerge Tools then Snapshot Test | Emerge and you should see something that looks like the screenshot below. This means you have successfully integrated snapshot testing in your repository. Once the PR is merged to the main branch the automatic checks will start working on all future PRs.

Using Snapshots

Emerge's Snapshots works by finding all the @Preview annotated methods in your project and creating snapshots from them. These functions are called by Emerge Tools on every PR and main branch build in order to generate snapshots. Emerge Tools saves these snapshots on our servers to use for comparison.

Whenever any snapshots are added, removed or modified in a PR relative to the respective base build, you will get a comment on your PR. The comment will show you what has changed and you can click it for further details.

By default, Snapshot modifications will fail a check on the PR like below.

You can click details to understand what changes were made to your snapshots.
If they were accidental, you should fix them in the code. Otherwise, if the changes were intentional, you can set this check to green by clicking details and then approving the changes from within the Emerge Tools UI.

You should be all set with Emerge Snapshot testing to be able to confidently ship UI changes!

For information and for more advanced configuration scenarios click here for our full Android Snapshots documentation. If you need any help, please contact our team.