@monoes/monobrowse 1.0.12 → 1.0.14

package/src/__tests__/cdp-transport.test.ts

@@ -0,0 +1,198 @@
+/**
+ * The transport seam under CdpClient.
+ *
+ * Two halves: WebSocketTransport must behave exactly as the inlined `ws`
+ * handling it replaced (that is what keeps the 474 existing tests honest),
+ * and CdpClient must drive *any* transport — the whole point of the seam,
+ * since the bridge-backed one is not a socket to a local Chrome at all.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+// --- fake `ws` -------------------------------------------------------------
+let lastSocket: FakeWs | null = null;
+
+class FakeWs {
+  handlers = new Map<string, Array<(...a: unknown[]) => void>>();
+  sent: string[] = [];
+  closed = false;
+  sendError: Error | null = null;
+
+  constructor(public url: string) {
+    lastSocket = this;
+  }
+
+  on(event: string, fn: (...a: unknown[]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, []);
+    this.handlers.get(event)!.push(fn);
+  }
+
+  emit(event: string, ...args: unknown[]): void {
+    for (const fn of [...(this.handlers.get(event) ?? [])]) fn(...args);
+  }
+
+  send(data: string, cb?: (err?: Error) => void): void {
+    this.sent.push(data);
+    cb?.(this.sendError ?? undefined);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+}
+
+vi.mock('ws', () => ({ WebSocket: FakeWs }));
+
+const { WebSocketTransport } = await import('../browser/transport.js');
+const { CdpClient } = await import('../browser/cdp.js');
+
+import type { CdpTransport, CdpTransportHandlers } from '../browser/transport.js';
+
+/** Collects what a transport hands back up to its owner. */
+function recorder(): CdpTransportHandlers & {
+  messages: string[];
+  closes: Array<Error | undefined>;
+} {
+  const messages: string[] = [];
+  const closes: Array<Error | undefined> = [];
+  const errors: Error[] = [];
+  return {
+    messages,
+    closes,
+    message: (d: string) => void messages.push(d),
+    close: (e?: Error) => void closes.push(e),
+    error: (e: Error) => void errors.push(e),
+  };
+}
+
+describe('WebSocketTransport', () => {
+  it('opens on the socket "open" event and reports the url it dialed', async () => {
+    const t = new WebSocketTransport('ws://127.0.0.1:9222/devtools/page/ABC');
+    const p = t.open(recorder());
+    lastSocket!.emit('open');
+    await p;
+    expect(lastSocket!.url).toBe('ws://127.0.0.1:9222/devtools/page/ABC');
+  });
+
+  it('rejects open() when the socket errors before it ever opened', async () => {
+    const t = new WebSocketTransport('ws://127.0.0.1:1/devtools');
+    const p = t.open(recorder());
+    lastSocket!.emit('error', new Error('ECONNREFUSED'));
+    await expect(p).rejects.toThrow('ECONNREFUSED');
+  });
+
+  it('routes a post-open error to error(), not to a rejected open()', async () => {
+    const h = recorder();
+    const errors: Error[] = [];
+    h.error = (e: Error) => void errors.push(e);
+    const t = new WebSocketTransport('ws://x');
+    const p = t.open(h);
+    lastSocket!.emit('open');
+    await p;
+    lastSocket!.emit('error', new Error('EPIPE'));
+    expect(errors.map((e) => e.message)).toEqual(['EPIPE']);
+  });
+
+  it('delivers messages as strings and reports close', async () => {
+    const h = recorder();
+    const t = new WebSocketTransport('ws://x');
+    const p = t.open(h);
+    lastSocket!.emit('open');
+    await p;
+    lastSocket!.emit('message', Buffer.from('{"id":1}'));
+    expect(h.messages).toEqual(['{"id":1}']);
+    lastSocket!.emit('close');
+    expect(h.closes).toHaveLength(1);
+  });
+
+  it('rejects send() with the socket error and closes the socket on close()', async () => {
+    const t = new WebSocketTransport('ws://x');
+    const p = t.open(recorder());
+    lastSocket!.emit('open');
+    await p;
+    await expect(t.send('{"id":1}')).resolves.toBeUndefined();
+    expect(lastSocket!.sent).toEqual(['{"id":1}']);
+    lastSocket!.sendError = new Error('socket gone');
+    await expect(t.send('{"id":2}')).rejects.toThrow('socket gone');
+    t.close();
+    expect(lastSocket!.closed).toBe(true);
+  });
+});
+
+// --- CdpClient over an arbitrary transport ---------------------------------
+
+/** A transport with no socket at all: the test *is* the other end. */
+class ScriptedTransport implements CdpTransport {
+  sent: string[] = [];
+  closed = false;
+  private handlers: CdpTransportHandlers | null = null;
+
+  async open(handlers: CdpTransportHandlers): Promise<void> {
+    this.handlers = handlers;
+  }
+
+  async send(frame: string): Promise<void> {
+    this.sent.push(frame);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  /** Push a frame up as if it had arrived from the other side. */
+  deliver(msg: unknown): void {
+    this.handlers!.message(JSON.stringify(msg));
+  }
+
+  drop(err?: Error): void {
+    this.handlers!.close(err);
+  }
+}
+
+describe('CdpClient.connectTransport', () => {
+  it('round-trips a command through a transport that is not a socket', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+    expect(client.isConnected()).toBe(true);
+
+    const pending = client.send<{ frameId: string }>('Page.navigate', { url: 'https://x.test' });
+    const sent = JSON.parse(t.sent[0]);
+    expect(sent.method).toBe('Page.navigate');
+    expect(sent.params).toEqual({ url: 'https://x.test' });
+
+    t.deliver({ id: sent.id, result: { frameId: 'F1' } });
+    expect(await pending).toEqual({ frameId: 'F1' });
+  });
+
+  it('dispatches events with their sessionId to listeners', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+
+    const seen: Array<[Record<string, unknown>, string | undefined]> = [];
+    client.on('Network.responseReceived', (params, sid) => void seen.push([params, sid]));
+    t.deliver({ method: 'Network.responseReceived', params: { requestId: 'R1' }, sessionId: 'S1' });
+
+    expect(seen).toEqual([[{ requestId: 'R1' }, 'S1']]);
+  });
+
+  it('flushes in-flight commands when the transport drops', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+
+    const pending = client.send('Page.enable');
+    t.drop(new Error('bridge disconnected'));
+    await expect(pending).rejects.toThrow('bridge disconnected');
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('closes the transport when the client closes', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+    client.close();
+    expect(t.closed).toBe(true);
+    await expect(client.send('Page.enable')).rejects.toThrow('CDP not connected');
+  });
+});

package/src/__tests__/profiler-heap.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Regression cover for the 0-byte heap snapshot.
+ *
+ * Chrome emits `HeapProfiler.reportHeapSnapshotProgress` with finished:true
+ * BEFORE it streams a single `addHeapSnapshotChunk` (verified against Chrome
+ * 153). startHeapSnapshot used to resolve on that progress event, detach its
+ * chunk listener and write an empty file every time. The stub below replays
+ * that exact ordering, so a regression fails here rather than in a profiling
+ * session nobody notices until DevTools refuses to load the snapshot.
+ */
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { CdpClient } from '../browser/cdp.js';
+import { startHeapSnapshot } from '../browser/profiler.js';
+
+type Listener = (params: Record<string, unknown>, sessionId?: string) => void;
+
+interface StubOptions {
+  /** Chunks Chrome streams, in order. */
+  chunks?: string[];
+  /** sessionId Chrome tags the chunk events with (defaults to the caller's). */
+  chunkSessionId?: string;
+  /** Emit the misleading finished:true progress event before the chunks. */
+  emitProgressFirst?: boolean;
+}
+
+/**
+ * A CdpClient that replays Chrome's real takeHeapSnapshot sequence: progress
+ * events first, then the chunks, and only then the command response.
+ */
+function heapClient(sessionId: string, options: StubOptions = {}) {
+  const { chunks = ['{"snapshot":', '{"node_count":2}', '}'], emitProgressFirst = true } = options;
+  const listeners = new Map<string, Set<Listener>>();
+  const calls: string[] = [];
+
+  const emit = (event: string, params: Record<string, unknown>, sid?: string) => {
+    for (const fn of listeners.get(event) ?? []) fn(params, sid);
+  };
+
+  // Chrome delivers each of these in its own WebSocket frame, so the stub
+  // yields between them. Emitting synchronously would paper over the very
+  // bug this file exists to catch: the buggy implementation resolved on the
+  // progress event, and only lost the chunks because they arrived a turn
+  // later, after its `finally` had detached the listener.
+  const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+
+  const client = {
+    on: vi.fn((event: string, fn: Listener) => {
+      if (!listeners.has(event)) listeners.set(event, new Set());
+      listeners.get(event)!.add(fn);
+      return () => listeners.get(event)?.delete(fn);
+    }),
+    send: vi.fn(async (method: string, _params?: unknown, _sid?: string) => {
+      calls.push(method);
+      if (method === 'HeapProfiler.takeHeapSnapshot') {
+        if (emitProgressFirst) {
+          emit(
+            'HeapProfiler.reportHeapSnapshotProgress',
+            { done: 1, total: 1, finished: true },
+            sessionId,
+          );
+          await tick();
+        }
+        for (const chunk of chunks) {
+          emit('HeapProfiler.addHeapSnapshotChunk', { chunk }, options.chunkSessionId ?? sessionId);
+          await tick();
+        }
+      }
+      return {};
+    }),
+  } as unknown as CdpClient;
+
+  return { client, calls, listeners };
+}
+
+const dirs: string[] = [];
+async function outPath(name = 'heap.heapsnapshot'): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'monobrowse-heap-'));
+  dirs.push(dir);
+  return join(dir, name);
+}
+
+afterEach(async () => {
+  await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })));
+});
+
+let seq = 0;
+const nextSession = () => `sid-${++seq}`;
+
+describe('startHeapSnapshot', () => {
+  it('writes every streamed chunk, not an empty file', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid);
+
+    const written = await startHeapSnapshot(client, sid, path);
+
+    expect(written).toBe(path);
+    const contents = await readFile(path, 'utf8');
+    expect(contents).toBe('{"snapshot":{"node_count":2}}');
+    expect(contents.length).toBeGreaterThan(0);
+  });
+
+  it('does not resolve on the finished progress event that precedes the chunks', async () => {
+    // The regression: with emitProgressFirst the old implementation resolved
+    // before any chunk arrived. Ordering is the whole point of this case.
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, {
+      emitProgressFirst: true,
+      chunks: ['a'.repeat(64), 'b'.repeat(64)],
+    });
+
+    await startHeapSnapshot(client, sid, path);
+
+    expect((await readFile(path, 'utf8')).length).toBe(128);
+  });
+
+  it('works when Chrome sends no progress events at all', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, { emitProgressFirst: false, chunks: ['{}'] });
+    await expect(startHeapSnapshot(client, sid, path)).resolves.toBe(path);
+    await expect(readFile(path, 'utf8')).resolves.toBe('{}');
+  });
+
+  it('asks Chrome not to report progress, since nothing consumes it', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid);
+    await startHeapSnapshot(client, sid, path);
+    const take = (client.send as ReturnType<typeof vi.fn>).mock.calls.find(
+      (c) => c[0] === 'HeapProfiler.takeHeapSnapshot',
+    );
+    expect(take?.[1]).toEqual({ reportProgress: false });
+  });
+
+  it('enables and disables the heap profiler around the capture', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client, calls } = heapClient(sid);
+    await startHeapSnapshot(client, sid, path);
+    expect(calls).toEqual([
+      'HeapProfiler.enable',
+      'HeapProfiler.takeHeapSnapshot',
+      'HeapProfiler.disable',
+    ]);
+  });
+
+  it('ignores chunks belonging to another session', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, { chunkSessionId: 'other-session' });
+    await expect(startHeapSnapshot(client, sid, path)).rejects.toThrow(/no data/i);
+  });
+
+  it('fails loudly instead of writing a 0-byte snapshot', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client } = heapClient(sid, { chunks: [] });
+    await expect(startHeapSnapshot(client, sid, path)).rejects.toThrow(/produced no data/);
+    await expect(readFile(path, 'utf8')).rejects.toThrow();
+  });
+
+  it('detaches its chunk listener once the snapshot is done', async () => {
+    const path = await outPath();
+    const sid = nextSession();
+    const { client, listeners } = heapClient(sid);
+    await startHeapSnapshot(client, sid, path);
+    expect(listeners.get('HeapProfiler.addHeapSnapshotChunk')?.size ?? 0).toBe(0);
+  });
+
+  it('releases the in-progress guard after a failure, so a retry is possible', async () => {
+    const failing = {
+      on: vi.fn(() => () => {}),
+      send: vi.fn(async (method: string) => {
+        if (method === 'HeapProfiler.takeHeapSnapshot') throw new Error('target crashed');
+        return {};
+      }),
+    } as unknown as CdpClient;
+
+    const sid = nextSession();
+    await expect(startHeapSnapshot(failing, sid)).rejects.toThrow('target crashed');
+
+    const path = await outPath();
+    const { client } = heapClient(sid);
+    await expect(startHeapSnapshot(client, sid, path)).resolves.toBe(path);
+  });
+});

package/src/__tests__/report-a11y.test.ts

@@ -0,0 +1,180 @@
+/**
+ * The a11y rules are pure functions over a CDP accessibility tree, so the
+ * fixtures here are hand-written AX node arrays — no Chrome involved.
+ */
+import { describe, expect, it } from 'vitest';
+import {
+  countA11y,
+  findFocusOrderIssues,
+  findHeadingIssues,
+  findNamingIssues,
+  orderNodes,
+  runA11yRules,
+} from '../report/a11y.js';
+import type { AxNode, FocusCandidate } from '../report/types.js';
+
+function node(partial: Partial<AxNode> & { nodeId: string | number }): AxNode {
+  return partial as AxNode;
+}
+
+function ax(nodeId: string | number, role: string, name = '', extra: Partial<AxNode> = {}): AxNode {
+  return node({ nodeId, role: { value: role }, name: { value: name }, ...extra });
+}
+
+function heading(nodeId: string | number, level: number, name = `h${level}`): AxNode {
+  return node({
+    nodeId,
+    role: { value: 'heading' },
+    name: { value: name },
+    properties: [{ name: 'level', value: { value: level } }],
+  });
+}
+
+describe('findNamingIssues', () => {
+  it('flags a button with no accessible name', () => {
+    const findings = findNamingIssues([ax(1, 'button', '')]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({
+      rule: 'unlabelled-control',
+      impact: 'error',
+      role: 'button',
+      name: null,
+      locator: 'ax-node:1',
+    });
+  });
+
+  it('leaves named controls alone, including whitespace-trimmed names', () => {
+    expect(findNamingIssues([ax(1, 'button', 'Save'), ax(2, 'link', 'Home')])).toEqual([]);
+  });
+
+  it('treats a whitespace-only name as no name', () => {
+    expect(findNamingIssues([ax(1, 'link', '   ')])).toHaveLength(1);
+  });
+
+  it('reports an unlabelled form field under its own rule, not unlabelled-control', () => {
+    const findings = findNamingIssues([ax(1, 'textbox', '')]);
+    expect(findings[0].rule).toBe('form-field-no-label');
+    expect(findings[0].impact).toBe('error');
+  });
+
+  it('flags an image with no alt text', () => {
+    const findings = findNamingIssues([ax(1, 'image', '')]);
+    expect(findings[0].rule).toBe('image-missing-alt');
+  });
+
+  it('does not flag a decorative image, which the AX tree marks ignored', () => {
+    expect(findNamingIssues([ax(1, 'image', '', { ignored: true })])).toEqual([]);
+  });
+
+  it('uses a resolved CSS selector as the locator when one is supplied', () => {
+    const locators = new Map([[42, '#submit']]);
+    const findings = findNamingIssues([ax(1, 'button', '', { backendDOMNodeId: 42 })], locators);
+    expect(findings[0].locator).toBe('#submit');
+  });
+
+  it('ignores roles that carry no naming requirement', () => {
+    expect(findNamingIssues([ax(1, 'paragraph', ''), ax(2, 'generic', '')])).toEqual([]);
+  });
+});
+
+describe('findHeadingIssues', () => {
+  it('flags a skipped heading level', () => {
+    const findings = findHeadingIssues([heading(1, 1), heading(2, 3)]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0].rule).toBe('heading-order-jump');
+    expect(findings[0].impact).toBe('warning');
+    expect(findings[0].detail).toContain('h1 -> h3');
+  });
+
+  it('accepts a well-formed outline, including going back up a level', () => {
+    expect(findHeadingIssues([heading(1, 1), heading(2, 2), heading(3, 3), heading(4, 2)])).toEqual(
+      [],
+    );
+  });
+
+  it('flags a document whose first heading is not h1', () => {
+    const findings = findHeadingIssues([heading(1, 2)]);
+    expect(findings[0].detail).toContain('starts at h2');
+  });
+
+  it('reads levels in document order, not array order', () => {
+    // Array order says h1, h3, h2 (a jump); tree order says h1, h2, h3 (fine).
+    const nodes = [
+      node({ nodeId: 'root', role: { value: 'main' }, childIds: ['a', 'c', 'b'] }),
+      { ...heading('b', 3), parentId: 'root' },
+      { ...heading('a', 1), parentId: 'root' },
+      { ...heading('c', 2), parentId: 'root' },
+    ];
+    expect(findHeadingIssues(nodes)).toEqual([]);
+  });
+
+  it('skips headings with no usable level property', () => {
+    expect(findHeadingIssues([ax(1, 'heading', 'Untitled')])).toEqual([]);
+  });
+});
+
+describe('orderNodes', () => {
+  it('walks childIds depth-first and keeps unreachable nodes rather than dropping them', () => {
+    const nodes = [
+      node({ nodeId: 'r', childIds: ['x'] }),
+      node({ nodeId: 'x', parentId: 'r', childIds: ['y'] }),
+      node({ nodeId: 'y', parentId: 'x' }),
+      node({ nodeId: 'orphan', parentId: 'gone' }),
+    ];
+    expect(orderNodes(nodes).map((n) => n.nodeId)).toEqual(['r', 'x', 'y', 'orphan']);
+  });
+
+  it('does not loop forever on a cyclic tree', () => {
+    const nodes = [
+      node({ nodeId: 'a', childIds: ['b'] }),
+      node({ nodeId: 'b', parentId: 'a', childIds: ['a'] }),
+    ];
+    expect(orderNodes(nodes)).toHaveLength(2);
+  });
+});
+
+describe('findFocusOrderIssues', () => {
+  const candidate = (partial: Partial<FocusCandidate>): FocusCandidate => ({
+    tag: 'button',
+    role: '',
+    name: 'Next',
+    tabindex: -1,
+    locator: '#next',
+    ...partial,
+  });
+
+  it('flags a natively focusable element taken out of the tab order', () => {
+    const findings = findFocusOrderIssues([candidate({})]);
+    expect(findings).toHaveLength(1);
+    expect(findings[0]).toMatchObject({ rule: 'negative-tabindex', impact: 'warning' });
+    expect(findings[0].detail).toContain('tabindex="-1"');
+  });
+
+  it('ignores non-negative tabindex', () => {
+    expect(findFocusOrderIssues([candidate({ tabindex: 0 })])).toEqual([]);
+  });
+
+  it('ignores a plain container that is merely script-focusable', () => {
+    expect(findFocusOrderIssues([candidate({ tag: 'div', role: '' })])).toEqual([]);
+  });
+
+  it('flags a div that claims an interactive role', () => {
+    expect(findFocusOrderIssues([candidate({ tag: 'div', role: 'button' })])).toHaveLength(1);
+  });
+});
+
+describe('runA11yRules', () => {
+  it('combines every rule and counts errors separately from warnings', () => {
+    const findings = runA11yRules({
+      nodes: [ax(1, 'button', ''), ax(2, 'image', ''), heading(3, 1), heading(4, 4)],
+      focusCandidates: [{ tag: 'a', role: '', name: 'Skip', tabindex: -1, locator: '#skip' }],
+    });
+    expect(findings.map((f) => f.rule).sort()).toEqual([
+      'heading-order-jump',
+      'image-missing-alt',
+      'negative-tabindex',
+      'unlabelled-control',
+    ]);
+    expect(countA11y(findings)).toEqual({ errors: 2, warnings: 2 });
+  });
+});