Race condition testing
How to test race conditions in a Postgres web app: Playwright vs k6 vs isolationtester vs Jepsen vs VibeRaven race
Test the SQL first: a race is two transactions reaching the same rows in a bad order. VibeRaven race runs every order of two SQL sessions from your migrations, with no Docker, and replays the one that broke. PostgreSQL isolationtester runs the orders in a spec you write, or all of them, on a PostgreSQL build. Then use Playwright for the two-user flow in the browser, and k6 or Locust for load. Those do not force an order, so a pass there does not rule a race out.
When to use which
- 1One rule that must hold when two users act at once, such as a seat limit, a stock count or a one-time invite: test the SQL in every order. VibeRaven race does this from the migrations in your repo; isolationtester does it from a PostgreSQL source build.
- 2The whole flow in two browsers, sign-in included: Playwright, with one browser context per user. A pass shows the flow works in the order that happened to run.
- 3Errors and latency under load: k6, scripted in JavaScript, or Locust, scripted in Python, against a staging copy of the app.
- 4Throughput of your SQL across many sessions, with serialization and deadlock failures counted: pgbench with your own script.
- 5A distributed database under faults, such as killed processes and clock changes: Jepsen, with Elle checking the transaction history. One Postgres behind a web app rarely needs it.
Seven tools side by side
Each tool is described from its own docs or README, read on 2026-11-17. The VibeRaven row is the published 1.10.0 CLI.
What each tool runs, and whether it controls the order
| Tool | What it runs | Order of steps | Exact replay | Setup | Use it for |
|---|---|---|---|---|---|
| Playwright | Real browsers, one isolated context per user | Not forced; timing decides | No | Your running app | A two-user flow, end to end |
| Grafana k6 | JavaScript load scripts, mostly HTTP; also a browser API | Not forced; sets users, iterations and rate | No | Your running app | Errors and latency under load |
| PostgreSQL isolationtester | SQL steps in several sessions, from a spec file | Forced: the orders you list, or all of them | Yes, rerun the permutation line | PostgreSQL source tree; make check or installcheck | Concurrency tests of SQL, in its spec format |
| pgbench | Your SQL script in many concurrent sessions | Not forced | No | A running PostgreSQL server | Throughput; counts serialization and deadlock failures |
| Locust | Python user scripts, mostly HTTP | Not forced | No | Your running app | Load tests written in Python |
| Jepsen and Elle | A distributed database under injected faults; Elle checks the recorded history | Not forced; finds anomalies such as G2 after the run | No | A control node and database nodes over SSH | Distributed databases |
| VibeRaven race | Two SQL sessions from your migrations, on PostgreSQL 18.6 in one Node process | Every order, up to 100,000 per isolation level | Yes, byte for byte | Node 24 with JSPI; no Docker or server | One rule two users must not break |
A two-user example
The bundled example is a bookings table with a trigger that allows at most 2 bookings per event. One booking exists, and users A and B each insert one more. The output below is from the published 1.10.0 CLI on 2026-11-17; the elapsed time is left out because it varies.
Under read committed and repeatable read, each trigger counts the bookings without seeing the other user's uncommitted row, so both commit and the event ends with 3. The example also ships a fix that takes a lock on a guard row first; with it, 0 of 60 orders break and 36 wait for the lock.
$ npx -y viberaven race --example
At most 2 bookings per event: 60 orders, 24 broken, 0 waiting
read committed: 12/20 broken
repeatable read: 12/20 broken
serializable: 0/20 broken
First broken order 001101 (read committed); COMMIT A=true, B=true
A: BEGIN ISOLATION LEVEL read committed
A: INSERT INTO public.bookings VALUES ('user-A', 'demo-event')
B: BEGIN ISOLATION LEVEL read committed
B: INSERT INTO public.bookings VALUES ('user-B', 'demo-event')
A: COMMIT
B: COMMIT
Replay record is byte-identical, including PostgreSQL protocol bytes.Limits
- VibeRaven race tests the database only: the SQL and the statement orders you give it. It does not drive a browser or send HTTP requests, and Auth, HTTP and other outside effects are not part of the test.
- It is a local test, not a live database test: it loads your migrations into its own engine and never connects to your database.
- VibeRaven is made for AI-built apps on Vercel + Supabase, and race reads plain SQL migrations. Its result is advice, not a gate: you decide when to ship.
- Requests run as postgres unless you set a role, so they bypass ordinary RLS. Review the role and claims in the spec.
- A clean run covers one rule and the orders tried; it is not a security audit. An incomplete run is not a pass.
- The engine passes 122 of PostgreSQL's 124 isolation specs, and 80 of 80 replays were byte-equal. The two misses are named in the method notes.
Related guides
Browse all launch guides · Read resources · How to make and check your next change
FAQ for builders before launch
Can k6 or Playwright find a race condition?
Only if the bad order happens during the run. Neither picks the order in which two transactions reach the database, so a passing run does not show the race is absent. Use them for the flow and the load, and a tool that forces orders for the SQL.
Can I use isolationtester on my own app?
It is PostgreSQL's own test tool: it opens several sessions with libpq and runs the steps of a spec file. It lives in the PostgreSQL source tree and runs with make check, or make installcheck against an installed server. You write the spec yourself, in its format.
Do I need Docker for VibeRaven race?
No. It runs PostgreSQL 18.6 as WebAssembly inside one Node process, with two real sessions and real locks. It needs Node 24 with JSPI.
Is Jepsen useful for a single Postgres web app?
Rarely. Jepsen tests distributed systems under injected faults and needs a control node and database nodes. Elle, its history checker, can also be used on its own on a recorded history of transactions.