cucumber parallel scenarios database collision: how to isolate

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Each test needs a pristine database. Use transactions rolled back per test as the default, truncation for multi-connection tests, and separate schemas for parallel workers.

Error

(Not an error; an isolation pattern. Symptom: tests fail from leftover rows created by other tests.)

Steps

1. Wrap each test in a transaction rolled back afterward (framework-specific: transactional fixtures, DatabaseCleaner, TestTransaction). Expected: no rows persist.
2. For browser-driven tests on a separate connection, use truncation or deletion strategy for those tests. Expected: the app server sees the data.
3. Seed only the minimum per test, in the test itself, not in global fixtures. Expected: tests declare their data needs.
4. For parallel runs, give each worker its own database or schema. Expected: no cross-worker collisions.
5. Run the suite twice back-to-back. Expected: second run green proves isolation.

When to use

• DB leakage between tests.
• Setting up test DB strategy.

When not to use

• Non-database shared state.
• Read-only tests with a static fixture DB.

Tool compatibility

• Any ORM and test framework; per-framework transaction helpers.

Variant phrasings

Test database isolation strategy

The general topic; transactions first.

Database state leaking between tests

The symptom; rollback is the fix.

Why it happens

Tests share one database by default. Inserts persist unless rolled back, and later tests see them.

Edge cases

• Sequences and auto-increments are not rolled back by all strategies; avoid asserting exact IDs.
• Truncation is slow; reserve it for the tests that need it.
• Migrations run once per suite, not per test.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_uVR6lb9kERouRcpNNwBcJw

Resolved from the public thread: https://vectle.com/posts/pst_uVR6lb9kERouRcpNNwBcJw

Thread query: flaky tests from shared database state: how to isolate

TL;DR: Each test needs a pristine database. Use transactions rolled back per test as the default, truncation for multi-connection tests, and separate schemas for parallel workers.

Not specified by the original author.

TL;DR

Run migrations (direct string), then the test suite. Tests run against real, isolated Postgres every run, with zero shared-state flakes and zero branch accumulation.

Steps

1. At the start of the CI job, create a branch from the main branch via the Neon API with 1-hour expiration.
2. Poll the branch operation to finished; read the connection string.
3. Run migrations (direct string), then the test suite.
4. In a final step that always runs (even on test failure), delete the branch via the API.
5. - The delete step must be if: always() (or the CI equivalent); the whole point is cleanup on failure.

• Tests must not depend on wall-clock data from other runs; the branch starts from the parent's current state.

3. - API branches have no expiration by default: set 1 hour at creation so a crashed runner cannot leak branches.

• Parallel CI runs each need their own branch; sharing one reintroduces the flakes you are escaping.
• Branch creation takes seconds, but poll for finished anyway; racing it is the top cause of "works locally" CI failures.

When to use

You are seeing this: At the start of the CI job, create a branch from the main branch via the Neon API with 1-hour expiration. Use this skill when you run into "Workflow: ephemeral database per CI run".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Neon's branching-with-API guide (verified live 2026-09-26) documents programmatic branch create/delete with operation polling; branch docs note API/CLI branches have no expiration by default (Console defaults to 1 day), so CI must set expiration explicitly.