Local Runs

If you've configured Screenshotbot to run on CI, developers need not have to run Screenshotbot themselves. Most libraries that generate screenshots have a mechanism to record and verify screenshots, and this mechanism can be used during development to locally test UI changes.

However, there are some cases where this is insufficient.

• Custom image generation code

  If you have a custom pipeline to generate screenshots, you might not want to create a record/verify code from scratch.

• Improve productivity from context switching

  Teaching developers to use multiple tools along with Screenshotbot can be confusing.

For these reasons, Screenshotbot provides a record/verify flow that your developers can run locally, with your familiar Screenshotbot UI for image comparisons.

Setting up

Each developer will need to create their own API key and API secret. They then need to set up environment variables locally:

      # Add to .bashrc
      export SCREENSHOTBOT_API_KEY=...
      export SCREENSHOTBOT_API_SECRET=...

Finally, developers need to install the Screenshotbot CLI tool locally:

        curl https://cdn.screenshotbot.io/recorder.sh | sh

          PS C:\> curl https://screenshotbot.io/recorder.exe -O recorder.exe

Recording Screenshots

To record a directory of screenshots, you can run the following command:

      $ ~/screenshotbot/recorder dev record --directory path/to/screenshots --channel ...channel-name...

This command always succeeds and sets the "golden" screenshots for the given channel.

Note that this command is unaware of Git commit hashes or branches. If you change branches, you might need to re-record the screenshots against the base of the branch, or use a different channel name.

Verifying Screenshots

As your work along the branch progresses, you can keep verifying your screenshots with the following command:

      $ ~/screenshotbot/recorder dev verify --directory path/to/screenshots --channel ...channel-name...

If no screenshots have changed, this will exit with a success code.

If screenshots have changed, this will exit with an error code and output a link to a comparison page:

      [15:06:35] INFO : 1 changes
      [15:06:35] INFO : See changes at https://screenshotbot.io/runs/.../compare/...

The comparison page is identical to the comparison pages you see on Pull Requests.

If you are happy with the changes, you can re-record the current state and keep working on your branch.

Using the Gradle Plugin

If you're on Android, and using the Gradle plugin, we provide Gradle tasks that wrap the above process.

Initially, you will need to install an API key with:

      $ ./gradlew :installScreenshotbot

This will take you through a flow to install an API key for Screenshotbot. You only need to do this once.

After that, if you are using Paparazzi, you can run the local record step as:

      $ ./gradlew :app:recordPaparazziDebugScreenshotbot

And you can run the local verify step as:

      $ ./gradlew :app:verifyPaparazziDebugScreenshotbot

Wrapping the tooling

We suggest wrapping the above commands with your the build system that you are using.

      $ ./gradlew :app:recordScreenshotbot

This task will be able to automatically infer the channel name and the directory to use, and reduces the friction for the developer.

Contact us for templates of such wrappers for the build system you are using.