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.

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.

shardIndex could be either 0-indexed or 1-indexed.

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