Skip to content
Vizzly Docs

Parallel Builds

Parallel builds let multiple test shards contribute screenshots into one Vizzly build.

The rule is simple: every shard uses the same parallel-id, and then you finalize that ID once all shards are done.

Basic pattern

Terminal window
vizzly run "npm test -- --shard=1/3" --parallel-id "build-12345"
vizzly run "npm test -- --shard=2/3" --parallel-id "build-12345"
vizzly run "npm test -- --shard=3/3" --parallel-id "build-12345"


vizzly finalize "build-12345"

You can also set VIZZLY_PARALLEL_ID.

Important rule

Make the parallel ID unique per CI run. Reusing an old one can attach screenshots to the wrong build.

CI guidance

No matter which CI provider you use:

  • generate one unique ID for the workflow or pipeline
  • pass it to every shard
  • always run finalize, even if some shards fail

That last part matters. finalize tells Vizzly that no more shards are expected.

Check every shard’s upload summary, even when all test jobs pass. An upload failure can leave the shared visual build incomplete without failing the shard’s tests. finalize doesn’t retry missing captures. Fix the upload problem, then rerun with a new parallel ID. See upload troubleshooting.

Next steps