Hamster E2E Realtime Testing Patterns
Overview
Deterministic patterns for E2E tests that seed data via Supabase admin client and expect it to appear in the browser via postgres_changes. Eliminates flaky timeouts by guaranteeing subscription readiness before writing.
When to Apply
- Writing E2E tests that insert/update data via admin client and expect realtime propagation
- Testing features that use
postgres_changes (chat threads, Y.js document sync, live updates)
- Any test where the browser receives data via Supabase Realtime WebSocket
Quick Reference
| Task |
Pattern |
Reference |
| Seed data via DB with realtime delivery |
Pre-subscribe → write → wait |
realtime-seeding.md |
| Wait for browser channel subscription |
WebSocket interception |
browser-interception.md |
| Wait for server-side event delivery |
waitForRealtimeEvent |
server-listener.md |
Core Pattern
// 1. Wait for browser's realtime channel to be subscribed
await pageObject.waitForDocumentChannelSubscribed(documentId);
// 2. Set up server-side listener
const rt = waitForRealtimeEvent({
table: 'document',
filter: `id=eq.${documentId}`,
event: 'UPDATE',
});
await rt.subscribed;
// 3. Write to DB — both browser and test harness are listening
await adminClient.from('document').update({ ... }).eq('id', documentId);
// 4. Wait for event delivery confirmation
await rt.event;
// 5. Assert UI updated
await expect(page.locator('[data-test="tiptap-editor"] img')).toHaveCount(1);
Anti-Patterns (MUST NOT)
// WRONG — arbitrary timeout, no subscription guarantee
await page.waitForTimeout(3000);
await adminClient.from('documents').update({ ... });
// WRONG — polling without subscription guarantee
await expect(async () => {
const count = await page.locator('img').count();
expect(count).toBeGreaterThanOrEqual(1);
}).toPass({ timeout: 30000 });
Known Channel Names
| Feature |
Channel Topic |
Table |
Event |
| Chat thread items |
realtime:thread:${threadId}:items |
thread_items |
INSERT |
| Thread summary/metadata |
realtime:thread-summary:${threadId} |
threads |
UPDATE |
| Y.js document sync |
realtime:yjs:doc:${documentId} |
document |
UPDATE |
Page Object Integration
POs that extend ChatPageObject have access to this.realtimeInterceptor (protected):
export class MyFeaturePageObject extends BriefsPageObject {
async waitForDocumentChannelSubscribed(documentId: string, timeoutMs = 15_000) {
await this.realtimeInterceptor.waitForChannel(
`realtime:yjs:doc:${documentId}`,
timeoutMs,
);
}
}
References
- realtime-seeding.md - Full deterministic seeding pattern with sequence diagram
- browser-interception.md - Browser-side WebSocket interception
- server-listener.md - Server-side
waitForRealtimeEvent utility
Key Files
| File |
Purpose |
apps/e2e/tests/utils/realtime.ts |
waitForRealtimeEvent — server-side listener |
apps/e2e/tests/utils/realtime-interception.ts |
createRealtimeInterceptor — browser WebSocket tracking |
apps/e2e/tests/chat/chat.po.ts |
ChatPageObject — base PO with realtime interceptor |
apps/e2e/tests/chat/utils/thread-seed-utils.ts |
Reference implementation (threads) |
packages/y-supabase/src/provider.ts |
SupabaseCollabProvider — channel naming, self-save filter |