Swift Snapshot Testing
The Emerge CLI has native support for PointFree's swift-snapshot-testing library. 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:
**/__Snapshots__/**/*.png
and you may have to manually remove them from git: git rm -r --cached "your/project/__Snapshots__"
4. Generate your snapshot images
swift-snapshot-testing
requires you to run your tests in "record" mode in order to generate new images. We recommend that you record new snapshots on every commit in CI. For example, in your XCTestCase
you can always record snapshots by overriding how tests are invoked:
override func invokeTest() {
// Always record new snapshots
withSnapshotTesting(record: .all) {
super.invokeTest()
}
}
One important note is that recording will cause all snapshot test cases to fail, which might terminate your CI workflow early. In Github you can work around this by enabling continue-on-error: true
:
- name: Generate new snapshots
run: |
xcodebuild test \
-scheme HackerNews \
-destination 'platform=iOS Simulator,name=iPhone 14' \
-only-testing:HackerNewsTests/SwiftSnapshotTest
continue-on-error: true
5. Upload to Emerge
With everything now configured, use the CLI to perform the upload:
emerge upload snapshots \
--name "AwesomeApp swift-snapshot-testing" \
--id "com.emerge.awesomeapp.swift-snapshot-testing" \
--repo-name "EmergeTools/AwesomeApp" \
--client-library swift-snapshot-testing \
--project-root /my/awesomeapp/ios/repo
A full list of options can be displayed by calling emerge upload snapshots -h
, but there are a few worth calling out:
--name
controls the display name of the job and is what will appear in our status check and website--id
needs 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
becomescom.emerge.awesomeapp.customsnapshots
--repo-name
is the full name of your repo, e.g.EmergeTools/AwesomeApp
. This allows us to post pull request comments and status checks.--sha
specifies 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 swift-snapshot-testing snapshots.
Updated 13 days ago