presence-cursors.spec.ts

presence-cursors.spec.tstests/e2e/specs/presence-cursors.spec.tsraw ← specs19,409 B← Back to the app
1/**
2 * TASK-0093 — 3-client presence + live cursors E2E (the presence half of the
3 * Phase-7 exit criterion + the cursor + a11y suite).
4 *
5 * ── RUNNER GATE (Docker) — NOT RUNNABLE LOCALLY ────────────────────────
6 * This spec needs the full stack (Postgres + Redis + API :4000 +
7 * realtime :4001 + web :3000, the seeded demo user) — a Docker daemon,
8 * which is unavailable in this environment (permission denied; recorded,
9 * never faked). It is CI-ready under the same contract as every other spec
10 * in this package (`pnpm docker:up && pnpm dev`, then the suite). Committed
11 * so the TASK-0093 acceptance mechanic is pinned for CI; it is not a
12 * local-green test here.
13 *
14 * ── WHY THREE DISTINCT USERS ───────────────────────────────────────────
15 * Presence is keyed by userId server-side (the server stamps `user` from the
16 * handshake token + the display-name resolver) and a tab never renders its
17 * OWN peer (the bar shows OTHERS). Three tabs of the SAME user collapse to
18 * one presence entry and are self-excluded → 0 avatars. To assert the DoD's
19 * "3 contexts on one page → all three see the other two's avatars", this
20 * spec uses THREE DISTINCT USERS in one workspace (the seeded demo owner +
21 * two invited members — the exact production scenario).
22 *
23 * ── ROUTE + SELECTORS (verified against the app source) ────────────────
24 * Page route: `/w/:workspace/page/:id` (the [workspace] segment accepts id
25 * or slug; the sidebar links `/w/${slug}/page/${id}`). There is NO `/p/`
26 * route and no middleware rewrite — the older specs' `/w/${id}/p/${id}` URL
27 * would 404 (a pre-existing latent bug in specs that were committed
28 * CI-ready but never run locally; recorded, not repeated here). Blocks are
29 * rows carrying `data-block-id={id}`; the cursor overlay is the
30 * `div[aria-hidden]` inside the block list; the a11y live region is
31 * `role="status"`.
32 *
33 * ── THE < 500 ms BUDGET (honest) ───────────────────────────────────────
34 * The DoD metric is "the other two's avatars < 500 ms of each's join". E2E
35 * measures the join→avatar delta on a 2× flake-superset (1000 ms) and logs
36 * the actual, so a real regression (several seconds) fails while CI jitter
37 * (100–200 ms) does not. The "caret within 4 px of coordsAtPos" sub-assert
38 * is a UNIT concern (lib/presence-cursor.test.ts resolves the geometry
39 * deterministically, including multi-block selections) — the E2E asserts
40 * the observable: the caret + name label render, in the RIGHT BLOCK's
41 * vicinity (a 4 px pixel-diff is not robust against CI font metrics).
42 */
43import { test, expect } from "../fixtures";
44import { DEMO_EMAIL, DEMO_PASSWORD } from "../fixtures";
45import {
46  addMemberViaSeam,
47  register,
48  login,
49  createWorkspace,
50  createPage,
51  createBlock,
52  getBlocks,
53  seamServiceToken,
54} from "../utils/api";
55import type { APIRequestContext, Browser, Page } from "@playwright/test";
56import type { AuthState } from "../fixtures";
57 
58const PRESENCE_BUDGET_MS = 1_000; // 2× the 500 ms DoD metric (flake-superset)
59const LEAVE_BUDGET_MS = 1_500; // the < 500 ms leave metric, flake-superset
60const DEMO_NAME = "Demo User"; // prisma/seed.ts: upsertUser(DEMO, "Demo User")
61 
62const WEB_BASE = process.env.E2E_BASE_URL ?? "http://localhost:3000";
63 
64/** A freshly-registered user with its own authenticated browser context
65 *  (mirrors the `secondUser` fixture's cookie + token storage state). */
66async function newUser(
67  browser: Browser,
68  name: string,
69): Promise<{
70  user: { email: string; password: string };
71  page: Page;
72  close: () => Promise<void>;
73  api: APIRequestContext;
74}> {
75  const email = `e2e-pres-${Date.now()}-${Math.random().toString(36).slice(2, 8)}@factory.local`;
76  const password = `e2e-${Date.now().toString(36)}`;
77  const plain = await browser.newContext();
78  const plainApi = plain.request;
79  await register(plainApi, email, password, name);
80  const { accessToken } = await login(plainApi, email, password);
81  const jar = await plain.cookies();
82  const state: AuthState = {
83    cookies: jar.map((c) => ({
84      name: c.name,
85      value: c.value,
86      domain: c.domain,
87      path: c.path,
88      expires: c.expires,
89      httpOnly: c.httpOnly,
90      secure: c.secure,
91      sameSite: c.sameSite,
92    })),
93    origins: accessToken
94      ? [{ origin: WEB_BASE, localStorage: [{ name: "factory.accessToken", value: accessToken }] }]
95      : [],
96  };
97  await plain.close();
98  const context = await browser.newContext({ storageState: state });
99  const page = await context.newPage();
100  return {
101    user: { email, password },
102    page,
103    api: context.request,
104    close: () => context.close(),
105  };
106}
107 
108/** The seeded demo owner, in its own context (a fresh login — the cookie
109 *  + token storage state). */
110async function ownerTab(browser: Browser) {
111  const plain = await browser.newContext();
112  const plainApi = plain.request;
113  await login(plainApi, DEMO_EMAIL, DEMO_PASSWORD);
114  const jar = await plain.cookies();
115  const state: AuthState = {
116    cookies: jar.map((c) => ({
117      name: c.name,
118      value: c.value,
119      domain: c.domain,
120      path: c.path,
121      expires: c.expires,
122      httpOnly: c.httpOnly,
123      secure: c.secure,
124      sameSite: c.sameSite,
125    })),
126    origins: [],
127  };
128  await plain.close();
129  const context = await browser.newContext({ storageState: state });
130  const page = await context.newPage();
131  return { page, close: () => context.close() };
132}
133 
134/** Seed: workspace + page + 3 paragraph blocks, then 3 distinct users in it. */
135async function seed(browser: Browser, api: APIRequestContext) {
136  const ws = await createWorkspace(api, `Presence ${Date.now()}`);
137  const pg = await createPage(api, ws.id, { title: "Presence page" });
138  for (let i = 0; i < 3; i += 1) {
139    await createBlock(api, pg.id, {
140      type: "paragraph",
141      content: { text: ["alpha", "beta", "gamma"][i] },
142      position: `${i + 1}.0`,
143    });
144  }
145  const owner = await ownerTab(browser);
146  const bob = await newUser(browser, "Bob");
147  const carol = await newUser(browser, "Carol");
148  // Add each new user via the internal test seam (TASK-0095 S9 — the D3
149  // unblock; the public invite flow is email-gated and its token is never in
150  // the response). The seam is service-token guarded and e2e-only.
151  await addMemberViaSeam(seamServiceToken(), ws.id, bob.user.email, "MEMBER");
152  await addMemberViaSeam(seamServiceToken(), ws.id, carol.user.email, "MEMBER");
153  const url = `/w/${ws.id}/page/${pg.id}`;
154  return {
155    wsId: ws.id,
156    pageId: pg.id,
157    url,
158    owner,
159    bob,
160    carol,
161    closeAll: async () => {
162      await owner.close().catch(() => {});
163      await bob.close().catch(() => {});
164      await carol.close().catch(() => {});
165    },
166  };
167}
168 
169/** The OTHERS' avatars in the PresenceBar (role=img; accessible name is
170 *  "{name} is viewing this page" — color is never the sole identifier). */
171function avatars(page: Page) {
172  return page.locator('[role="img"][aria-label$="is viewing this page"]');
173}
174 
175/** A peer's cursor name label (the visible pill in the overlay). */
176function cursorLabel(page: Page, name: string) {
177  return page.locator(`div[aria-hidden="true"] span`, {
178    hasText: new RegExp(`^${name.replace(/[.*+?^${}()|[\\]\\\\]/g, "\\$&")}$`),
179  });
180}
181 
182// --- the mechanic -------------------------------------------------------------
183 
184test.describe("TASK-0093 — 3-client presence + live cursors", () => {
185  test("three clients see the other two's avatars within the budget; a leave updates the bars", async ({
186    browser,
187    api,
188  }) => {
189    const s = await seed(browser, api);
190    try {
191      await s.owner.page.goto(s.url);
192      await s.bob.page.goto(s.url);
193      // The 3rd client joins last; its join→avatar delta measures the
194      // re-broadcast catch-up (the server re-sends the peer set on join).
195      const t0 = Date.now();
196      await s.carol.page.goto(s.url);
197      await expect
198        .poll(() => avatars(s.carol.page).count(), {
199          timeout: PRESENCE_BUDGET_MS * 2,
200          message: "the joiner sees the current peer set (re-broadcast)",
201        })
202        .toBe(2);
203      const delta = Date.now() - t0;
204      expect(
205        delta,
206        `join→avatar delta ${delta} ms (DoD metric is 500 ms; this is a 2× flake-superset)`,
207      ).toBeLessThanOrEqual(PRESENCE_BUDGET_MS);
208 
209      // Each client's bar shows the other TWO, with the "2 people are
210      // viewing this page" accessible count.
211      for (const p of [s.owner.page, s.bob.page, s.carol.page]) {
212        await expect.poll(() => avatars(p).count(), { timeout: PRESENCE_BUDGET_MS * 2 }).toBe(2);
213        await expect
214          .poll(
215            async () =>
216              p
217                .locator('div[aria-label*="are viewing this page"]')
218                .first()
219                .getAttribute("aria-label"),
220            {
221              timeout: PRESENCE_BUDGET_MS * 2,
222            },
223          )
224          .toContain("2");
225      }
226 
227      // One leaves: Carol's socket closes → the server announces the
228      // leave → owner + bob see Carol's avatar vanish (3 peers → 2 others).
229      await s.carol.close();
230      for (const p of [s.owner.page, s.bob.page]) {
231        await expect
232          .poll(() => avatars(p).count(), {
233            timeout: LEAVE_BUDGET_MS,
234            message: "the leaver's avatar disappears",
235          })
236          .toBe(1);
237      }
238    } finally {
239      await s.closeAll();
240    }
241  });
242 
243  test("cursors: A types → B and C see A's caret + name label; A hidden → cursor gone, avatar stays; A returns → cursor back", async ({
244    browser,
245    api,
246  }) => {
247    const s = await seed(browser, api);
248    try {
249      await s.owner.page.goto(s.url);
250      await s.bob.page.goto(s.url);
251      await s.carol.page.goto(s.url);
252      await expect
253        .poll(() => avatars(s.bob.page).count(), { timeout: PRESENCE_BUDGET_MS * 2 })
254        .toBe(2);
255 
256      // A (owner) types in block 2 → the caret moves → B and C see A's
257      // cursor: the name label in the overlay, in the right block's
258      // vicinity (the exact 4 px geometry is unit-tested).
259      await s.owner.page
260        .locator("[data-block-id]")
261        .nth(1)
262        .locator('[contenteditable="true"]')
263        .first()
264        .click();
265      await s.owner.page.keyboard.press("End");
266      await s.owner.page.keyboard.type(" hi");
267 
268      await expect
269        .poll(
270          async () => {
271            const label = cursorLabel(s.bob.page, DEMO_NAME).first();
272            if ((await label.count()) === 0) return false;
273            const caretBox = await label.boundingBox();
274            const rowBox = await s.bob.page.locator("[data-block-id]").nth(1).boundingBox();
275            if (!caretBox || !rowBox) return false;
276            // In block 2's vicinity: horizontally within the row's band,
277            // vertically within one row-height above/below (the label sits
278            // just below the caret).
279            return (
280              caretBox.x >= rowBox.x - 8 &&
281              caretBox.x <= rowBox.x + rowBox.width + 8 &&
282              caretBox.y >= rowBox.y - 40 &&
283              caretBox.y <= rowBox.y + rowBox.height + 40
284            );
285          },
286          { timeout: PRESENCE_BUDGET_MS * 2, message: "B sees A's caret in block 2" },
287        )
288        .toBeTruthy();
289      await expect
290        .poll(async () => (await cursorLabel(s.carol.page, DEMO_NAME).count()) > 0, {
291          timeout: PRESENCE_BUDGET_MS * 2,
292          message: "C sees A's caret",
293        })
294        .toBeTruthy();
295 
296      // A's tab goes hidden → viewing:false → A's cursor hides on B/C
297      // within the budget, but A's AVATAR stays (A is still "here").
298      await s.owner.page.evaluate(() => {
299        Object.defineProperty(document, "visibilityState", { configurable: true, value: "hidden" });
300        document.dispatchEvent(new Event("visibilitychange"));
301      });
302      await expect
303        .poll(async () => (await cursorLabel(s.bob.page, DEMO_NAME).count()) === 0, {
304          timeout: LEAVE_BUDGET_MS,
305          message: "A's cursor hides when A's tab is hidden",
306        })
307        .toBeTruthy();
308      expect(await avatars(s.bob.page).count(), "A's avatar stays when A's tab is hidden").toBe(2);
309 
310      // A returns → the cursor reappears.
311      await s.owner.page.evaluate(() => {
312        Object.defineProperty(document, "visibilityState", {
313          configurable: true,
314          value: "visible",
315        });
316        document.dispatchEvent(new Event("visibilitychange"));
317      });
318      await expect
319        .poll(async () => (await cursorLabel(s.bob.page, DEMO_NAME).count()) > 0, {
320          timeout: PRESENCE_BUDGET_MS * 2,
321          message: "A's cursor returns when A's tab is visible",
322        })
323        .toBeTruthy();
324    } finally {
325      await s.closeAll();
326    }
327  });
328 
329  test("stale cursor: B deletes A's block → A's cursor is dropped on B (no orphan node)", async ({
330    browser,
331    api,
332  }) => {
333    const s = await seed(browser, api);
334    try {
335      await s.owner.page.goto(s.url);
336      await s.bob.page.goto(s.url);
337      await s.carol.page.goto(s.url);
338      await expect
339        .poll(() => avatars(s.bob.page).count(), { timeout: PRESENCE_BUDGET_MS * 2 })
340        .toBe(2);
341 
342      // A parks a cursor in block 1 (types once).
343      await s.owner.page
344        .locator("[data-block-id]")
345        .nth(0)
346        .locator('[contenteditable="true"]')
347        .first()
348        .click();
349      await s.owner.page.keyboard.press("End");
350      await s.owner.page.keyboard.type("x");
351      await expect
352        .poll(async () => (await cursorLabel(s.bob.page, DEMO_NAME).count()) > 0, {
353          timeout: PRESENCE_BUDGET_MS * 2,
354          message: "B sees A's cursor in block 1",
355        })
356        .toBeTruthy();
357 
358      // B deletes block 1 via the API (authoritative + deterministic). The
359      // delete publishes `page.updated` → the realtime fan-out sends the
360      // `block:changed` refetch hint → B's overlay refetches (the (b)
361      // mechanic, TASK-0092) → block 1 is gone from B's DOM. A's cursor
362      // still references the deleted blockId → the resolver returns null →
363      // the cursor is DROPPED silently (no orphan node).
364      const blocks = await getBlocks(api, s.pageId);
365      const first = blocks[0];
366      expect(first, "block 1 exists before the delete").toBeTruthy();
367      const del = await api.delete(`/api/v1/blocks/${first.id}`);
368      expect(del.status()).toBeLessThan(300);
369      await expect
370        .poll(async () => s.bob.page.locator("[data-block-id]").count(), { timeout: 3_000 })
371        .toBe(2); // 3 blocks → 2 after the delete
372 
373      // A's cursor label is gone from B's overlay (the stale blockId
374      // dropped); A's avatar STAYS (presence is independent of blocks).
375      await expect
376        .poll(async () => (await cursorLabel(s.bob.page, DEMO_NAME).count()) === 0, {
377          timeout: PRESENCE_BUDGET_MS * 2,
378          message: "A's stale cursor is dropped on B",
379        })
380        .toBeTruthy();
381      expect(await avatars(s.bob.page).count(), "A's avatar stays after the block delete").toBe(2);
382    } finally {
383      await s.closeAll();
384    }
385  });
386 
387  test("a11y: the live region announces presence state; the cursor overlay is aria-hidden", async ({
388    browser,
389    api,
390  }) => {
391    const s = await seed(browser, api);
392    try {
393      await s.owner.page.goto(s.url);
394      await s.bob.page.goto(s.url);
395      // The polite live region (role=status) is attached + visually hidden.
396      const live = s.bob.page.locator('[role="status"]').first();
397      await expect(live).toBeAttached();
398 
399      // A join is a state change → announced (≤ 1/s; the first change
400      // within the window lands immediately).
401      const before = await live.innerText().catch(() => "");
402      await s.carol.page.goto(s.url); // a 3rd client joins
403      await expect
404        .poll(async () => (await live.innerText().catch(() => "")).replace(before, "").trim(), {
405          timeout: PRESENCE_BUDGET_MS * 2,
406          message: "the live region gains an announcement on the join",
407        })
408        .toMatch(/joined|editing|left/);
409 
410      // The cursor overlay is decorative (aria-hidden): the caret + name
411      // label are NOT in the accessibility tree — the announcement is the
412      // SR channel, the cursor is the visual one (spec R5).
413      await s.owner.page
414        .locator("[data-block-id]")
415        .nth(0)
416        .locator('[contenteditable="true"]')
417        .first()
418        .click();
419      await s.owner.page.keyboard.type("a");
420      const overlay = s.bob.page
421        .locator('div[aria-hidden="true"]')
422        .filter({ has: s.bob.page.locator("span") })
423        .last();
424      await expect
425        .poll(async () => (await cursorLabel(s.bob.page, DEMO_NAME).count()) > 0, {
426          timeout: PRESENCE_BUDGET_MS * 2,
427          message: "the cursor renders (visually)",
428        })
429        .toBeTruthy();
430      await expect(overlay).toHaveAttribute("aria-hidden", "true");
431    } finally {
432      await s.closeAll();
433    }
434  });
435 
436  test("reduced motion: the cursor caret has transition-duration 0s (instant)", async ({
437    browser,
438    api,
439  }) => {
440    const ws = await createWorkspace(api, `RM ${Date.now()}`);
441    const owner = await ownerTab(browser);
442    const bob = await newUser(browser, "Bob");
443    // Seam add (TASK-0095 S9 — D3 unblock; see the seed() above).
444    await addMemberViaSeam(seamServiceToken(), ws.id, bob.user.email, "MEMBER");
445    const pg = await createPage(api, ws.id, { title: "RM page" });
446    for (let i = 0; i < 2; i += 1) {
447      await createBlock(api, pg.id, {
448        type: "paragraph",
449        content: { text: ["a", "b"][i] },
450        position: `${i + 1}.0`,
451      });
452    }
453    const url = `/w/${ws.id}/page/${pg.id}`;
454    // Bob in a reduced-motion context (the Phase-4 flag).
455    const rm = await browser.newContext({
456      storageState: await bob.page.context().storageState(),
457      reducedMotion: "reduce",
458    });
459    const rmPage = await rm.newPage();
460    try {
461      await owner.page.goto(url);
462      await rmPage.goto(url);
463      await expect.poll(() => avatars(rmPage).count(), { timeout: PRESENCE_BUDGET_MS * 2 }).toBe(1);
464      await owner.page
465        .locator("[data-block-id]")
466        .nth(0)
467        .locator('[contenteditable="true"]')
468        .first()
469        .click();
470      await owner.page.keyboard.type("x");
471      await expect
472        .poll(async () => (await cursorLabel(rmPage, DEMO_NAME).count()) > 0, {
473          timeout: PRESENCE_BUDGET_MS * 2,
474          message: "the cursor renders under reduced motion",
475        })
476        .toBeTruthy();
477      // The caret spans have no CSS transition (the global
478      // prefers-reduced-motion rule + the layer sets none) — instant.
479      const dur = await rmPage
480        .locator('div[aria-hidden="true"] span')
481        .first()
482        .evaluate((el) => getComputedStyle(el).transitionDuration);
483      expect(dur, `caret transition-duration under reduced motion (got ${dur})`).toBe("0s");
484    } finally {
485      await owner.close().catch(() => {});
486      await rm.close().catch(() => {});
487      await bob.close().catch(() => {});
488    }
489  });
490});
491