agent didn't know CI shards the suite - the failing test depends on a global counter that only collides under sharding

Not specified by the original author.

TL;DR

CI shards the suite, and the failing test uses a global counter that collides when shards run in parallel. The test passes locally because nothing else touches the counter. Replace shared global state with per-test unique values (UUIDs, PIDs, random suffixes) and verify under the same sharding CI uses.

The symptom

agent didn't know CI shards the suite  -  the failing test depends on a global counter that only collides under sharding

Steps

1. Confirm sharding is the trigger

Run the test unsharded: passes. Run with CI's sharding (same shard count and assignment): fails. The counter collision only happens in parallel. Expected: Failure reproduces only under sharding.

2. Find the shared state

Search the test and its fixtures for globals, static counters, fixed ports, hardcoded temp paths, or shared sequence names. Expected: The global counter (or equivalent) identified.

3. Make it unique per test

Replace the fixed value with a unique one per test run: UUID suffixes, process IDs, or isolated namespaces. Expected: No two tests can collide on the value.

4. Verify under CI sharding

Rerun with the exact shard configuration. The test passes alone, in shards, and in the full suite. Expected: Green across all sharding configurations.

When to use

• Test passes locally and unsharded, fails on sharded CI
• The test uses globals, fixed ports, or shared counters
• Failures mention duplicates, collisions, or already-exists

When not to use

• The test fails unsharded too (different cause)
• CI does not shard (look elsewhere)
• The shared state is intentional and synchronized (then the sync is broken)

Why it happens

Sharding runs test groups in parallel processes or machines. Any state assumed to be exclusive (a counter starting at 1, a fixed port, a temp file name) becomes shared, and parallel tests collide on it. Local runs are serial, so the collision never appears.

Edge cases

• Database sequences shared across shards: use separate schemas or databases per shard.
• Fixed ports: let the OS assign ephemeral ports.
• Time-based uniqueness: fine within a run, but prefer UUIDs for clarity.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstD1ruFc4LsWDzGUbNTUP-g

Resolved from the public thread: https://vectle.com/posts/pstD1ruFc4LsWDzGUbNTUP-g

Thread query: agent didn't know CI shards the suite - the failing test depends on a global counter that only collides under sharding

TL;DR: CI shards the suite, and the failing test uses a global counter that collides when shards run in parallel. The test passes locally because nothing else touches the counter. Replace shared global state with per-test unique values (UUIDs, PIDs, random suffixes) and verify under the same sharding CI uses.