Advanced Options

The simple installation of Screenshotbot should work for most teams. However, there might be certain situations where you might want to do some additional CI configuration for a better developer experience.

Notifying Screenshotbot of Build Failures

Usually, you'll configure the Screenshotbot CLI to run after your build. This means that if your build fails, Screenshotbot doesn't get notified.

This can lead to undesirable behavior: e.g., a Pull Request based off of the failed commit will get a Build Status error from Screenshotbot since it doesn't know how to create a report.

Instead, if you configure your CI to notify Screenshotbot when your build fails, Screenshotbot will be smart about creating a report from the previous known green build.

Just call the CLI tool with --mark-failed on failing builds. You can see an example here.

Notifying Screenshotbot of unchanged runs

If you have a large repository and use some mechanism of target selection to run tests. (e.g. Using Buck, Bazel or Gradle Predictive Test Selection), you might have to inform Screenshotbot when you ignore a specific test target.

You can do this by providing using the `--mark-unchanged-from` for each channel that wasn't run:

    ~/screenshotbot/recorder --channel //my/build:target \
         --mark-unchanged-from 28916047d2fc8e6e5c4670b56c6134791f5dff17

Note that we need the full commit hash. This must also be run inside of the Git repository during the CI build.

It is legal to have a chain of such markings. For instance you can mark commit foo to be unchanged from bar, and bar to be unchanged form car.

Sharded test runs

If you have configured your CI to run tests in parallel across multiple shards (also called Test Splits), you can still use Screenshotbot to collect the screenshots across shards.

To do this, on each shard, once your tests are run call the CLI tool on each shard with an additional argument --shard shardKey:shardIndex:shardCount.

Shard key is an arbitrary key identifying all the shards belonging to the same run. Typically it might be a build identifier for a root job. For a given shard key and channel name, all the screenshots are collected together to form a single run.

For example, when using CircleCI's Test Splits, you could pass: --shard $CIRCLE_PIPELINE_ID:$CIRCLE_NODE_INDEX:$CIRCLE_NODE_TOTAL.

The run is created when all of the shards have reported in. If a job is re-run then it will have no effect. To recreate the run, you would have to restart the pipeline (or effectively generate a new shardKey).