Command Line Interface

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.

Installation

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://screenshotbot.io/recorder.sh | sh

This 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.

Overview of CLI options

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

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
 --branch                [OBSOLETE]                              
 --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`.
 --create-github-issue   Create a Github issue if enabled on your account
 --defaults                                                      
 --device-regex                                                  
 --directory             Directory of images                     
 --gitlab-merge-request-iid                                        
                         GitLab merge request IID
 --help                                                          
 --ios-diff-dir          When using ios-snapshot-test-case, this can link to the
                          IMAGE_DIFF_DIR. In most cases this isn't required, but it can be
                          useful for backward compatibility if you don't want to update the
                          tests to always work in recorde mode.
 --ios-multi-dir                                                 
 --lang-regex                                                    
 --main-branch           Git Branch of the main branch being tracked. We try first
                          `main` and then `master`, by checking for origin/<branch-name>
 --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                                                    
 --pull-request          Pull request URL. Automatically detected on CircleCI,
                          Bitrise, Netlify.
 --repo-url              Repository URL (e.g. https://github.com/foo/bar)
 --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.
 --verbose               Verbose logs                            

Copyright 2020-2022 Modern Interpreters Inc.
Please reach out to support@screenshotbot.io for any questions

Example usage for a generic iOS/web project

For 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.git

The 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.

Example usage for Android project

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.

Ready to get started?

Sign up or contact us.