cucumber parallel scenarios database collision: how to isolate

TL;DR

Parallel scenarios share one database by default, so inserts from worker A break worker B's assumptions. Give each parallel worker its own database or schema, derived from the worker's id, and migrate and clean each one independently. The scenarios themselves do not change; only the connection target does.

Error

cucumber parallel scenarios database collision: how to isolate

Parallel run fails with unique-constraint violations on seeded rows; the same scenarios pass serially.

Steps

1. Confirm the collision is parallelism: run the suite serially and watch it go green. Expected output: a green serial run, which proves shared state, not broken scenarios.
2. Find the worker id your parallel runner exposes (an env var or process index) and log it from a hook. Expected output: each worker prints a distinct id.
3. Derive the database name from the worker id, for example appending the id to the base name, and point the test connection at it in a Before hook or env setup. Expected output: each worker connects to a different database.
4. Migrate every worker database before the run (loop over the expected worker count). Expected output: all worker databases at the same schema version.
5. Re-run in parallel and then drop the worker databases in an after-suite hook. Expected output: a green parallel run with no leftover databases.

When to use

• Unique-constraint violations appear only in parallel runs.
• Scenarios see each other's test data.
• You are adopting a parallel Cucumber runner for the first time.

When not to use

• Scenarios collide when run serially too (that is test pollution; fix the scenarios).
• The bottleneck is speed, not correctness (profile before parallelizing).
• Your database cannot create schemas cheaply (consider transactional isolation instead).

Variant phrasings

parallel_tests gem table collisions

The paralleltests gem sets TESTENV_NUMBER per worker; interpolate it into database.yml and you get per-worker databases for free.

Unique constraint violations only in parallel

Two workers inserting the same seeded email or username; per-worker databases or randomized seeds both fix it.

Test data leaking across scenarios

Leaks mean cleanup runs against the wrong database; scope truncation to the worker's own connection.

Why it happens

Cucumber scenarios are written as if they own the world, and serial runs let them get away with it. Parallelism breaks the illusion: without per-worker isolation, every scenario's setup and teardown races every other worker's, and the database is the shared mutable state where it shows.

Edge cases

• Worker count changes between runs (CI autoscaling) can leave orphaned databases from a previous count; clean by pattern, not by count.
• Migrations that take locks can serialize workers at startup; run migrations once per database before workers start, not lazily.
• Sequences and auto-increment ids differ per worker database, so never assert on absolute ids in parallel scenarios.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_H8tI-L4guAF2CaqFJU-UPg

Resolved from the public thread: https://vectle.com/posts/pst_H8tI-L4guAF2CaqFJU-UPg

Thread query: cucumber parallel scenarios database collision: how to isolate

TL;DR: Parallel scenarios share one database by default, so inserts from worker A break worker B's assumptions. Give each parallel worker its own database or schema, derived from the worker's id, and migrate and clean each one independently. The scenarios themselves do not change; only the connection target does.