Docs / Testing and review

Sharded test runs

When one test run is split across several CI machines, each machine pushes its screenshots as a shard. Screenery holds the shards and moves your channels once, when the last one is in, as if one machine had pushed them all.

Availability: shards need the CLI release after 0.4.0. The screenery/push@v1 Action gains its shard inputs with that release; until then, run npx screenery push directly as below.

Why not one push per machine

A push is the whole set: the channels it moves end up holding exactly what it carried, and anything else is removed from them (see How @latest moves). Four machines each pushing a quarter of the screenshots would each remove the other three quarters. Marking every push --partial avoids that, but then nothing is ever removed, and a screenshot whose test you deleted stays on @latest forever. Shards keep removals and lose neither.

Pushing shards

In each job of a GitHub Actions matrix:

strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx playwright test --shard=${{ matrix.shard }}/4
  - run: npx screenery push screenshots --project acme/web --shard ${{ matrix.shard }}/4

• The group key is the workflow run id by default, which every job of a run and every re-run of it share. Outside GitHub Actions, pass --shard-key with your CI's run id.
• Each shard's screenshots are stored at once. Their version URLs (@v_…) work as soon as the shard finishes.
• The last shard moves the channels. When every shard is in, one combined build moves your branch channel, @pr-N and, on the default branch, @latest. Names no shard pushed are removed.
• One pull-request comment. Earlier shards post nothing; the comment is posted once, for the whole run.
• Every shard pushes the same commit, branch and total. A shard that disagrees is refused. Shards count from 1, like Playwright's.
• Give each shard's screenshots their own names. If two shards push the same name, the newest shard's image is kept and the log warns.

What the channels show meanwhile

Exactly what they showed before the run. Nothing is half-moved, so a pull request's gallery never shows three quarters of a run. If a shard never arrives, the channels simply stay where they were; after 24 hours the group is marked expired, and a shard that arrives later picks it up again.

Re-running a failed job

Re-run only the failed job and its shard replaces the one from the first attempt. The shards that were not re-run are kept, so nothing they pushed reads as removed.

When you do not know how many shards

Push each shard with --shard-total auto, then finish the run once, in a job that needs all of them:

npx screenery push screenshots --project acme/web --shard 3 --shard-total auto
# … after every shard:
npx screenery push --finalize-shards --project acme/web

Finishing a run with a known total is harmless: it reports the combined build already made, or names the shards still missing.

Shards and --partial

--partial still means one of several separate pushes, such as web screenshots and store screenshots pushed from different workflows. Use shards for one test run split across machines, and --partial for pushes that are genuinely separate.