@monoes/monobrowse 1.0.12 → 1.0.14

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

@@ -0,0 +1,293 @@
+/**
+ * RIG-13 — run history on disk and the trends computed from it.
+ *
+ * The filesystem half uses a scratch directory under the monomind data dir
+ * (never the shared /tmp) and points MONOBROWSE_HISTORY_DIR at it, so no test
+ * can touch a real history.
+ */
+import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { buildReport } from '../report/analyze.js';
+import { DEFAULT_BUDGET } from '../report/budget.js';
+import {
+  type HistoryRun,
+  historyKey,
+  listRuns,
+  loadRunScreenshot,
+  pruneHistory,
+  saveRun,
+  toHistoryRun,
+} from '../report/history.js';
+import { encodePng, pngToDataUrl } from '../report/png.js';
+import { buildTrend, formatTrendDelta, formatTrendValue } from '../report/trend.js';
+import type { Budget, CaptureData, Report, VitalsData } from '../report/types.js';
+
+function capture(partial: Partial<CaptureData> = {}): CaptureData {
+  return {
+    url: 'https://shop.test/checkout',
+    finalUrl: 'https://shop.test/checkout',
+    title: 'Checkout',
+    capturedAt: '2026-09-21T10:00:00.000Z',
+    durationMs: 1200,
+    console: [],
+    pageErrors: [],
+    requests: [],
+    vitals: { lcp: 2000, cls: 0.01, inp: 50 },
+    a11y: [],
+    screenshots: [],
+    notes: [],
+    ...partial,
+  };
+}
+
+const report = (partial: Partial<CaptureData> = {}, budget: Budget = DEFAULT_BUDGET): Report =>
+  buildReport(capture(partial), budget);
+
+/** A prior run, shaped exactly as it comes back off disk. */
+function historyRun(
+  capturedAt: string,
+  vitals: VitalsData,
+  counts: Partial<Report['counts']> = {},
+) {
+  const run = toHistoryRun(report({ capturedAt, vitals }), `id-${capturedAt}`);
+  run.counts = { ...run.counts, ...counts };
+  run.verdict = (counts.consoleErrors ?? 0) > 0 ? 'fail' : 'pass';
+  return run;
+}
+
+function tinyPng(width = 4, height = 4, shade = 200) {
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) data.set([shade, shade, shade, 255], i * 4);
+  return encodePng({ width, height, data });
+}
+
+// ---------------------------------------------------------------------------
+// Storage
+// ---------------------------------------------------------------------------
+
+describe('historyKey', () => {
+  it('is readable and includes a hash of the full URL', () => {
+    expect(historyKey('https://shop.test/checkout')).toMatch(/^shop\.test-checkout-[0-9a-f]{8}$/);
+  });
+
+  it('does not collide across URLs that differ only in the query string', () => {
+    expect(historyKey('https://a.test/list?page=2')).not.toBe(
+      historyKey('https://a.test/list?page=3'),
+    );
+  });
+
+  it('survives a string that is not a URL at all', () => {
+    expect(historyKey('not a url')).toMatch(/^not-a-url-[0-9a-f]{8}$/);
+  });
+});
+
+describe('run history on disk', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    await mkdir(join(homedir(), '.monomind'), { recursive: true });
+    root = await mkdtemp(join(homedir(), '.monomind', 'monobrowse-history-test-'));
+    process.env.MONOBROWSE_HISTORY_DIR = root;
+  });
+
+  afterEach(async () => {
+    delete process.env.MONOBROWSE_HISTORY_DIR;
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it('writes one JSON record per run, keyed by URL', async () => {
+    const saved = await saveRun(report(), { root, id: '20260921T100000Z-aaaaaaaa' });
+    expect(saved.dir).toBe(join(root, historyKey('https://shop.test/checkout')));
+    const files = await readdir(saved.dir);
+    expect(files).toContain('20260921T100000Z-aaaaaaaa.json');
+    expect(files).toContain('url.txt');
+  });
+
+  it('archives the main screenshot alongside so the next run can diff pixels', async () => {
+    const png = tinyPng();
+    const saved = await saveRun(
+      report({
+        screenshots: [{ label: 'page', width: 4, height: 4, dataUrl: pngToDataUrl(png) }],
+      }),
+      { root, id: '20260921T100000Z-bbbbbbbb' },
+    );
+    expect(saved.run.screenshotFile).toBe('20260921T100000Z-bbbbbbbb.png');
+    const loaded = await loadRunScreenshot(saved.dir, saved.run);
+    expect(loaded && Buffer.from(loaded).equals(png)).toBe(true);
+  });
+
+  it('returns null for a screenshot that was never archived', async () => {
+    const saved = await saveRun(report(), { root, id: '20260921T100000Z-cccccccc' });
+    expect(await loadRunScreenshot(saved.dir, saved.run)).toBeNull();
+  });
+
+  it('lists runs oldest first', async () => {
+    for (const ts of ['2026-09-21T12:00:00.000Z', '2026-09-21T10:00:00.000Z']) {
+      await saveRun(report({ capturedAt: ts }), { root });
+    }
+    const dir = join(root, historyKey('https://shop.test/checkout'));
+    expect((await listRuns(dir)).map((r) => r.capturedAt)).toEqual([
+      '2026-09-21T10:00:00.000Z',
+      '2026-09-21T12:00:00.000Z',
+    ]);
+  });
+
+  it('prunes to the configured maximum, oldest first, taking the PNGs with them', async () => {
+    const dir = join(root, historyKey('https://shop.test/checkout'));
+    for (let i = 0; i < 5; i++) {
+      await saveRun(
+        report({
+          capturedAt: `2026-09-2${i + 1}T10:00:00.000Z`,
+          screenshots: [{ label: 'page', width: 4, height: 4, dataUrl: pngToDataUrl(tinyPng()) }],
+        }),
+        { root, max: 3, id: `2026092${i + 1}T100000Z-0000000${i}` },
+      );
+    }
+    const runs = await listRuns(dir);
+    expect(runs.map((r) => r.capturedAt)).toEqual([
+      '2026-09-23T10:00:00.000Z',
+      '2026-09-24T10:00:00.000Z',
+      '2026-09-25T10:00:00.000Z',
+    ]);
+    const files = await readdir(dir);
+    expect(files.filter((f) => f.endsWith('.png')).length).toBe(3);
+  });
+
+  it('keeps everything when the history is shorter than the maximum', async () => {
+    const dir = join(root, historyKey('https://shop.test/checkout'));
+    await saveRun(report(), { root, max: 10 });
+    expect(await pruneHistory(dir, 10)).toEqual([]);
+  });
+
+  it('skips a corrupt record instead of failing the whole read', async () => {
+    const dir = join(root, historyKey('https://shop.test/checkout'));
+    await saveRun(report(), { root, id: '20260921T100000Z-dddddddd' });
+    await writeFile(join(dir, '20260922T100000Z-eeeeeeee.json'), '{ truncated', 'utf8');
+    const runs = await listRuns(dir);
+    expect(runs.map((r) => r.id)).toEqual(['20260921T100000Z-dddddddd']);
+  });
+
+  it('returns an empty history for a URL never reported on', async () => {
+    expect(await listRuns(join(root, 'never-seen-00000000'))).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Trends
+// ---------------------------------------------------------------------------
+
+describe('buildTrend', () => {
+  it('reports no prior runs on a first run without inventing a direction', () => {
+    const trend = buildTrend(report(), []);
+    expect(trend.runs).toBe(0);
+    expect(trend.windowFrom).toBeNull();
+    expect(trend.series.every((s) => s.direction === 'new')).toBe(true);
+    expect(trend.headlines).toEqual([]);
+  });
+
+  it('names the slow decay the story is about', () => {
+    // LCP walks 2000 -> 2400ms across nine prior runs, never once crossing
+    // the 2500ms budget, so no individual run ever failed.
+    const history: HistoryRun[] = [];
+    for (let i = 0; i < 9; i++) {
+      history.push(historyRun(`2026-09-${10 + i}T10:00:00.000Z`, { lcp: 2000 + i * 50 }));
+    }
+    const trend = buildTrend(
+      report({ capturedAt: '2026-09-21T10:00:00.000Z', vitals: { lcp: 2400 } }),
+      history,
+    );
+    const lcp = trend.series.find((s) => s.key === 'lcp');
+    expect(lcp?.deltaFromOldest).toBe(400);
+    expect(lcp?.creep).toBe('LCP has crept up 400ms over 10 runs (2.00s → 2.40s).');
+    expect(trend.headlines[0]).toContain('crept up 400ms');
+  });
+
+  it('does not call rasteriser-scale jitter a regression', () => {
+    const history = [historyRun('2026-09-20T10:00:00.000Z', { lcp: 2000 })];
+    const trend = buildTrend(report({ vitals: { lcp: 2010 } }), history);
+    expect(trend.series.find((s) => s.key === 'lcp')?.direction).toBe('flat');
+  });
+
+  it('calls a real movement a regression, and the reverse an improvement', () => {
+    const history = [historyRun('2026-09-20T10:00:00.000Z', { lcp: 2000 })];
+    expect(
+      buildTrend(report({ vitals: { lcp: 2600 } }), history).series.find((s) => s.key === 'lcp')
+        ?.direction,
+    ).toBe('regressed');
+    expect(
+      buildTrend(report({ vitals: { lcp: 1400 } }), history).series.find((s) => s.key === 'lcp')
+        ?.direction,
+    ).toBe('improved');
+  });
+
+  it('treats a single new console error as a regression', () => {
+    const history = [historyRun('2026-09-20T10:00:00.000Z', { lcp: 2000 })];
+    const current = report({
+      console: [{ type: 'error', text: 'boom', timestamp: 0 }],
+    });
+    const errors = buildTrend(current, history).series.find((s) => s.key === 'consoleErrors');
+    expect(errors).toMatchObject({
+      current: 1,
+      previous: 0,
+      deltaFromPrevious: 1,
+      direction: 'regressed',
+    });
+  });
+
+  it('leads with a first failure after a clean window', () => {
+    const history = [1, 2, 3].map((i) => historyRun(`2026-09-1${i}T10:00:00.000Z`, { lcp: 2000 }));
+    const failing = report({ console: [{ type: 'error', text: 'boom', timestamp: 0 }] });
+    expect(failing.verdict).toBe('fail');
+    expect(buildTrend(failing, history).headlines[0]).toBe(
+      'First failure in this window — the previous 3 run(s) all passed.',
+    );
+  });
+
+  it('includes this run as the last point of every series', () => {
+    const history = [historyRun('2026-09-20T10:00:00.000Z', { lcp: 2000 })];
+    const trend = buildTrend(
+      report({ capturedAt: '2026-09-21T10:00:00.000Z', vitals: { lcp: 2100 } }),
+      history,
+    );
+    const lcp = trend.series.find((s) => s.key === 'lcp');
+    expect(lcp?.points).toEqual([
+      { capturedAt: '2026-09-20T10:00:00.000Z', value: 2000 },
+      { capturedAt: '2026-09-21T10:00:00.000Z', value: 2100 },
+    ]);
+    expect(trend.verdictHistory.at(-1)).toEqual({
+      capturedAt: '2026-09-21T10:00:00.000Z',
+      verdict: 'pass',
+    });
+  });
+
+  it('ignores runs that never measured the metric when picking a baseline', () => {
+    const history = [
+      historyRun('2026-09-18T10:00:00.000Z', { lcp: 2000 }),
+      historyRun('2026-09-19T10:00:00.000Z', {}),
+    ];
+    const lcp = buildTrend(report({ vitals: { lcp: 2600 } }), history).series.find(
+      (s) => s.key === 'lcp',
+    );
+    expect(lcp?.previous).toBe(2000);
+    expect(lcp?.deltaFromPrevious).toBe(600);
+  });
+});
+
+describe('trend formatting', () => {
+  it('switches to seconds past a second so a reader can see the scale', () => {
+    expect(formatTrendValue('ms', 412)).toBe('412ms');
+    expect(formatTrendValue('ms', 2450)).toBe('2.45s');
+    expect(formatTrendValue('score', 0.1234)).toBe('0.123');
+    expect(formatTrendValue('count', 3)).toBe('3');
+    expect(formatTrendValue('ms', null)).toBe('—');
+  });
+
+  it('signs deltas, and says so plainly when there is no change', () => {
+    expect(formatTrendDelta('ms', 400)).toBe('+400ms');
+    expect(formatTrendDelta('ms', -400)).toBe('−400ms');
+    expect(formatTrendDelta('count', 0)).toBe('no change');
+    expect(formatTrendDelta('count', null)).toBe('no change');
+  });
+});

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

@@ -0,0 +1,210 @@
+/**
+ * Everything around the two files the command leaves behind: where they go,
+ * what the JSON carries, plus the two pure helpers from the collectors
+ * (request classification and locator upgrading) that a stub client can
+ * exercise without launching Chrome.
+ */
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it, vi } from 'vitest';
+import type { CdpClient } from '../browser/cdp.js';
+import { buildReport } from '../report/analyze.js';
+import { DEFAULT_BUDGET } from '../report/budget.js';
+import { toRequestEntries } from '../report/collect.js';
+import { upgradeLocators } from '../report/collect-a11y.js';
+import { resolveOutPath, toJsonReport, writeReportFiles } from '../report/index.js';
+import type { A11yFinding, AxNode, CaptureData, Report } from '../report/types.js';
+
+function capture(partial: Partial<CaptureData> = {}): CaptureData {
+  return {
+    url: 'https://shop.test/checkout',
+    finalUrl: 'https://shop.test/checkout',
+    title: 'Checkout',
+    capturedAt: '2026-09-21T10:00:00.000Z',
+    durationMs: 3200,
+    console: [],
+    pageErrors: [],
+    requests: [],
+    vitals: { lcp: 100, cls: 0, inp: 10 },
+    a11y: [],
+    screenshots: [],
+    notes: [],
+    ...partial,
+  };
+}
+
+const report = (partial: Partial<CaptureData> = {}): Report =>
+  buildReport(capture(partial), DEFAULT_BUDGET);
+
+describe('resolveOutPath', () => {
+  const when = '2026-09-21T10:00:00.000Z';
+
+  it('derives a dated, host-and-path filename when --out is omitted', async () => {
+    const path = await resolveOutPath(undefined, 'https://shop.test/checkout', when, '/work');
+    expect(path).toBe('/work/monobrowse-report-shop.test-checkout-20260921T100000Z.html');
+  });
+
+  it('uses an explicit .html path as given', async () => {
+    expect(await resolveOutPath('/tmp/out.html', 'https://a.test/', when, '/work')).toBe(
+      '/tmp/out.html',
+    );
+  });
+
+  it('resolves a relative path against the working directory', async () => {
+    expect(await resolveOutPath('reports/run.html', 'https://a.test/', when, '/work')).toBe(
+      '/work/reports/run.html',
+    );
+  });
+
+  it('adds .html to a path that has no extension and is not a directory', async () => {
+    expect(await resolveOutPath('/tmp/run', 'https://a.test/', when, '/work')).toBe(
+      '/tmp/run.html',
+    );
+  });
+
+  it('treats a trailing-separator path as a directory to drop the report into', async () => {
+    const path = await resolveOutPath('reports/', 'https://a.test/', when, '/work');
+    expect(path).toBe('/work/reports/monobrowse-report-a.test-20260921T100000Z.html');
+  });
+
+  it('treats an existing directory as a directory', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'monobrowse-out-'));
+    const path = await resolveOutPath(dir, 'https://a.test/', when, '/work');
+    expect(path).toBe(join(dir, 'monobrowse-report-a.test-20260921T100000Z.html'));
+  });
+});
+
+describe('writeReportFiles', () => {
+  it('writes the HTML and a sibling JSON carrying the verdict and failures', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'monobrowse-write-'));
+    const r = report({ pageErrors: [{ text: 'boom', timestamp: 0 }] });
+    const paths = await writeReportFiles(r, join(dir, 'run.html'));
+
+    expect(paths.jsonPath).toBe(join(dir, 'run.json'));
+    const html = await readFile(paths.htmlPath, 'utf8');
+    expect(html).toContain('<!doctype html>');
+
+    const json = JSON.parse(await readFile(paths.jsonPath, 'utf8'));
+    expect(json.verdict).toBe('fail');
+    expect(json.failures[0]).toMatchObject({ budget: 'maxPageErrors', actual: '1' });
+  });
+
+  it('creates the output directory if it does not exist yet', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'monobrowse-write-'));
+    const paths = await writeReportFiles(report(), join(dir, 'nested', 'deep', 'run.html'));
+    await expect(readFile(paths.htmlPath, 'utf8')).resolves.toContain('PASS');
+  });
+});
+
+describe('toJsonReport', () => {
+  it('drops base64 image payloads but keeps the screenshot metadata', () => {
+    const json = toJsonReport(
+      report({
+        screenshots: [
+          {
+            label: 'page',
+            width: 1280,
+            height: 900,
+            dataUrl: 'data:image/png;base64,AAAA',
+            path: '/tmp/page.png',
+          },
+        ],
+      }),
+    );
+    const shots = json.screenshots as Array<Record<string, unknown>>;
+    expect(shots[0]).toEqual({ label: 'page', width: 1280, height: 900, path: '/tmp/page.png' });
+    expect(JSON.stringify(json)).not.toContain('base64');
+  });
+});
+
+describe('toRequestEntries', () => {
+  const base = { id: '1', url: 'https://a.test/x', method: 'GET', startTime: 100 };
+
+  it('marks a 4xx/5xx response as failed', () => {
+    const [entry] = toRequestEntries([{ ...base, status: 503, endTime: 400 }], new Map());
+    expect(entry.failed).toBe(true);
+    expect(entry.durationMs).toBe(300);
+  });
+
+  it('leaves a 3xx and a 2xx alone', () => {
+    const entries = toRequestEntries(
+      [
+        { ...base, status: 200 },
+        { ...base, id: '2', status: 302 },
+      ],
+      new Map(),
+    );
+    expect(entries.map((e) => e.failed)).toEqual([false, false]);
+  });
+
+  it('marks a transport failure as failed and carries its errorText', () => {
+    const failures = new Map([['1', { errorText: 'net::ERR_CONNECTION_REFUSED' }]]);
+    const [entry] = toRequestEntries([base], failures);
+    expect(entry).toMatchObject({ failed: true, errorText: 'net::ERR_CONNECTION_REFUSED' });
+  });
+
+  it('does not count a request the page itself cancelled', () => {
+    const failures = new Map([['1', { errorText: 'net::ERR_ABORTED', canceled: true }]]);
+    expect(toRequestEntries([base], failures)[0].failed).toBe(false);
+  });
+
+  it('still counts a blocked request even though CDP also marks it cancelled', () => {
+    const failures = new Map([['1', { canceled: true, blockedReason: 'csp' }]]);
+    const [entry] = toRequestEntries([base], failures);
+    expect(entry).toMatchObject({ failed: true, errorText: 'blocked: csp' });
+  });
+
+  it('does not treat a still-in-flight request as a failure', () => {
+    expect(toRequestEntries([base], new Map())[0].failed).toBe(false);
+  });
+});
+
+describe('upgradeLocators', () => {
+  const finding = (locator: string): A11yFinding => ({
+    rule: 'unlabelled-control',
+    impact: 'error',
+    role: 'button',
+    name: null,
+    locator,
+    detail: 'no name',
+  });
+
+  function stubClient(selector: string | null) {
+    return {
+      send: vi.fn(async (method: string) => {
+        if (method === 'DOM.resolveNode') return { object: { objectId: 'obj-1' } };
+        if (method === 'Runtime.callFunctionOn') return { result: { value: selector } };
+        return {};
+      }),
+    } as unknown as CdpClient;
+  }
+
+  const nodes: AxNode[] = [{ nodeId: '7', backendDOMNodeId: 42 }];
+
+  it('replaces the ax-node placeholder with a resolved CSS selector', async () => {
+    const out = await upgradeLocators(stubClient('#submit'), 'sid', [finding('ax-node:7')], nodes);
+    expect(out[0].locator).toBe('#submit');
+  });
+
+  it('keeps the placeholder when the DOM cannot resolve the node', async () => {
+    const out = await upgradeLocators(stubClient(null), 'sid', [finding('ax-node:7')], nodes);
+    expect(out[0].locator).toBe('ax-node:7');
+  });
+
+  it('leaves DOM-derived locators untouched and costs no round-trip', async () => {
+    const client = stubClient('#other');
+    const out = await upgradeLocators(client, 'sid', [finding('#already-known')], nodes);
+    expect(out[0].locator).toBe('#already-known');
+    expect(client.send).not.toHaveBeenCalled();
+  });
+
+  it('resolves each backend node once, however many findings point at it', async () => {
+    const client = stubClient('#submit');
+    await upgradeLocators(client, 'sid', [finding('ax-node:7'), finding('ax-node:7')], nodes);
+    const resolves = (client.send as ReturnType<typeof vi.fn>).mock.calls.filter(
+      (c) => c[0] === 'DOM.resolveNode',
+    );
+    expect(resolves).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,95 @@
+/**
+ * The PNG codec underpins the pixel diff, so it is tested against images it
+ * did not produce as well as its own round trip — an encoder and decoder that
+ * are wrong in the same direction would agree with each other perfectly.
+ *
+ * `assets/mascot.png` and `assets/logo.png` are ordinary 8-bit RGBA PNGs
+ * checked into this repo by other tooling; decoding them exercises the real
+ * filter mix (Sub/Up/Average/Paeth) that a synthetic image never produces.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { crc32, decodePng, encodePng, pngFromDataUrl, pngToDataUrl } from '../report/png.js';
+
+const ASSETS = join(import.meta.dirname, '..', '..', '..', '..', '..', 'assets');
+
+function solid(width: number, height: number, rgba: [number, number, number, number]) {
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) data.set(rgba, i * 4);
+  return { width, height, data };
+}
+
+describe('crc32', () => {
+  it('matches the known CRC-32 of "123456789"', () => {
+    expect(crc32(new TextEncoder().encode('123456789'))).toBe(0xcbf43926);
+  });
+});
+
+describe('decodePng', () => {
+  it('decodes a real 8-bit RGBA PNG at its stated dimensions', () => {
+    const img = decodePng(readFileSync(join(ASSETS, 'mascot.png')));
+    expect({ width: img.width, height: img.height }).toEqual({ width: 650, height: 618 });
+    expect(img.data.length).toBe(650 * 618 * 4);
+  });
+
+  it('decodes a second real PNG, exercising a different filter mix', () => {
+    const img = decodePng(readFileSync(join(ASSETS, 'logo.png')));
+    expect(img.data.length).toBe(img.width * img.height * 4);
+    // A logo is not uniform: if unfiltering were broken every row would be
+    // identical or the image would be a single flat colour.
+    const unique = new Set<string>();
+    for (let i = 0; i < img.data.length; i += 4) {
+      unique.add(`${img.data[i]},${img.data[i + 1]},${img.data[i + 2]},${img.data[i + 3]}`);
+      if (unique.size > 5) break;
+    }
+    expect(unique.size).toBeGreaterThan(5);
+  });
+
+  it('rejects a file that is not a PNG', () => {
+    expect(() => decodePng(new TextEncoder().encode('GIF89a not a png'))).toThrow(/bad signature/);
+  });
+
+  it('rejects an interlaced PNG by name rather than decoding it wrongly', () => {
+    const png = encodePng(solid(2, 2, [1, 2, 3, 4]));
+    png[8 + 8 + 12] = 1; // IHDR interlace byte
+    expect(() => decodePng(png)).toThrow(/interlaced/);
+  });
+});
+
+describe('encodePng', () => {
+  it('round-trips an image byte-for-byte', () => {
+    const img = decodePng(readFileSync(join(ASSETS, 'mascot.png')));
+    const again = decodePng(encodePng(img));
+    expect(again.width).toBe(img.width);
+    expect(again.height).toBe(img.height);
+    expect(Buffer.from(again.data).equals(Buffer.from(img.data))).toBe(true);
+  });
+
+  it('writes the PNG signature and an IEND chunk', () => {
+    const png = encodePng(solid(3, 2, [10, 20, 30, 255]));
+    expect([...png.subarray(0, 8)]).toEqual([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    expect(png.subarray(png.length - 8, png.length - 4).toString('ascii')).toBe('IEND');
+  });
+
+  it('refuses a pixel buffer whose length disagrees with the dimensions', () => {
+    expect(() => encodePng({ width: 4, height: 4, data: new Uint8Array(8) })).toThrow(
+      /expected 64 bytes/,
+    );
+  });
+});
+
+describe('data URLs', () => {
+  it('round-trips through a data: URL', () => {
+    const png = encodePng(solid(2, 2, [7, 8, 9, 255]));
+    const url = pngToDataUrl(png);
+    expect(url.startsWith('data:image/png;base64,')).toBe(true);
+    expect(Buffer.from(pngFromDataUrl(url)).equals(png)).toBe(true);
+  });
+
+  it('accepts a bare base64 payload, which is what CDP actually returns', () => {
+    const png = encodePng(solid(1, 1, [1, 1, 1, 255]));
+    const bare = Buffer.from(png).toString('base64');
+    expect(Buffer.from(pngFromDataUrl(bare)).equals(png)).toBe(true);
+  });
+});