Concepts

This document summarizes the basic concepts and terminology used in Screenshotbot.

A screenshot is just an image, usually a PNG, with associated metadata such as its name and debugging information.

A run is a collection of screenshots that are sent to Screenshotbot. Typically associated with a single CI build, but you may create multiple runs per CI build. For example, you might create one run for each build target in your repository.

A channel is an arbitrary tracking name associated with runs. For example, you might call your channel name example.com-ios-app.

The promoted run is the current run that’s going to be associated with the channel. You can consider it the current “golden” screenshots. The promoted run links to the previous promoted run and so on. We use this to get the history of a given screenshot. Certain runs may not get promoted, for example, if you re-run a CI build on the main branch, or if you have a run from a pull request.

A comparison is just comparing two runs. The runs could be from different channels. For example, you might compare screenshots from your staging server and your production server.

A report is a pre-generated comparison, that’s usually associated with some kind of notification. Each time any screenshots change on your main branch, we generate a report, and depending on your notification settings, we’ll notify you that the promoted screenshots have changed. We’ll also generate reports for Pull Requests/Merge Requests/Diffs, and in this case we’ll link to the report from your code review tool.

For Pull Requests (or for any non-main branch), we compare against the first known run on the merge-base to generate the report. In this case we don’t look at the promotion state of the run.

A Web Project is a project that is run by us, and not on your CI server. We generate screenshots against your publicly available website periodically, and create appropriate runs and reports. You can still test websites without our Web Project infrastructure, as long as you generate the screenshots yourself.

You might see us using the term screenshot and image. For now, you can disregard this distinction. But more precisely, an image is just the PNG file without the associated metadata such as name or commit information.