@monoes/monobrowse 1.0.11 → 1.0.13

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 });
+  });
+});

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

@@ -0,0 +1,202 @@
+/**
+ * Budget evaluation decides the exit code, so these cover the boundaries
+ * (at the limit passes, one over fails) and the cases where a metric simply
+ * was not measured — which must not silently grade as a pass.
+ */
+import { describe, expect, it } from 'vitest';
+import {
+  buildReport,
+  evaluateBudget,
+  failedRequests,
+  summarizeVerdict,
+} from '../report/analyze.js';
+import { DEFAULT_BUDGET, parseBudget } from '../report/budget.js';
+import type { A11yFinding, CaptureData, ConsoleEntry, RequestEntry } from '../report/types.js';
+
+function capture(partial: Partial<CaptureData> = {}): CaptureData {
+  return {
+    url: 'https://example.test/',
+    finalUrl: 'https://example.test/',
+    title: 'Example',
+    capturedAt: '2026-09-21T10:00:00.000Z',
+    durationMs: 1234,
+    console: [],
+    pageErrors: [],
+    requests: [],
+    vitals: {},
+    a11y: [],
+    screenshots: [],
+    notes: [],
+    ...partial,
+  };
+}
+
+const consoleEntry = (type: string, text: string): ConsoleEntry => ({
+  type,
+  text,
+  timestamp: 0,
+});
+
+const request = (partial: Partial<RequestEntry> = {}): RequestEntry => ({
+  url: 'https://example.test/api',
+  method: 'GET',
+  failed: false,
+  ...partial,
+});
+
+const a11yError = (rule: A11yFinding['rule']): A11yFinding => ({
+  rule,
+  impact: 'error',
+  role: 'button',
+  name: null,
+  locator: '#x',
+  detail: 'no name',
+});
+
+describe('evaluateBudget', () => {
+  it('passes a clean page against the defaults', () => {
+    const result = evaluateBudget(
+      capture({ vitals: { lcp: 900, cls: 0.02, inp: 80 } }),
+      DEFAULT_BUDGET,
+    );
+    expect(result.verdict).toBe('pass');
+    expect(result.failures).toEqual([]);
+    expect(result.unmeasured).toEqual([]);
+  });
+
+  it('fails on a console error and names expected vs actual', () => {
+    const result = evaluateBudget(
+      capture({ console: [consoleEntry('error', 'Uncaught TypeError: x is not a function')] }),
+      parseBudget({ lcp: null, cls: null, inp: null }),
+    );
+    expect(result.verdict).toBe('fail');
+    expect(result.failures).toHaveLength(1);
+    expect(result.failures[0]).toMatchObject({
+      budget: 'maxConsoleErrors',
+      expected: '<= 0',
+      actual: '1',
+    });
+    expect(result.failures[0].detail).toContain('Uncaught TypeError');
+  });
+
+  it('does not count console warnings as errors', () => {
+    const result = evaluateBudget(
+      capture({ console: [consoleEntry('warn', 'deprecated')] }),
+      parseBudget({ lcp: null, cls: null, inp: null }),
+    );
+    expect(result.verdict).toBe('pass');
+  });
+
+  it('fails on failed requests and quotes the first few', () => {
+    const requests = [
+      request({ failed: true, status: 500, url: 'https://example.test/a' }),
+      request({ failed: true, errorText: 'net::ERR_NAME_NOT_RESOLVED', url: 'https://x.test/b' }),
+      request({ status: 200 }),
+    ];
+    const result = evaluateBudget(capture({ requests }), DEFAULT_BUDGET);
+    const failure = result.failures.find((f) => f.budget === 'maxFailedRequests');
+    expect(failure).toBeDefined();
+    expect(failure?.actual).toBe('2');
+    expect(failure?.detail).toContain('500 GET https://example.test/a');
+    expect(failure?.detail).toContain('net::ERR_NAME_NOT_RESOLVED');
+  });
+
+  it('treats a metric exactly at the limit as passing, and one over as failing', () => {
+    const budget = parseBudget({ lcp: 2500, cls: null, inp: null });
+    expect(evaluateBudget(capture({ vitals: { lcp: 2500 } }), budget).verdict).toBe('pass');
+    const over = evaluateBudget(capture({ vitals: { lcp: 2501 } }), budget);
+    expect(over.verdict).toBe('fail');
+    expect(over.failures[0]).toMatchObject({
+      budget: 'lcpMs',
+      expected: '<= 2500ms',
+      actual: '2501ms',
+    });
+  });
+
+  it('records an unmeasured metric instead of passing it', () => {
+    const result = evaluateBudget(
+      capture({ vitals: {} }),
+      parseBudget({ lcp: 2500, cls: null, inp: null }),
+    );
+    expect(result.verdict).toBe('pass');
+    expect(result.unmeasured).toEqual(['LCP (Largest Contentful Paint)']);
+  });
+
+  it('skips a budget set to null entirely', () => {
+    const result = evaluateBudget(
+      capture({ vitals: { lcp: 99_000 } }),
+      parseBudget({ lcp: null, cls: null, inp: null }),
+    );
+    expect(result.verdict).toBe('pass');
+    expect(result.unmeasured).toEqual([]);
+  });
+
+  it('counts a11y errors but not a11y warnings against the a11y budget', () => {
+    const a11y: A11yFinding[] = [
+      a11yError('unlabelled-control'),
+      { ...a11yError('heading-order-jump'), impact: 'warning' },
+    ];
+    const result = evaluateBudget(capture({ a11y }), DEFAULT_BUDGET);
+    const failure = result.failures.find((f) => f.budget === 'maxA11yErrors');
+    expect(failure?.actual).toBe('1');
+    expect(failure?.detail).toContain('unlabelled-control at #x');
+  });
+
+  it('reports a CLS breach as a score, not milliseconds', () => {
+    const result = evaluateBudget(
+      capture({ vitals: { cls: 0.42 } }),
+      parseBudget({ lcp: null, inp: null }),
+    );
+    expect(result.failures[0]).toMatchObject({
+      budget: 'clsScore',
+      expected: '<= 0.1',
+      actual: '0.42',
+    });
+  });
+});
+
+describe('failedRequests', () => {
+  it('selects only entries marked failed', () => {
+    expect(failedRequests([request({ failed: true }), request()])).toHaveLength(1);
+  });
+});
+
+describe('buildReport', () => {
+  it('carries the verdict, the failure list and the headline counts', () => {
+    const report = buildReport(
+      capture({
+        console: [consoleEntry('error', 'boom'), consoleEntry('warn', 'meh')],
+        requests: [request({ failed: true, status: 404 }), request({ status: 200 })],
+        a11y: [a11yError('image-missing-alt')],
+        vitals: { lcp: 1000, cls: 0, inp: 10 },
+      }),
+      DEFAULT_BUDGET,
+    );
+    expect(report.verdict).toBe('fail');
+    expect(report.counts).toEqual({
+      consoleErrors: 1,
+      consoleWarnings: 1,
+      pageErrors: 0,
+      requests: 2,
+      failedRequests: 1,
+      a11yErrors: 1,
+      a11yWarnings: 0,
+    });
+    expect(report.failures.map((f) => f.budget).sort()).toEqual([
+      'maxA11yErrors',
+      'maxConsoleErrors',
+      'maxFailedRequests',
+    ]);
+  });
+
+  it('summarizes a pass and a fail in one line each', () => {
+    const pass = buildReport(capture({ vitals: { lcp: 10, cls: 0, inp: 1 } }), DEFAULT_BUDGET);
+    expect(summarizeVerdict(pass)).toContain('PASS');
+    const fail = buildReport(
+      capture({ pageErrors: [{ text: 'boom', timestamp: 0 }] }),
+      DEFAULT_BUDGET,
+    );
+    expect(summarizeVerdict(fail)).toContain('FAIL');
+    expect(summarizeVerdict(fail)).toContain('Uncaught page errors');
+  });
+});

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

@@ -0,0 +1,92 @@
+/**
+ * Budgets are the CI gate, so the parser's job is to be strict: a typo'd key
+ * must fail loudly rather than quietly disabling a check.
+ */
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_BUDGET, formatThreshold, loadBudget, parseBudget } from '../report/budget.js';
+
+describe('DEFAULT_BUDGET', () => {
+  it('gates on zero errors and the Core Web Vitals "good" boundaries', () => {
+    expect(DEFAULT_BUDGET).toMatchObject({
+      maxConsoleErrors: 0,
+      maxPageErrors: 0,
+      maxFailedRequests: 0,
+      maxA11yErrors: 0,
+      lcpMs: 2500,
+      clsScore: 0.1,
+      inpMs: 200,
+    });
+  });
+});
+
+describe('parseBudget', () => {
+  it('merges over the defaults rather than replacing them', () => {
+    const budget = parseBudget({ lcpMs: 4000 });
+    expect(budget.lcpMs).toBe(4000);
+    expect(budget.maxConsoleErrors).toBe(0);
+  });
+
+  it('accepts short and snake_case spellings', () => {
+    const budget = parseBudget({ lcp: 3000, cls: 0.25, max_console_errors: 5, 'a11y-errors': 2 });
+    expect(budget).toMatchObject({
+      lcpMs: 3000,
+      clsScore: 0.25,
+      maxConsoleErrors: 5,
+      maxA11yErrors: 2,
+    });
+  });
+
+  it('treats null as "do not enforce"', () => {
+    expect(parseBudget({ lcp: null }).lcpMs).toBeNull();
+  });
+
+  it('rejects an unknown key instead of silently ignoring it', () => {
+    expect(() => parseBudget({ maxConsoleError: 0 })).toThrow(/Unknown budget key/);
+  });
+
+  it('rejects non-numeric and negative values', () => {
+    expect(() => parseBudget({ lcp: 'fast' })).toThrow(/must be a number/);
+    expect(() => parseBudget({ lcp: -1 })).toThrow(/negative/);
+  });
+
+  it('rejects a non-object budget', () => {
+    expect(() => parseBudget([1, 2])).toThrow(/expected a JSON object/);
+    expect(() => parseBudget(null)).toThrow(/expected a JSON object/);
+  });
+});
+
+describe('loadBudget', () => {
+  it('returns the defaults when nothing is passed', async () => {
+    await expect(loadBudget()).resolves.toEqual(DEFAULT_BUDGET);
+  });
+
+  it('parses inline JSON', async () => {
+    await expect(loadBudget('{"lcp": 1000}')).resolves.toMatchObject({ lcpMs: 1000 });
+  });
+
+  it('reads a budget file', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'monobrowse-budget-'));
+    const file = join(dir, 'budget.json');
+    await writeFile(file, JSON.stringify({ maxFailedRequests: 3 }), 'utf8');
+    await expect(loadBudget(file)).resolves.toMatchObject({ maxFailedRequests: 3 });
+  });
+
+  it('names the file it could not read', async () => {
+    await expect(loadBudget('/nope/does-not-exist.json')).rejects.toThrow(/Budget file not found/);
+  });
+
+  it('reports malformed inline JSON as such', async () => {
+    await expect(loadBudget('{oops}')).rejects.toThrow(/not valid JSON/);
+  });
+});
+
+describe('formatThreshold', () => {
+  it('units millisecond budgets and leaves counts and scores bare', () => {
+    expect(formatThreshold('lcpMs', 2500)).toBe('<= 2500ms');
+    expect(formatThreshold('clsScore', 0.1)).toBe('<= 0.1');
+    expect(formatThreshold('maxConsoleErrors', 0)).toBe('<= 0');
+  });
+});