Swift Snapshot Testing

Screenshotbot integrates with the popular swift-snapshot-testing library. In this document we’ll walk you through the steps required to set up the integration.

You have two options:

• Use our fork of swift-snapshot-testing, which has default behaviors that handle both images and text snapshots seamlessly.
• Or use the upstream version, but create wrapper functions around assertSnapshot to always pass record: true, and use this wrapper function when taking snapshots of views/images.

Using our fork

Update your swift-snapshot-testing to point to https://github.com/tdrhq/swift-snapshot-testing. We try to keep this synced with the latest released version from upstream.

Once you use this fork, the test behavior changes:

• For non-image snapshots, the behavior is unchanged. This means that your text-based snapshots can co-exist with Screenshotbot.
• For snapshots that produce a png file, we will record the new image, but the tests will never fail: i.e. it won't fail if the snapshot has changed, and it won't fail if the image is not present.

Instead of having tests fail, we'll upload the png files to Screenshotbot in the next step (we will not upload during the test run). If you need to override this temporarily while developing a feature, you can set screenshotbotMode = false.

Next you need to add all the image snapshots to your .gitignore:

  **/__Snapshots__/**/*.png

Finally in your CI, you need to look find all __Snapshots__ directories, and upload them to Screenshotbot. In Fastlane, this might look like:

  lane :fetch_screenshotbot do
     sh "curl https://cdn.screenshotbot.io/recorder.sh | sh"
  end

  lane :screenshotbot_upload_all do
    # For each __Snapshots__ directory, load it to screenshotbot
    Dir.glob("../**/__Snapshots__/").each do |dir|
      channel_name = dir[3..-("/__Snapshots__/".length + 1)]
      sh "~/screenshotbot/recorder --channel #{channel_name} --directory #{dir} --recursive"
    end
  end

  lane :screenshotbot_ci do
    tests
    fetch_screenshotbot
    screenshotbot_upload_all
  end

You can now call bundle exec fastlane screenshotbot_ci instead of bundle exec fastlane tests from your CI.

For a full example of an integration using Fastlane and CircleCI, see this repository.

Using the upstream version of swift-snapshot-testing

To use the upstream version, typically our customers would create a new assertScreenshot function that calls into assertSnapshot with record: true.

Ideally, you also need to be override this for developers trying to verify screenshots locally, although developers could use our Local Runs feature instead.

  **/__Snapshots__/**/*.png

And finally you would update your CI to call the Screenshotbot CLI tool to upload all the screenshots. See the Fastlane script in the previous section for an example.

We'll add some sample code for this integration in the future. In the meantime, please reach out if you need help.

Next Steps

In order to get the full benefits of Screenshotbot we encourage you to integrate the scripts from above into your CI jobs, for example CircleCI or Bitrise.

To start with you could get notifications on Slack each time screenshots change.

Once you're comfortable with that you can then integrate with your Code Review platform of you choice (for example, GitHub), to get build statuses right on your Pull Request.