How to control Percy snapshot concurrency in CI
Coordinate Percy snapshots across CI shards with a shared nonce, the right total, and a reliable finalization step. Includes fixed and variable shard examples.
To coordinate Percy snapshots across CI workers, give every shard in one CI run the same unique PERCY_PARALLEL_NONCE. If the shard count is fixed, set PERCY_PARALLEL_TOTAL to the number of Percy shards expected. If the count is unknown, use total -1 and run percy build:finalize after all shards finish. A build can stay in “receiving” when Percy is still waiting for an expected shard or the explicit finalization step.
Percy parallelism coordinates shard contributions to a build; these settings do not establish a universal cap on simultaneous snapshots. Most supported CI setups detect parallel metadata automatically, so inspect Percy’s detected environment before adding manual overrides. See Percy’s parallel test suites guide and environment variable reference.
1. Choose the coordination mode
| CI situation | Configuration | How the build completes | Common risk |
|---|---|---|---|
| Known, fixed number of Percy shards | One shared, run-unique nonce and the exact PERCY_PARALLEL_TOTAL |
Percy waits for that many shard finalizations | A total larger than the shards that finish can leave the build receiving |
| Variable or unknown shard count | Parallel mode, shared nonce, total -1 |
A dependent job explicitly runs percy build:finalize after all test shards finish |
A missing finalize job or different nonce can leave the build open |
Count the Percy build shards Percy sees, not the individual test cases. One CI invocation that runs many test cases is generally one shard for this coordination decision; separate workers that report to Percy are separate shards.
2. Configure a fixed shard count
Set the nonce and total consistently in every shard job. Use an identifier shared by jobs in the same CI run, such as the run ID, and make sure it is distinct between separate runs. Do not reuse a nonce that can point to an already finalized build.
PERCY_PARALLEL_NONCE="$CI_RUN_ID" PERCY_PARALLEL_TOTAL=4 \
npx percy exec --parallel -- npm testRun this command in each of the four Percy shard jobs with the same CI_RUN_ID and total. The shell syntax above assumes the CI system exposes a shared run identifier as CI_RUN_ID; map that placeholder to your provider’s actual variable. Percy documents percy exec --parallel -- [test command] for tests spread across machines or containers. Confirm the installed CLI’s syntax and your CI integration’s completion behavior.
Fixed-count checklist
- Every shard uses the same nonce for this run.
- The nonce changes for a new run, including reruns when the provider reuses workflow identifiers.
- The total equals the number of Percy shard invocations expected to report.
- Every expected shard reaches Percy’s finalization step, including retry behavior.
- No job overrides the nonce or total with a conflicting value.
3. Configure a variable or unknown shard count
When the number of shards cannot be known in advance, use Percy’s documented -1 mode, then place one finalize job after all test jobs. That job must use the same nonce as the shards. For example, set the shared value in the CI environment for all jobs:
export PERCY_PARALLEL_NONCE="$CI_RUN_ID"
export PERCY_PARALLEL_TOTAL=-1
npx percy exec --parallel -- npm testAfter every shard has completed, run the finalization command once in a dependent job:
PERCY_PARALLEL_NONCE="$CI_RUN_ID" npx percy build:finalizeWire the final job to depend on all test shard jobs, and configure the CI workflow so it runs after those jobs have completed, including the failure and retry cases your workflow must account for. Use the current command syntax for your installed Percy CLI; consult the Percy commands reference. Percy’s guide may describe the operation as finalize-all; the documented CLI command is percy build:finalize.
4. Handle parallel tests on one machine
Distributed CI shards each run their own Percy command. For multiple test processes on the same machine, Percy’s guide describes keeping one Percy server available while those tests run and stopping or finalizing it only after they exit. The server lifecycle is different from a distributed-shard workflow, so follow the instructions for your CLI version and avoid finalizing while processes still need to send snapshots. See the official parallel suites guidance.
5. Verify the run and diagnose “receiving”
- Check Percy’s environment detection and confirm whether it found parallel metadata automatically.
- Compare the configured total with the Percy shard jobs that actually reported and finalized.
- For total
-1, verify the dependent finalize job ran after all test shards and used the same nonce. - For retries, verify the nonce still identifies only the intended run and does not collide with a finalized build.
- For a custom or unsupported CI provider, explicitly map the Percy token and parallel metadata into each job.
| Symptom | Likely cause | Fix |
|---|---|---|
| Build remains in “receiving” | The fixed total is higher than the number of shard finalizations Percy received, or one shard failed before reporting | Check shard logs and completion, then correct the total or repair the missing worker. Do not mark a shard complete just to satisfy the count. |
Build with total -1 stays open |
The finalize command did not run, ran too early, or used a different nonce | Make finalization a single dependent job after all shard jobs, using their shared nonce. |
| Rerun attaches to an old or finalized build | The rerun reused a nonce that identifies another run | Use a run-unique nonce, accounting for how your CI provider assigns IDs to retries. |
| Shards appear split across builds | Jobs used different nonce values | Pass one shared run identifier to every shard and the finalize job. |
| Conflicting parallel settings across jobs | Manual variables override automatic detection inconsistently | Inspect detected metadata first; remove unnecessary overrides or set consistent values everywhere. |
| Custom CI does not join shards | The provider integration does not supply Percy’s parallel metadata | Manually map the token and parallel variables; Percy identifies the nonce as required for custom providers. |
For custom provider setup and automatic detection details, see Percy’s other CI/CD integrations and environment variable reference.
6. Performance, reliability, and cost considerations
These settings coordinate how Percy groups and completes parallel builds; they do not specify a universal maximum concurrency or account-level cap. The available official guidance does not establish one universal cap on simultaneous snapshots, so check the current plan documentation or project support for account-specific limits.
Parallel workers can finish at different times. Build completion therefore depends on the expected shard finalizations, not simply on the test suite having started or on most workers being done. Retries improve reliability only when they preserve the intended run grouping and do not accidentally reuse a nonce from another finalized run. The provided Percy guidance does not give a cost formula for shard concurrency; consult current plan terms for billing details rather than inferring a price from these variables.
Or skip the browser setup
If what you need is a screenshot of a page for a visual check or report, ScreenshotNeo is a website screenshot API and MCP server. It is separate from Percy’s test snapshot coordination. A single GET request returns an image or PDF, with parameters for formats and capture options documented in the ScreenshotNeo API docs.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers say which page verdict was returned and whether it was billed. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up free for 1,000 screenshots a month, with no card required.
FAQ
Does PERCY_PARALLEL_TOTAL limit simultaneous snapshots?
No. It tells Percy how many parallel builds or shards to expect for coordination when using a fixed count.
Can separate shards use different nonces?
Shards that belong to the same Percy build must share the nonce. Use a different nonce for a separate CI run.
Should I always set both variables manually?
No. Most supported CI configurations detect parallel settings automatically. Check what Percy detects before adding overrides.
What should the finalization job wait for?
In -1 mode, it should run after every test shard that can contribute to the build has completed, and use the same nonce.
