How to Test Presence Avatars Online with Playwright: Multi-Tab Coordination, Heartbeats, and State Transitions

Goal:When User A opens a document, User B (already viewing the document) sees User A's avatar appear in the presence indicator within 2 seconds. The avatar should display the correct initials or profile image, and a tooltip should show User A's name.

Preconditions: Both users are authenticated. User B is already on the document page. The WebSocket connection is established.

Playwright Implementation

What to Assert Beyond the UI

Check the WebSocket messages directly to verify the server is broadcasting the correct presence payload. Playwright lets you intercept WebSocket frames using the page.on('websocket') event. Verify that the presence message includes the correct user ID, display name, avatar URL, and a status of "online". Also confirm that the message arrives within your SLA (typically under 500ms for a local test environment).

test('joining user appears in presence', async ({ browser }) => {
  const ctxA = await browser.newContext({ storageState: './auth/user-a.json' });
  const ctxB = await browser.newContext({ storageState: './auth/user-b.json' });
  const pageA = await ctxA.newPage();
  const pageB = await ctxB.newPage();

  await pageB.goto('/docs/test-document-123');
  await pageB.waitForSelector('[data-testid="presence-indicator"]');
  await pageA.goto('/docs/test-document-123');

  const avatars = pageB.locator('[data-testid="presence-avatar"]');
  await expect(avatars).toHaveCount(2, { timeout: 5000 });
  await expect(avatars.nth(1)).toContainText('AC');
  await ctxA.close();
  await ctxB.close();
});

Goal: When User A opens the same document in three browser tabs, other users should see exactly one avatar for User A, not three. When User A closes two of those tabs, the avatar should remain visible. Only when the last tab is closed should the avatar disappear.

Preconditions: User A is authenticated. User B is viewing the document. The presence system uses a connection-count or session-deduplication strategy.

This scenario catches one of the most common presence bugs: each tab registers a separate WebSocket connection, and naive implementations count each connection as a distinct user. The fix is typically server-side deduplication keyed by user ID rather than connection ID, combined with a reference counter that tracks how many connections a single user has open. The avatar should only be removed when the reference count drops to zero.

Playwright Implementation

What to Assert Beyond the UI

Intercept WebSocket frames on User B's page to verify the server sends a single presence:join event for User A (not three). When tabs close, verify the server does not broadcast presence:leave until the last connection for that user is gone. You can also query the presence API endpoint directly to confirm the server-side member count matches the UI.

Goal:When more users are present than the avatar stack can display (e.g., 7 users in a stack that shows 4), the component should render the first N avatars with correct z-index stacking and show a “+3” overflow pill. Avatars should overlap with consistent negative margins and maintain the correct visual order.

Preconditions: The MAX_VISIBLE_AVATARS constant is set to 4. Seven test users are seeded in the database. All seven navigate to the same document.

Playwright Implementation

What to Assert Beyond the UI

Beyond visual checks, verify the DOM structure and CSS properties programmatically. The avatar stack should use position: relative with decreasing z-index values so the first avatar renders on top. The negative margin-left on each subsequent avatar creates the overlap effect. Screenshot comparison can catch subtle rendering regressions that DOM assertions miss, such as avatar images not loading or border radius changes breaking the circular shape.

test('overflow pill shows correct count', async ({ browser }) => {
  const contexts = await Promise.all(
    Array.from({ length: 8 }, (_, i) =>
      browser.newContext({ storageState: `./auth/user-${i}.json` })
    )
  );
  const observer = await contexts[0].newPage();
  await observer.goto('/docs/test-document-123');
  for (let i = 1; i < 8; i++) {
    const p = await contexts[i].newPage();
    await p.goto('/docs/test-document-123');
  }
  await observer.waitForTimeout(3000);
  const pill = observer.locator('[data-testid="presence-overflow"]');
  await expect(pill).toContainText('+4');
  await Promise.all(contexts.map(c => c.close()));
});

Goal:When User A stops interacting with the page (no mouse movement, no keyboard input, no scroll) for longer than the idle threshold, their avatar should transition from “online” (green dot) to “away” (yellow dot). When they resume activity, the avatar should transition back to “online” within one heartbeat interval.

Preconditions: The idle threshold is configured to 3 seconds for testing. Both users are viewing the document. User A is currently shown as online.

Testing idle detection is tricky because Playwright tests inherently generate no user input. By default, a Playwright page is “idle” the moment you stop sending actions. This means you need to either continuously dispatch synthetic events to keep a user “active,” or you need to design your test so that the lack of input is the trigger you are testing.

Playwright Implementation

Goal:When User A's WebSocket connection is severed without a clean disconnect (simulating a network failure or browser crash), the presence system should detect the missed heartbeats and remove User A's avatar after the timeout period. The transition should not be instantaneous; there should be a grace period to handle transient network blips.

Preconditions: Heartbeat interval is 2 seconds. Presence timeout is 5 seconds (missing roughly 2 heartbeats triggers removal). Both users are viewing the document and showing as online.

This scenario is critical because it tests the server-side timeout logic rather than relying on a clean WebSocket.close() event. In production, users lose connectivity, laptop lids close, and mobile browsers get killed by the OS. The presence system must handle all of these gracefully, and the only way to test it is to simulate an unclean disconnect by blocking network traffic rather than closing the page.

Playwright Implementation

test('missed heartbeats trigger avatar removal', async ({ browser }) => {
  const ctxA = await browser.newContext({ storageState: './auth/user-a.json' });
  const ctxB = await browser.newContext({ storageState: './auth/user-b.json' });
  const pageA = await ctxA.newPage();
  const pageB = await ctxB.newPage();
  await pageB.goto('/docs/test-document-123');
  await pageA.goto('/docs/test-document-123');
  const avatars = pageB.locator('[data-testid="presence-avatar"]');
  await expect(avatars).toHaveCount(2, { timeout: 5000 });
  const cdp = await pageA.context().newCDPSession(pageA);
  await cdp.send('Network.emulateNetworkConditions', {
    offline: true, downloadThroughput: 0, uploadThroughput: 0, latency: 0
  });
  await expect(avatars).toHaveCount(1, { timeout: 10_000 });
  await ctxA.close();
  await ctxB.close();
});

Goal:When User A experiences a brief network interruption (under the heartbeat timeout), the WebSocket client should automatically reconnect, re-register presence, and User A's avatar should remain visible to other users without flickering. If the interruption exceeds the timeout and the avatar was removed, it should reappear upon reconnection.

Preconditions: The WebSocket client implements exponential backoff reconnection. The heartbeat timeout is 5 seconds. Both users are viewing the document.

Playwright Implementation

What to Assert Beyond the UI

Monitor the WebSocket reconnection attempts by intercepting frames on User A's page. Verify the client uses exponential backoff (the delay between reconnection attempts should increase). After reconnection, verify the client sends a fresh presence:joinmessage and that the server responds with the current participant list. This ensures the client's local presence state is synchronized with the server after the outage.