cellajs/cella/two-tab-sync-test

Two-tab realtime sync testing

Use when a live-sync symptom needs runtime evidence ("create doesn't show up in the other tab", "typing doesn't reach the other editor", "offline edits are gone") or to verify sync changes end-to-end. Two drivers, each a fixed matrix with per-tab console, network evidence and screenshots:

• two-tab-driver.mjs: one user in two tabs. Rename control, create, delete-fresh, delete-preseeded, description typing and save, reload truth-check.
• description-driver.mjs: two users (and a third who may only read) on one description. Cursors, saves while typing, an outside write, offline from storage, a relay outage, sign-out with unsynced edits, two offline tabs, a delete under unsaved edits.

Preconditions

• A healthy dev stack in the checkout under test, its stdout captured (verify, Launch). The driver reads that checkout's URL and cookie name.
• The description experiment needs the relay (appConfig.services.yjs.enabled, on by default).
• Postgres probes: psql <DATABASE_ADMIN_URL from backend/.env> (e.g. a row's seq, deleted_at or description after an action).
• Never act in the org a human is testing in (watch the request log for their active org); pick another seeded org.

Auth: a minted session

The driver mints a session for each user and signs it out when it ends (verify, Drive).

• Default, the bench user (needs pnpm --filter bench db:seed once): xbench-user-0000@xbench.local is admin of xbench/xbench-org. The seed sets that tenant's attachment quota to unlimited, so every experiment runs there, creates included.
• Any other seeded org: pick an admin and pass EMAIL and ORG_PATH.

SELECT o.tenant_id, o.slug, m.role, e.email FROM organizations o JOIN memberships m ON m.organization_id = o.id JOIN emails e ON e.user_id = m.user_id WHERE o.slug <> 'xbench-org' ORDER BY o.slug, m.role LIMIT 20; An org at its tenant's attachment quota (appConfig.defaultRestrictions.quotas) answers creates with 403 `restrict_by_app`.

• The description driver's users: EMAIL and EMAIL_B both edit (bench users 0000 and 0001 by default), EMAIL_VIEWER may read the row and not update it. With the template's permissions that is a member who did not create the row; every bench member is an admin, so the read-only experiment needs another org and is skipped without EMAIL_VIEWER.

Run

From the repo root:

[EMAIL=<email>] [ORG_PATH=<tenantId>/<orgSlug>] OUT_DIR=<scratch> \
  node cella/skills/two-tab-sync-test/two-tab-driver.mjs

Writes evidence.json (every console line / range fetch / assert, ms timestamps) and shots/*.png. Tab A acts, tab B observes. Asserts print PASS/FAIL live. The first line, target, names the URL and cookie in use: check it against the stack you mean to test.

[EMAIL=<editor>] [EMAIL_B=<editor>] [EMAIL_VIEWER=<member>] [ORG_PATH=<tenantId>/<orgSlug>] \
  [ROW=<name>] [DELETE_ROW=<name>] [ONLY=live,typing,outside,viewer,offline,outage,signout,tabs,delete] \
  [RELAY=ws://localhost:<port>] OUT_DIR=<scratch> \
  node cella/skills/two-tab-sync-test/description-driver.mjs

Writes description-evidence.json and shots/*.png, about two minutes for the whole matrix. User A acts, user B keeps the description of ROW (the first row by default) open and observes; server truth is read through the API. It ends with the count of passed asserts and exits 1 when one failed.

A relay change in a worktree runs beside the main stack, with no stack of its own: start that checkout's relay alone, pointed at the main backend (BACKEND_INTERNAL_URL=<the main backend's internal URL> pnpm --filter yjs-worker dev; it listens on the worktree's own relay port and, with the same backend/.env values, shares the database and the token key), then run the driver from the main checkout with RELAY=ws://localhost:<that port>. Every editor socket of the run goes to that relay, and the main stack serves the rest.

Reading the evidence: entity changes

Decision rule: no console change line and the API's `cdc` component is not healthy (its reason says why) → the worker (read its log), not the client; no console change line otherwise → SSE/leader/broadcast layer; change but no fetch → fetch prioritizer/cursor (check the org and view seqs in syncStore, frontend/src/query/realtime/sync-store.ts); fetch contains the row but UI unchanged → cache-patch layer (fetchRangeAndPatch in frontend/src/query/realtime/cache-ops.ts).

Became leader, reconnecting... follows whenever a tab gains leadership with no open stream: at startup, or when the leader tab closed (Client). viewing=true marks a tab on the org route, which fetches at once. Chromium throttles a hidden tab's timers to about 1s, so use generous assert windows.

Creates not propagating: check the applyServerEntity applicator in cache-ops.ts first.

Reading the evidence: descriptions

Typing does not ride the entity path. Keystrokes go editor → relay socket (/yjs/<entityId>) → the other editors. The relay saves the row a few seconds after the last keystroke (Save), and the saved row then travels the entity path like a rename.

Decision rule: no `relay-connect` → token or socket (the yjs/token status, the relay process, the /yjs proxy); connected but no live text → relay session and broadcast (yjs/src/sync/relay.ts); live text but no saved row → compaction and materialization (yjs/src/sync/compaction.ts, the backend's /internal/yjs/materialize); saved row fetched but the cell is stale → the cache rule for Yjs-owned fields (registerYjsOwnedFields).

The table cell of an editing tab proves no save: its own editor already patched the cache. Only the range fetch and the reload show the server row.

The description driver's experiments, by their ONLY name:

relay-http lines with route pull or push during outage are the HTTP transport at work; the same lines in any other experiment mean the socket failed there.

Gotchas