---
updatedAt: 2025-02-20T16:08:48.000Z
agentTools:
  projectIndex: https://docs.emergetools.com/llms.txt
---

# Integrate Emerge Snapshots for iOS with Github Actions

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 Xcode for regular feature development.

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

<Image align="center" src="https://files.readme.io/e92fb0b0d12e97bd88f25b8eff7308756d45a09a44deb1c0172c152374f712d9-diff.gif" />

# Integration Steps

1. Create free account at [emergetools.com](https://emergetools.com)

2. 1. Go to your [Emerge profile](https://www.emergetools.com/profile) by clicking your email in the bottom left corner of the sidebar on emergetools.com

      <Image align="center" src="https://files.readme.io/4d1b9737659aa00cfb2351cc586b3491423c81823e6b87589f916ae62aefb261-Screenshot_2025-01-27_at_14.03.13.png" />

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

      <Image align="center" width="400px" src="https://files.readme.io/83c4c2bf81cd8faab2462fb6e1354da42a498645b3e6aaf3902f9503d9a1afbc-image.png" />

   [Here are more details](https://docs.emergetools.com/docs/github) 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`

   <br />

   <Image align="center" border={false} caption="`https://github.com/<your-org>/<your-repo>/settings/secrets/actions`" src="https://files.readme.io/043747f8895d91c18162ec6364e85c103639d1a891d3293180064df0ccf0c0d9-repo-secrets.png" width="600px" />

3. Install the Emerge Fastlane Plugin:

   ```shell
   fastlane add_plugin emerge
   ```

4. Add the following lane to your `Fastlane/fastfile` replacing `<my-scheme>` with your app’s scheme used for Debug builds.

   ```shell Fastlane/fastfile
     desc "Build and upload snapshot build to Emerge Tools"
     lane :build_upload_emerge_snapshot do
       emerge_snapshot(scheme: "<my-scheme>")
     end
   ```

5. Add the following to your Github workflow that runs on PRs and the main branch.

   ```yaml .github/workflows/upload-ios-snapshots.yml
   - name: Upload to Emerge for Snapshot
     run: bundle exec fastlane build_upload_emerge_snapshot
     env:
       EMERGE_API_TOKEN: ${{ secrets.EMERGE_API_TOKEN }}
   ```

6. 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.

   <Image align="center" border={false} caption="Emerge Snapshots comment on first successful integration" src="https://files.readme.io/0531ddc1802102f345d7a1c0816be2700ce1af9c87d0a8480efd124af174258e-Screenshot_2025-02-19_at_14.19.24.png" />

Emerge's snapshot testing works by automatically parsing all of the Xcode previews present in your app binary, and then instantiating them on a real simulator to generate images. This means the build must contain all the relevant code and resources needed to render each preview.

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.

<Image align="center" border={false} caption="[Example PR with modified snapshots](https://github.com/EmergeTools/hackernews/pull/356)" src="https://files.readme.io/cda58e993d2b285e6d5a3901081e53139e98f5b975df30e8999ca053388bca3d-image.png" />

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

<Image align="center" border={false} caption="Failed Snapshot check on a Github PR" src="https://files.readme.io/bfba645525960486f81982a2b17899b33566db805e8b341fb974a676057c1dc2-Screenshot_2025-01-30_at_16.05.28.png" />

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.

<Image align="center" border={false} caption="[Emerge Snapshot diff viewer](https://www.emergetools.com/snapshot/804d5a66-6192-47e6-a42c-3d3a9fcd94e3?tab=changed)" src="https://files.readme.io/6f53f1c65ad5925757242ba72b466944235f57f45c37c6205bd44594f8fbd14d-Screenshot_2025-02-06_at_18.07.45.png" />

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

For more information and for more advanced configuration scenarios [click here](https://docs.emergetools.com/docs/ios-snapshots) for our full iOS Snapshots documentation. If you need any help, please [contact our team](mailto:support@emergetools.com).