Sharding a Playwright suite that has outgrown one machine

Browser tests have a cost structure that unit tests don't. Each one runs a real browser: a Chromium process tree using several hundred megabytes, rendering, executing JavaScript, waiting on network. Six hundred of those in sequence is forty minutes, and forty minutes is long enough that people stop running them before merging.

Parallelism is the answer, but it comes in two forms that get conflated, and knowing which one you need saves you from optimising the wrong axis.

Workers and shards are different things

Workers are parallel processes on one machine. Shards are subsets of the suite split across machines.

// playwright.config.ts
export default defineConfig({
  workers: process.env.CI ? 4 : undefined,   // processes on THIS machine
  fullyParallel: true,                       // parallelise within files too
});

# Shards: each command runs on a DIFFERENT machine
npx playwright test --shard=1/8
npx playwright test --shard=2/8
# ... 8 machines, each running 4 workers = 32 concurrent browsers

Workers are limited by the machine — memory first, then CPU. Shards are limited by how many machines you're willing to run. The practical sequence is: raise workers until the machine is saturated, then add shards.

Where workers stop helping

Memory, almost always, and the arithmetic is unforgiving.

Chromium per worker      ~300-500 MB   (more with heavy pages or video)
Node test runner process  ~150 MB
Your app under test       ~500 MB
                          ------------
8 workers                 ~4.5 GB       before the OS has anything

Exceed available memory and the failure is not a clean error. The kernel's OOM killer takes whichever process it likes, which is usually a browser mid-test, and you get a test that fails with a target-closed error. That looks exactly like a flaky test, so teams add retries, which makes the suite slower, which makes them add workers, which makes it worse.

The rule of thumb that holds: roughly one worker per 1 GB of available memory, capped at the core count. Eight workers wants 8 to 12 GB. If you have 4 GB, running four workers is slower and less reliable than running two.

The real blocker is shared state

The technical side of parallelism is a config flag. The reason suites can't use it is almost always that the tests share a backend.

• Two tests log in as the same user, and one logs out while the other is mid-flow.
• One test creates a record the next test's list assertion counts.
• A test changes an account setting or feature flag that others read.
• Tests assert on 'the most recent order' and another shard just created one.
• A test resets the database between runs, which is fine sequentially and catastrophic in parallel.

The usual mitigation is per-test unique data: every test creates its own user with a random email and operates only on records it made. That works and it's the right first step, but it doesn't cover global state — feature flags, admin settings, anything genuinely singular — and it makes tests longer and noisier to read.

The stronger version is a private backend per shard. Not just a database, but the whole stack: app, database, any dependent services, snapshot-restored so it starts in about a second rather than being built.

// Each shard gets its own full environment — restored, not built
import { Sandbox } from "@pandastack/sdk";

export default async function globalSetup() {
  const env = await Sandbox.fork(process.env.STACK_SNAPSHOT);
  process.env.BASE_URL = env.url;        // tests point here
  process.env.SANDBOX_ID = env.id;
}

export async function globalTeardown() {
  await Sandbox.delete(process.env.SANDBOX_ID);   // no cleanup, just gone
}

This removes the entire class of cross-shard interference, and it removes cleanup logic — the environment is destroyed rather than reset, so there's no truncation script that can be incomplete. Tests can also do genuinely destructive things: delete all users, fill the disk, change a global setting, because nothing else is watching.

Merging the results

Eight shards produce eight reports, which is eight places to look for the one failure. Playwright's blob reporter exists for this and it's a two-line fix that people skip.

# On each shard
npx playwright test --shard=$N/8 --reporter=blob

# After all shards finish, in a merge job
npx playwright merge-reports --reporter=html ./all-blob-reports

# One HTML report: full timeline, traces, and the flaky-test view intact

Balancing shards

Playwright splits by test count, not duration. If one shard happens to collect the slow tests, your suite takes as long as that shard and the other seven sit idle. The fix is to feed durations back in.

# Playwright can use a timing report from a previous run to balance shards
npx playwright test --shard=$N/8 \
  --reporter=blob \
  --last-failed=false \
  --pass-with-no-tests

# Store the JSON report as a CI artifact and restore it on the next run —
# without it, sharding is a coin flip on whether the split is even.

Even without tooling, watch your per-shard durations. A spread of 4 to 11 minutes across eight shards means you're paying for eleven and using an average of six.

Do these first

Sharding costs money and coordination. Several cheaper things often produce a bigger improvement.

1. Stop logging in through the UI. Authenticate once in global setup, save the storage state, and reuse it. This alone frequently removes several seconds from every test in the suite.
2. Seed via the API, not the interface. Creating test data by clicking through forms is slow and tests the same forms repeatedly for no additional coverage.
3. Delete tests that assert the same thing. Large E2E suites accumulate near-duplicates, and each one costs you on every run forever.
4. Move what you can down the pyramid. If an assertion can be made at the component or API level, it will run in milliseconds instead of seconds.
5. Fix the flaky tests rather than retrying them. A test retried twice costs three times as long when it fails, and a retry that passes is a test that told you nothing.

Then shard. The end state that works well is a handful of shards, each with a private restored environment, results merged into one report, and durations fed back for balance. That combination scales to a suite of thousands and keeps the feedback loop inside the window where people will actually wait for it.