- Getting Started
- Code Review
- Platforms
- CI integrations
- Web Projects
- Developer Tools
- Get Notified
- API
The recorder command line tool is the primary interface for you to upload screenshots to Screenshotbot. It’s a simple script that you can run at the end of the tests. The source code for the script is available on GitHub.
You can build this script from the Open Source repository, or you can install the latest version at any time using the following command:
curl https://cdn.screenshotbot.io/recorder.sh | shThis will install the script at ~/screenshotbot/recorder. You may call this from your CI jobs. You’re welcome to use this script even if you’re using the open source version of Screenshotbot, however, we suggest you let us know so that we can ensure that our CDN can be optimized for your needs.
This installation process works for 64-bit Linux, and 64-bit Mac OS (both Intel and ARM). For any other platform (including Windows), please reach out to us, or build the binary from scratch from our Open Source repository.
When invoking from your CI, our command line tool will read environment variables to get most of the information we need automatically. Typically you need only the following two lines:
git fetch origin main
~/screenshotbot/recorder --directory path/to/screenshots/ --channel-name channelWe recommend the git fetch before calling our tool. On some CI frameworks, the main or master branch is not fetched when running a job on Pull Requests, and we use the main branch information to figure out which commit we should generate reports against. Please make sure you're passing the right branch that corresponds to the main branch.
If your main branch is not main or master you must pass it to the recorder tool using --main-branch branch-name argument.
This is the full list of CLI options (as seen with --help), we’ll go over the important details in the next section.
Screenshotbot Recorder script
Usage: recorder [options]
Use this script from your CI pipelines or locally to
upload screenshots and generate reports
We are currently migrating the commands from a single top-level
command to multiple subcommands. Use `recorder help` to get documentation
for subcommands.
Options:
--api-hostname Screenshotbot API Endpoint
--api-key Screenshotbot API Key. Defaults to $SCREENSHOTBOT_API_KEY.
--api-secret Screenshotbot API Secret. Defaults to $SCREENSHOTBOT_API_SECRET
--author Author for this run. Either in the form of "Full Name <email@example.com>" or just "email@example.com". The email is used to enforce review rules.
--batch Batch multiple channels into one single build status named by this
argument.
--browser-configs A YAML file that specifies the configuration of the
browsers. Please see documentation for details.
--build-url Build URL to easily identify build that generated this run
--channel Channel name for screenshot tracking. Defaults to `unnamed-channel`.
--commit-limit Limit the number of commits for which we upload commit hashes. This is
useful for large repositories (about > 10000 commits). For large
repositories, sending all the commit hashes will time out. The
uploaded graph is merged with the graph that the server already knows
of.
You should set this high enough so that Screenshotbot always has the
entire commit graph from the previous promoted run to the new run. A
value of about 1000 should be safe and relatively fast for most
people.
--compare-threshold Fraction of pixels that can be different for Screenshotbot to consider
the screenshots to be the same. (between 0.0 and 1.0)
We don't recommend using this unless absolutely required. Flaky
screenshots are harder to maintain long term. Using this argument can
also slow down the processig of your reports significantly.
If not specified, or if specified by 0.0, we'll consider screenshots
equal only if they are identical by file content. (e.g. any changes in
encoding, or EXIF data will cause a screenshot change.)
Keep in mind that this value will typically be very low. e.g., a
1000x1000 image, using 0.001 threshold would still allow for 1000
pixel changes which might be too high for most practical uses. You
probably want to choose this so that no more than 10-20 pixels are
allowed to be different at a time.
--create-github-issue Create a Github issue if enabled on your account
--desktop Whether running in desktop mode. In desktop mode the --hostname
defaults to http://localhost:4095, and authentication is disabled.
--directory Directory with the images.
By default we don't scan recursively, see the `--recursive` flag for that.
--finalize Notify Screenshotbot that all builds on all channels on this
commit are complete. This is not required to be called, but if
used provides a better developer experience when later builds
are waiting on this commit.
--firebase-output When running Android tests in Firebase Test Lab, pass the output of
the `gcloud firebase test android run` as a file to this option. We'll
automatically fetch the required files from Google Cloud, and clean
up the files from Google Cloud when we're done. We use the `gcloud`
command line tool so you must have already called
activate-service-account before this step.
--gitlab-merge-request-iid
GitLab merge request IID
--help
--image-file-types When scanning a directory, this is the list of file extensions
we consider as images. This defaults to `png`, but we support
PNG, WEBP, HEIC, JXL, JPG. We do not
recommend JPG or any other lossy formats. You can separate multiple
extensions with a comma.
--main-branch Git Branch of the main branch being tracked. We try first
`main` and then `master`, by checking for origin/<branch-name>
--main-branch-commit-hash
The commit of the main branch at time of running. In most case, you
DO NOT need to provide this, and we'll detect this from the Git repository
directly. Please contact support@screenshotbot.io if you plan on using this.
--mark-failed Mark this run as failed. This might happen if the build step that
generates the screenshots failed.
You don't need to call this, but if you do we can use the information
to show more appropriate information on Pull Requests. For instance,
if you have a Pull Request based off of a failing commit, we can find
the last green commit to make our screenshot report.
--mark-unchanged-from Notify Screenshotbot that the run for this commit will be identical
to the run from the commit provided
--merge-base-commit-hash
Override the merge base commit. In most cases, you do not
need to provide this, and it will be computed automatically (as
`git merge-base main this-branch`).The merge base is only use on PR
commits, to figure out which commit to compare screenshots against.
This might be useful to override if you don't have access to the
repository when calling this CLI, or implementing custom behavior with
stacked Pull Requests.
--metadata A metadata.xml file (Android only)
--override-commit-hash Override the commit hash detected by git. In most cases you
don't need this, and this is only relevant for Pull Requests, and
only if you rebase your changes as part of your CI run. This hash
must be the full hash, partial hashes or tag names are not
suitable.
Automatically detected on: CircleCI, Bitrise
--phabricator-diff-id Phabricator Diff ID
--production Whether this is a run on your CI. For local runs, we
suggest using `--production=false`. This avoids polluting your runs
in production.
--pull-request Pull request URL. Automatically detected on CircleCI,
Bitrise, Netlify.
--recursive Whether to scan the directory recursively
--repo-url Repository URL (e.g. https://github.com/foo/bar)
--self-test Run self-diagnostic tools to ensure that this CLI can work on your
machine.
--shard If the screenshots for a channel are being generated from multiple shards
(or "test splits"), you can pass a shard specifier here. When provided, Screenshotbot will
only create the screenshots for the last shard is uploaded.
A shard specifier looks like <buildId>:<shardNum>:<shardCount>. Build ID can be any
arbitrary identifier, but must be the same for the all the invocations. For example, it could
be a build ID of the root CI job.
--static-website Use to generate screenshots of a static website
--static-website-assets-root
When parsing the website directory at --static-website, the
asset root is used to determine where to fetch JS, CSS and image
from. If not specified, we assume the assets are all stored in the
same directory.
--tags A comma separated list of tags to associate with these runs. Tags are arbitrary and will be shown next to the run names, and let's you filter runs by tags.
--verbose Verbose logs
--version Show the version of this SDK and exit
--work-branch Your current branch, preferably as provided by your CI environment
as opposed to reading from git. Some CI environments may not update the
local branch name, and instead provides the branch name as an environment
variable. We can automatically figure this out on CircleCI, Bitrise,
Netlify, Azure DevOps, BuildKits, and Bitbucket Pipelines.
Copyright 2020-2022 Modern Interpreters Inc.
Please reach out to support@screenshotbot.io for any questionsFor a generic iOS or web project, we’ll expect you to store all the screenshots at the end of the CI run into a directory. This directory should not be committed into the git repository. At the end of the CI run, you can invoke the CLI script:
~/screenshotbot/recorder \
--directory path/to/screenshots/ \
--channel some-project-name \
--main-branch master \
--api-key ${SCREENSHOTBOT_API_KEY} \
--api-secret ${SCREENSHOTBOT_API_SECRET} \
--repo-url https://github.com/org/myrepo.gitThe repo URL is used for certain source control integrations. For example, with GitHub it is used for the Checks API (but make sure you install the Screenshotbot app to your project, and give it permissions to your repo. The Screenshotbot app only has access to the checks API and nothing else).
The channel is an arbitrary name that you can think of as a project id. The main-branch will always point to your master or main branch. It defaults to master. This branch is used to track the history of the screenshots, and for pull requests it is used to determine which branch to compare against.
Everything above applies for the Android project. Except we have special integrations for screenshot-tests-for-android and Shot, especially when using Firebase Test Lab.
You can see an example of this here.
Sign up or contact us.