testaro 78.0.6 → 78.4.0

package/procs/doTestAct.js

@@ -1,5 +1,6 @@
 /*
   © 2024–2025 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2026 Jeff Witt.
   © 2025–2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or
@@ -9,9 +10,10 @@
 */
 
 /*
-  doActs
-  Performs the tests of an act.
-  This file is designed to be run as a child process.
+  doTestAct
+  Performs the tests of an act, under process isolation.
+  This file is designed to be run as a child process: it reads the temporary report, performs
+  the act with procs/testAct.js, writes the revised report, and messages the parent.
 */
 
 // ERROR LOGGING
@@ -32,31 +34,8 @@ process.on('unhandledRejection', reason => {
 
 // Module to perform file operations.
 const fs = require('fs/promises');
-// Module to close and launch browsers.
-const {browserClose, launch} = require('./launch');
-
-// CONSTANTS
-
-/*
-  Tool XPath requirements.
-    none: Needs no script or extra load time.
-    own: Needs extra load time for its own XPath computations.
-    script: Needs the window.getXPath script.
-    attribute: Needs data-xpath attributes made with window.getXPath.
-*/
-const xPathNeeds = {
-  alfa: 'own',
-  aslint: 'own',
-  axe: 'attribute',
-  ed11y: 'script',
-  htmlcs: 'attribute',
-  ibm: 'attribute',
-  nuVal: 'attribute',
-  nuVnu: 'attribute',
-  qualWeb: 'attribute',
-  wave: 'script'
-};
-const accessibleNameNeeders = ['testaro'];
+// Function to perform a test act.
+const {performTestAct} = require('./testAct');
 
 // FUNCTIONS
 
@@ -78,105 +57,32 @@ const doTestAct = async (reportPath, actIndex) => {
   // Get the temporary report.
   const reportJSON = await fs.readFile(reportPath, 'utf8');
   const report = JSON.parse(reportJSON);
-  // Get a reference to the act in the report.
   const act = report.acts[actIndex];
-  // Get the tool name.
-  const {which} = act;
-  let page;
-  // If the tool is not Testaro:
-  if (which !== 'testaro') {
-    const browserID = act.launch && act.launch.browserID || report.browserID;
-    const targetURL = act.launch && act.launch.target && act.launch.target.url || report.target.url;
-    // Launch a browser, navigate to the URL, and update the run-module page export.
-    page = await launch({
-      report,
-      actIndex,
-      tempBrowserID: browserID,
-      tempURL: targetURL,
-      xPathNeed: xPathNeeds[which] ?? 'none',
-      needsAccessibleName: accessibleNameNeeders.includes(which)
-    });
-    // If the launch aborted the job:
+  let status = 'ok';
+  let error = '';
+  try {
+    // Perform the act, revising the report.
+    await performTestAct({report, actIndex});
+    // If the launch aborted the job or no page existed, report that.
     if (report.jobData?.aborted) {
-      // Close the browser and its context, if they exist.
-      await browserClose(page);
-      const reportJSON = JSON.stringify(report);
-      // Save the revised report.
-      await fs.writeFile(reportPath, reportJSON);
-      // Report this.
-      sendMessage({
-        status: 'error',
-        error: 'Page launch aborted'
-      });
-      process.exit(1);
+      status = 'error';
+      error = 'Page launch aborted';
     }
-  }
-  // If the page exists after the launch, or if the tool is Testaro:
-  if (page || which === 'testaro') {
-    try {
-      // Make the act reporter perform the specified tests of the tool.
-      const actReport = await require(`../tests/${which}`).reporter(page, report, actIndex, 65);
-      // Add the data and result to the act.
-      act.data = actReport.data;
-      act.result = actReport.result;
-      // If the tool reported that the page prevented testing:
-      if (act.data && act.data.prevented) {
-        const {standardResult} = act.result;
-        // Add this to any standard result.
-        if (standardResult) {
-          standardResult.prevented = true;
-        }
-        // Add prevention data to the job data.
-        report.jobData.preventions[which] = act.data.error;
-      }
-      // Close the browser and its context, if they exist.
-      await browserClose(page);
-      const reportJSON = JSON.stringify(report);
-      // Save the revised report.
-      await fs.writeFile(reportPath, reportJSON);
-      // Send a completion message.
-      sendMessage({
-        status: 'ok',
-      });
-      process.exit(0);
+    else if (act.data?.prevented && act.data.error === 'No page') {
+      status = 'error';
+      error = 'ERROR: No page';
     }
-    // If the tool invocation failed:
-    catch(error) {
-      // Close the browser and its context, if they exist.
-      await browserClose(page);
-      // Save the revised report.
-      const reportJSON = JSON.stringify(report);
-      await fs.writeFile(reportPath, reportJSON);
-      // Report the failure.
-      const message = error.message.slice(0, 400);
-      console.log(`ERROR: Test act ${act.which} failed (${message})`);
-      sendMessage({
-        status: 'error',
-        error: 'ERROR performing the act'
-      });
-      process.exit(1);
-    };
   }
-  // Otherwise, i.e. if the page does not exist after the launch:
-  else {
-    // Add this to the act.
-    act.data ??= {};
-    act.data.prevented = true;
-    act.data.error = 'No page';
-    // Add the prevention to the job data.
-    report.jobData.preventions[which] = act.data.error;
-    const reportJSON = JSON.stringify(report);
-    // Save the revised report.
-    await fs.writeFile(reportPath, reportJSON);
-    // Report this.
-    const message = 'ERROR: No page';
-    console.log(message);
-    sendMessage({
-      status: 'error',
-      error: message
-    });
-    process.exit(1);
+  // If the tool invocation failed:
+  catch(err) {
+    console.log(`ERROR: Test act ${act.which} failed (${err.message.slice(0, 400)})`);
+    status = 'error';
+    error = 'ERROR performing the act';
   }
+  // Save the revised report and report the outcome to the parent.
+  await fs.writeFile(reportPath, JSON.stringify(report));
+  sendMessage(status === 'ok' ? {status} : {status, error});
+  process.exit(status === 'ok' ? 0 : 1);
 };
 process.on('uncaughtException', error => {
   console.log(`ERROR: uncaughtException (${error.message})`);

package/procs/flow.js

@@ -0,0 +1,221 @@
+/*
+  © 2026 Jeff Witt.
+
+  Licensed under the MIT License. See LICENSE file at the project root or
+  https://opensource.org/license/mit/ for details.
+
+  SPDX-License-Identifier: MIT
+*/
+
+/*
+  flow.js
+  Builds report.flow: the running list of issues across a job's checkpoints. For each pair of
+  consecutive checkpoints it records which issues were added, persisted, and removed by the
+  acts between them, together with a structure diff of the two catalogs and a line diff of
+  the two ARIA snapshots. See docs/checkpoint-scanning.md (Phase 2). Runs on the unpruned
+  catalog at job end, and can run on a stored report whose catalog was pruned (the structure
+  diff then covers cited elements only).
+*/
+
+// IMPORTS
+
+const {diffLines} = require('diff');
+const {getStructureDiff} = require('./scope');
+
+// CONSTANTS
+
+// The most changed lines an ARIA snapshot diff records.
+const maxAriaChanges = 500;
+
+// FUNCTIONS
+
+/*
+  Returns the identity of a standard instance for comparison across checkpoints:
+  tool, rule, element XPath, and start tag. The catalog index differs per checkpoint for the
+  same element, so the XPath stands for the element; the start tag distinguishes a replaced
+  element at the same path. Box and text are excluded because layout and copy shift without
+  the defect changing. A summary instance (no element) has an empty element key.
+*/
+const getIdentity = (tool, instance, catalog) => {
+  const entry = instance.catalogIndex !== undefined && instance.catalogIndex !== ''
+    ? catalog[String(instance.catalogIndex)]
+    : null;
+  const pathID = entry ? entry.pathID ?? '' : instance.pathID ?? '';
+  const startTag = entry ? entry.startTag ?? '' : '';
+  return {
+    tool,
+    ruleID: instance.ruleID,
+    pathID,
+    startTag,
+    key: [tool, instance.ruleID, pathID, startTag].join('|')
+  };
+};
+// Returns whether an XPath is one of, or inside one of, the given root XPaths.
+const isWithin = (pathID, roots) => roots.some(
+  root => pathID === root || pathID.startsWith(`${root}/`)
+);
+/*
+  Returns the issues found at a checkpoint, keyed by identity; the tools that observed it;
+  and, for each tool whose every act at the checkpoint was scoped to changed subtrees, the
+  XPaths of those subtrees (scopedRoots), since such a tool observed nothing outside them.
+*/
+const getCheckpointIssues = (report, checkpointIndex) => {
+  const catalog = report.catalog ?? {};
+  const issues = {};
+  const tools = new Set();
+  const unscopedTools = new Set();
+  const scopedRoots = {};
+  report.acts.forEach((act, actIndex) => {
+    if (act.type !== 'test' || act.checkpoint !== checkpointIndex) {
+      return;
+    }
+    // A prevented act observed nothing.
+    if (act.data && act.data.prevented) {
+      return;
+    }
+    const standardResult = act.result && act.result.standardResult;
+    if (! standardResult || standardResult.prevented) {
+      return;
+    }
+    tools.add(act.which);
+    const scope = act.data && act.data.scope;
+    if (scope && scope.applied) {
+      scopedRoots[act.which] = [... (scopedRoots[act.which] ?? []), ... (scope.pathIDs ?? [])];
+    }
+    else {
+      unscopedTools.add(act.which);
+    }
+    (standardResult.instances ?? []).forEach(instance => {
+      const identity = getIdentity(act.which, instance, catalog);
+      const issue = issues[identity.key] ??= {
+        tool: identity.tool,
+        ruleID: identity.ruleID,
+        pathID: identity.pathID,
+        startTag: identity.startTag,
+        what: instance.what,
+        ordinalSeverity: instance.ordinalSeverity,
+        outcome: instance.outcome,
+        count: 0,
+        actIndexes: []
+      };
+      issue.count += instance.count || 1;
+      if (! issue.actIndexes.includes(actIndex)) {
+        issue.actIndexes.push(actIndex);
+      }
+    });
+  });
+  unscopedTools.forEach(tool => {
+    delete scopedRoots[tool];
+  });
+  return {issues, tools, scopedRoots};
+};
+// Returns a string ending with a newline, so the last line of a snapshot compares as a line.
+const withFinalNewline = text => text && ! text.endsWith('\n') ? `${text}\n` : text;
+// Returns a line diff of two ARIA snapshots: counts and the changed lines.
+const getAriaDiff = (before, after) => {
+  const changes = [];
+  let addedLineCount = 0;
+  let removedLineCount = 0;
+  let truncated = false;
+  let line = 0;
+  diffLines(withFinalNewline(before ?? ''), withFinalNewline(after ?? '')).forEach(part => {
+    const lines = part.value.replace(/\n$/, '').split('\n');
+    if (part.added) {
+      addedLineCount += lines.length;
+    }
+    else if (part.removed) {
+      removedLineCount += lines.length;
+    }
+    if (part.added || part.removed) {
+      lines.forEach(text => {
+        if (changes.length < maxAriaChanges) {
+          changes.push({type: part.added ? 'added' : 'removed', line, text});
+        }
+        else {
+          truncated = true;
+        }
+        if (part.added) {
+          line++;
+        }
+      });
+    }
+    else {
+      line += lines.length;
+    }
+  });
+  return {addedLineCount, removedLineCount, truncated, changes};
+};
+/*
+  Builds and returns the flow of a report, or null if the report has fewer than two
+  checkpoints. For each pair of consecutive checkpoints, the issues of the tools that observed
+  both are compared: added (only at the later), persisted (at both), removed (only at the
+  earlier). Tools that observed only one of the two are listed as notObserved, since their
+  issues cannot be compared. An earlier issue that a tool did not re-test at the later
+  checkpoint, because its acts there were all scoped to changed subtrees and the issue's
+  element lies outside them, is listed as notRetested rather than removed.
+*/
+exports.getFlow = report => {
+  const checkpoints = report.checkpoints ?? [];
+  if (checkpoints.length < 2) {
+    return null;
+  }
+  const observations = checkpoints.map(checkpoint => getCheckpointIssues(report, checkpoint.index));
+  const summaries = checkpoints.map((checkpoint, index) => {
+    const {issues, tools} = observations[index];
+    return {
+      index: checkpoint.index,
+      name: checkpoint.name,
+      kind: checkpoint.kind,
+      url: checkpoint.url,
+      actIndex: checkpoint.actIndex,
+      testActs: checkpoint.testActs,
+      tools: Array.from(tools).sort(),
+      issueCount: Object.keys(issues).length
+    };
+  });
+  const deltas = [];
+  for (let index = 1; index < checkpoints.length; index++) {
+    const before = observations[index - 1];
+    const after = observations[index];
+    const tools = Array.from(before.tools).filter(tool => after.tools.has(tool)).sort();
+    const notObserved = Array.from(new Set([... before.tools, ... after.tools]))
+    .filter(tool => ! tools.includes(tool))
+    .sort();
+    const comparable = issue => tools.includes(issue.tool);
+    const added = [];
+    const persisted = [];
+    const removed = [];
+    const notRetested = [];
+    Object.keys(after.issues).forEach(key => {
+      const issue = after.issues[key];
+      if (comparable(issue)) {
+        (before.issues[key] ? persisted : added).push(issue);
+      }
+    });
+    Object.keys(before.issues).forEach(key => {
+      const issue = before.issues[key];
+      if (comparable(issue) && ! after.issues[key]) {
+        const roots = after.scopedRoots[issue.tool];
+        const retested = ! roots || (issue.pathID && isWithin(issue.pathID, roots));
+        (retested ? removed : notRetested).push(issue);
+      }
+    });
+    // The structure diff recorded when the checkpoint was made, else one computed now (on a
+    // stored report, over the cited entries only).
+    const structure = checkpoints[index].structure
+      ?? getStructureDiff(report, checkpoints[index - 1].index, checkpoints[index].index);
+    deltas.push({
+      from: checkpoints[index - 1].index,
+      to: checkpoints[index].index,
+      tools,
+      notObserved,
+      added,
+      persisted,
+      removed,
+      notRetested,
+      structure,
+      aria: getAriaDiff(checkpoints[index - 1].ariaSnapshot, checkpoints[index].ariaSnapshot)
+    });
+  }
+  return {checkpoints: summaries, deltas};
+};

package/procs/generateRuleRegistry.js

@@ -0,0 +1,94 @@
+/*
+  © 2026 Jeff Witt.
+
+  Licensed under the MIT License. See LICENSE file at the project root or
+  https://opensource.org/license/mit/ for details.
+
+  SPDX-License-Identifier: MIT
+*/
+
+/*
+  generateRuleRegistry
+  Build tool: writes testaro/registry.ts from the rule modules present in the
+  testaro directory (issue #73). Run with npm run build:registry; the CI
+  workflow regenerates the registry and fails on drift, so the committed
+  registry always matches the rule modules on disk.
+*/
+
+// IMPORTS
+
+const fs = require('fs');
+const path = require('path');
+
+// CONSTANTS
+
+const ruleDir = path.join(__dirname, '..', 'testaro');
+const registryPath = path.join(ruleDir, 'registry.ts');
+
+// OPERATION
+
+// Get the rule IDs: every TypeScript rule module in the directory.
+const ruleIDs = fs.readdirSync(ruleDir)
+.filter(name => name.endsWith('.ts') && ! name.endsWith('.d.ts'))
+.map(name => name.replace(/\.ts$/, ''))
+.filter(name => name !== 'registry')
+.sort();
+// Compose the registry source.
+const lines = [];
+lines.push(
+  '/*',
+  '  © 2026 Jeff Witt.',
+  '',
+  '  Licensed under the MIT License. See LICENSE file at the project root or',
+  '  https://opensource.org/license/mit/ for details.',
+  '',
+  '  SPDX-License-Identifier: MIT',
+  '*/',
+  '',
+  '/*',
+  '  registry',
+  '  GENERATED by procs/generateRuleRegistry.js (npm run build:registry); do not edit.',
+  '  Maps each rule ID to a lazy loader of its module, preserving on-demand loading',
+  '  while giving consumers a checked RuleID union and a typed reporter (issue #73).',
+  '*/',
+  '',
+  '// TYPES',
+  '',
+  '// The report every rule reporter resolves with.',
+  'export interface RuleReport {',
+  '  data: unknown;',
+  '  totals: number[];',
+  '  standardInstances: unknown[];',
+  '}',
+  '// The module shape of a rule.',
+  'export interface RuleModule {',
+  '  reporter: (...args: any[]) => Promise<RuleReport>;',
+  '}',
+  '',
+  '// The IDs of all rule modules.',
+  'export type RuleID =');
+ruleIDs.forEach((id, index) => {
+  lines.push(`  | '${id}'${index === ruleIDs.length - 1 ? ';' : ''}`);
+});
+lines.push(
+  '',
+  '// CONSTANTS',
+  '',
+  '// Lazy loaders of the rule modules, keyed by rule ID.',
+  'export const ruleModules = {');
+ruleIDs.forEach(id => {
+  lines.push(`  ${id}: () => require('./${id}') as typeof import('./${id}'),`);
+});
+lines.push(
+  '} satisfies Record<RuleID, () => RuleModule>;',
+  '');
+// Write the registry if it changed.
+const source = lines.join('\n');
+const existing = fs.existsSync(registryPath) ? fs.readFileSync(registryPath, 'utf8') : '';
+if (source !== existing) {
+  fs.writeFileSync(registryPath, source);
+  console.log(`Wrote ${registryPath} with ${ruleIDs.length} rules`);
+}
+else {
+  console.log(`Registry is current (${ruleIDs.length} rules)`);
+}

package/procs/getSource.d.ts

@@ -0,0 +1,26 @@
+/*
+  © 2026 Jeff Witt.
+
+  Licensed under the MIT License. See LICENSE file at the project root or
+  https://opensource.org/license/mit/ for details.
+
+  SPDX-License-Identifier: MIT
+*/
+
+/*
+  getSource (hand-written declarations)
+  Minimal typings for the surface of procs/getSource.js that converted
+  TypeScript files use. Delete this file when getSource.js itself is converted
+  (issue #73).
+*/
+
+import type {Page} from 'playwright';
+
+export interface SourceData {
+  prevented: boolean;
+  source: string;
+  error?: string;
+}
+
+// Gets the source of the document of a page.
+export function getSource(page: Page): Promise<SourceData>;

package/procs/getSource.js

@@ -1,5 +1,6 @@
 /*
   © 2023–2024 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or
   https://opensource.org/license/mit/ for details.