Skip to main content
Sharding splits a run across multiple parallel shards and merges the results into a single report — the fastest way to bring down wall-clock time on a large suite. It isn’t automatic, though: a suite that was written to run serially (or with a handful of local workers) can hit new failure modes once it’s split across many independent machines that all hit your application at the same time. This page covers what to check before you turn sharding on, and the current limits. For the mechanics of triggering a sharded run, see CI Integration and the API Reference.

​
Is your suite ready to shard?

​
Every test should own its data

The single biggest predictor of a clean sharded run is data isolation. Each shard runs independently and in parallel against the same environment, so:
  • When the setup itself isn’t what the test is verifying, create the data a test needs via your API rather than a UI form, with a unique name — something like <test-id>-<random-suffix> — never a fixed human-readable name another test might also create or match against.
  • Don’t assert on the state of a shared resource (“there are 3 items in the list”). Assert on your own uniquely-named item.
  • Avoid a single default project, workspace, or org that every test reads from and writes to. If multiple tests mutate the same record, one shard’s setup or cleanup can race another shard’s assertions.
  • Clean up what you created in a teardown step, best-effort — log a cleanup failure rather than letting it fail the test itself, so leftover data doesn’t go unnoticed.
If you’re migrating test setup from UI steps to direct API calls for speed, confirm the API call actually creates everything the test depends on — not just a top-level record. A setup call that only creates a parent object, while the test also depends on nested state, won’t save the time you expect and can leave a test’s real setup still happening through the slow UI path.

​
Session and login state

If your application keeps session- or user-scoped state that a test’s steps depend on, each shard doing UI-driven login independently may need its own isolated user or session — otherwise two shards logged in as the same user can race each other’s navigation, toggles, or in-progress work. Some things to check first:
  • Before assuming you need one account per shard, verify empirically how many concurrent sessions your backend actually supports on a single account. Some backends safely deduplicate concurrent logins into a single valid session; others invalidate the previous session on a new login. Test this directly (open N sessions concurrently, confirm none of them get logged out) before picking a shard count.
  • If you restore a saved login session (cookies or local storage) instead of logging in through the UI, apply it before the first page navigation and avoid rewriting cookie domains you don’t need to — some SSO providers run a silent login check on page load that can overwrite a session restored too late or with a mangled cookie domain, which shows up as an intermittent “logged out” failure specific to parallel runs.

​
Backend and environment capacity

Every shard’s tests hit your application’s APIs at the same time. A suite that’s fast and reliable with one worker can behave differently once N shards are calling the same endpoints simultaneously:
  • Check for rate limits, connection-pool limits, or per-account concurrency limits on your backend and staging/test environment.
  • If you only see timeouts in sharded runs, don’t reach for a longer timeout right away — first rule out a data/session race (two shards fighting over the same entity or account), since that fails the same way real backend saturation does. If the failure reproduces even with isolated data, then it’s a capacity signal and a timeout bump is the right call.
  • If you turn on retries to smooth over flakiness, remember retries add wall-clock time on every retried test — on a suite with a few very slow tests, this can offset a meaningful chunk of the speedup sharding gives you.

​
Avoid test.describe.serial as a workaround

If two tests only pass when forced to run in sequence, that’s usually a sign they share state that should be isolated instead. Forcing serial execution hides the coupling (and the runtime cost) rather than fixing it, and it doesn’t help with sharding either — tests locked into a fixed order don’t gain anything from being split across more shards.

​
Know your ceiling

  • A shard’s runtime is driven by the files assigned to it. If one file is much larger or slower than the rest, that file’s shard becomes your wall-clock floor no matter how many shards you add — splitting an oversized file into smaller files gives sharding more to balance across.
  • Merge takes a little time after all shards finish. Once every shard is done, Checksum combines the shard reports into one final report. Budget for a short merge step on top of your shards’ runtime — it isn’t instant.
  • Compare wall-time changes fairly. A shard-count change is only comparable to a previous run if the test count, environment, and retry settings also match — a suite that grew or shrank between runs isn’t a fair before/after.
  • Verify in your real CI environment, not just locally. Auth and session handling in particular can behave differently under a headless CI runner than on your local machine, so a shard-count assumption that holds locally should still be confirmed with an actual sharded run before you rely on it.

​
Current limits

Before your first sharded run, update checksumai on your tests branch to the latest release and commit it (npm install checksumai@latest is the safe default). An outdated version can fail to combine shard results into a final report, which delays the run’s outcome well past a normal run’s duration. See CI Integration for the current minimum supported version.
Need more than 40 shards for your suite? Reach out to your Checksum contact.

​
Rolling out sharding safely

Start with a modest shard count, confirm it’s fully green and stable, then scale up gradually — diagnosing each new failure (isolation vs. capacity, per the sections above) before you reach for a timeout, a retry, or a bigger shard count as the fix.

​
Next Steps