Introducing a Gradle plugin for Screenshotbot

Screenshotbot has always been easy to integrate in Android. We now introduce our new Gradle plugin that makes it even simpler for Android teams to integrate their projects using existing screenshot testing libraries. In addition, it simplifies some workflows that developers use locally during development.

If you haven’t tried Screenshotbot before, here’s a quick primer: Screenshotbot is a platform-agnostic screenshot testing service. We don’t care how you generate your screenshots, as long as you can provide us a directory of screenshots. Once you upload them to us with the scripts we provide, we will compare it against an appropriate base commit, and notify you on the appropriate channel (e.g. a Pull Request or Slack). In particular, we are used by small and large Android, iOS and Web teams.

Library Support

Our Gradle plugin supports most of the popular Android screenshot testing libraries:

• Cashapp’s Paparazzi
• Facebook’s screenshot-tests-for-android
• Pedro Gómez’ Shot
• Takahiro Menju’s Roborazzi
• Dropbox’s Dropshots

Local Runs

We recently introduced a Local Runs mode for Screenshotbot. Before this feature, even though teams used Screenshotbot in their CI, developers had to use the record/verify provided by their screenshot testing library when iterating locally. Screenshotbot’s Local Runs lets developers use a single workflow for both CI and local development, and they also can take advantage of our powerful image comparison tools.

It also reduces the context switching as people switch between different screenshot testing libraries.

Quick Setup and testing Local Runs

It’s pretty straightforward to install our plugin. Just include it in your your build.gradle:

plugin {
  id "io.screenshotbot.plugin" version "1.9"
}

And that’s really it! The plugin will detect which screenshot testing libraries are being used, and generate appropriate tasks. The plugin does not change the behavior of any existing tasks, so it should be safe to add this plugin while migrating to Screenshotbot.

The plugin provides three tasks (which are named slightly differently for each screenshot testing library). We have a record and a verify task, and a CI task for automating the CI process.

For the rest of this discussion, we’ll focus on Paparazzi.

If you run gradle tasks, you’ll now see that our plugin has added the new tasks, for each Paparazzi flavor combination.

Once you fully migrate to Screenshotbot, you’ll no longer have any images stored in Git or GitLFS. But our plugin handles the case if you still have screenshots stored: we just never verify screenshots against screenshots saved in the repository.

Instead the developer can choose to record the screenshots at any point of time by running gradle recordPaparazziDebugScreenshotbot. The recorded screenshots are not tied to any git commit, so the developer can run this even during incremental refactoring steps.

To check that no screenshots changed you will run gradle verifyPaparazziDebugScreenshots. If nothing changes, this will pass. If something changed, the task will fail and you’ll see a link to screenshotbot.io with the report of changes. At this point you could choose to re-record, or revert your latest changes.

We also made it easy for developers to install their API keys by running gradle installScreenshotbot: this step will just direct you to a URL to get a key and paste it back. (If you haven’t created an account with us yet, running this step will guide you through the process.)

Using the plugin in CI

In the past, we suggested that people integrating with these libraries should add all their screenshots to .gitignore, call the screenshot testing library’s record step in CI, and then call the script we provide.

The Gradle plugin streamlines this process further.

If you previously called gradle verifyPaparazziDebug on CI, you just change it to gradle recordAndVerifyPaparazziDebugScreenshotbotCI. That’s it. In most cases, our script will read environment variables from your CI to correctly figure out all the details we need such as whether this is a Pull Request or main branch commit etc.

What’s next

We chose to build this plugin because of the fantastic feedback we get from our users. If you think there’s another common configuration that we could automate, please let us know! In particular, we are working on Fastlane plugins for iOS developers.

If you’re using a screenshot testing library that’s not listed above, we’ll be happy to add it. It usually doesn’t take a lot of work for us to add an integration.

This Gradle plugin is also pretty new, so if you do see bugs, please reach out to support@screenshotbot.io, we’re pretty good about responding to issues quickly.