testaro 78.0.6 → 78.4.0

package/procs/testaro.ts

@@ -0,0 +1,321 @@
+/*
+  © 2023–2024 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  https://opensource.org/license/mit/ for details.
+
+  SPDX-License-Identifier: MIT
+*/
+
+// ########## IMPORTS
+
+// Function to get a catalog index from an XPath.
+import {getXPathCatalogIndex} from './xPath';
+// Function to build a standard instance.
+import {getInstance, type InstanceSpec} from './standard';
+import type {Locator, Page} from 'playwright';
+import type {GetBadWhat, Outcome, Report, SeverityTotals, StandardInstance, UncertaintyCode} from '../types';
+
+/*
+  testaro
+  Utilities for Testaro tests. Compiled to testaro.js by tsc (issue #73); edit
+  this file, not the emitted one.
+*/
+
+// ########## TYPES
+
+// A violation found in the page before it becomes a standard instance.
+interface ProtoInstance {
+  what: string;
+  ordinalSeverity: number;
+  outcome?: Outcome;
+  xPath: string;
+}
+// What doTest and getBasicResult return to the calling rule module.
+export interface RuleResult {
+  data: Record<string, unknown>;
+  totals: SeverityTotals;
+  standardInstances: StandardInstance[];
+}
+// A violation reported by a doTest-ineligible rule module.
+interface BasicViolation {
+  loc: Locator;
+  what: string;
+  // A violation may specify its own certainty.
+  outcome?: Outcome;
+  uncertainty?: UncertaintyCode;
+  needed?: string;
+}
+
+// ########## FUNCTIONS
+
+// Returns a standard instance, leaving the outcome unset if the violation did not specify one, so
+// that the testaro tool can apply the rule's default outcome.
+const getRuleInstance = (spec: InstanceSpec): StandardInstance => {
+  const instance = getInstance(spec);
+  if (! spec.outcome) {
+    instance.outcome = undefined;
+  }
+  return instance;
+};
+
+// Tests for a testaro rule.
+export const doTest = async (
+  page: Page,
+  report: Report,
+  withItems: boolean,
+  ruleID: string,
+  candidateSelector: string,
+  whats: string,
+  severity: number,
+  getBadWhatString: string
+): Promise<RuleResult> => {
+  // The subtree roots the rule is restricted to, if the test act has scope changed and the
+  // testaro tool judged the rule element-local (set per rule by tests/testaro.ts).
+  const scopeRoots = report.ruleScopeRoots ?? null;
+  const ruleData = await page.evaluate(async args => {
+    // Get the arguments.
+    const [
+      withItems,
+      candidateSelector,
+      severity,
+      getBadWhatString,
+      scopeRoots
+    ] = args;
+    // Get all violator candidates, within the scope roots if any.
+    let candidates = Array.from(document.querySelectorAll(candidateSelector));
+    if (scopeRoots && scopeRoots.length) {
+      const roots = scopeRoots
+      .map(selector => {
+        try {
+          return document.querySelector(selector);
+        }
+        catch {
+          return null;
+        }
+      })
+      .filter((root): root is Element => Boolean(root));
+      candidates = candidates.filter(candidate => roots.some(root => root.contains(candidate)));
+    }
+    let violationCount = 0;
+    // Initialize proto-instances.
+    const protoInstances: ProtoInstance[] = [];
+    // Initialize counts of cantTell violations by ordinal severity, for summary instances.
+    const cantTellTotals = [0, 0, 0, 0];
+    /*
+      Parse the supplied string to get the classifier. The predicate travels as
+      source text (serialized with toString() by the rule module) because it
+      must run inside the page; this cast is the single point where its type is
+      asserted rather than checked (issue #73, RFC decision 4). The eval input
+      is first-party rule-module source from this repository, never target-page
+      or user data; replacing the eval pipeline with a bundled artifact is the
+      Phase 3 reassessment recorded on issue #73.
+    */
+    const getBadWhat = eval(`(${getBadWhatString})`) as GetBadWhat;
+    // Initialize data on the rule.
+    let data: Record<string, unknown> = {};
+    const totals = [0, 0, 0, 0];
+    // For each candidate:
+    for (const candidate of candidates) {
+      // Classify it as and get a violation description if a violator or undefined if not.
+      const violationWhat = await getBadWhat(candidate);
+      // If the candidate violates the rule:
+      if (violationWhat) {
+        // Increment the violation count.
+        violationCount++;
+        let ruleWhat;
+        const violationType = typeof violationWhat;
+        // If data on the violation were provided (unusual):
+        if (violationType === 'object') {
+          // Get the description and add the data to the rule data.
+          ruleWhat = (violationWhat as {description: string; data?: unknown}).description;
+          data[violationCount - 1] = (violationWhat as {description: string; data?: unknown}).data;
+        }
+        // Otherwise, i.e. if only a description of the violation was provided:
+        else if (violationType === 'string') {
+          // Get it.
+          ruleWhat = violationWhat as string;
+        }
+        let ordinalSeverity = severity;
+        let outcome: 'cantTell' | undefined;
+        // A predicate that returns a truthy non-object non-string would make this throw,
+        // exactly as in the JavaScript original.
+        // If this violation has a custom severity or outcome prefix (e.g. 2:, 2?:, or ?:):
+        const prefixMatch = (ruleWhat as string).match(/^([0-3])?(\?)?:/);
+        if (prefixMatch) {
+          // If the prefix has a severity, get it.
+          if (prefixMatch[1]) {
+            ordinalSeverity = Number(prefixMatch[1]);
+          }
+          // If the prefix marks the violation as uncertain, record this.
+          if (prefixMatch[2]) {
+            outcome = 'cantTell';
+            cantTellTotals[ordinalSeverity]++;
+          }
+          // Remove the prefix from the violation description.
+          ruleWhat = (ruleWhat as string).slice(prefixMatch[0].length);
+        }
+        // Increment the applicable rule-violation total.
+        totals[ordinalSeverity]++;
+        // If itemization is required:
+        if (withItems) {
+          const protoInstance: ProtoInstance = {
+            what: ruleWhat as string,
+            ordinalSeverity,
+            outcome,
+            xPath: window.getXPath(candidate as Element) ?? '/html'
+          };
+          // Add a proto-instance to the proto-instances.
+          protoInstances.push(protoInstance);
+        }
+      }
+    }
+    return {
+      data,
+      totals,
+      cantTellTotals,
+      protoInstances
+    }
+  }, [
+      withItems,
+      candidateSelector,
+      severity,
+      getBadWhatString,
+      scopeRoots
+    ] as const
+  );
+  // Initialize the standard instances. Any instance without an outcome gets the rule's default
+  // outcome from the testaro tool.
+  let standardInstances: StandardInstance[] = [];
+  const {data, totals, cantTellTotals, protoInstances} = ruleData;
+  // If itemization is required:
+  if (withItems) {
+    // For each proto-instance:
+    protoInstances.forEach(protoInstance => {
+      const {what, ordinalSeverity, outcome, xPath} = protoInstance;
+      // Add a standard instance to the standard instances.
+      standardInstances.push(getRuleInstance({
+        ruleID,
+        what,
+        ordinalSeverity,
+        outcome,
+        catalogIndex: xPath ? getXPathCatalogIndex(report, xPath) : undefined
+      }));
+    });
+  }
+  // Otherwise, i.e. if itemization is not required:
+  else {
+    // For each ordinal severity:
+    totals.forEach((total, ordinalSeverity) => {
+      const cantTellTotal = cantTellTotals[ordinalSeverity];
+      // If there were any asserted violations at that severity:
+      if (total - cantTellTotal) {
+        // Add a summary standard instance to the standard instances.
+        standardInstances.push(getRuleInstance({
+          ruleID,
+          what: whats,
+          ordinalSeverity,
+          count: total - cantTellTotal
+        }));
+      }
+      // If there were any uncertain violations at that severity:
+      if (cantTellTotal) {
+        // Add a summary standard instance for them.
+        standardInstances.push(getRuleInstance({
+          ruleID,
+          what: whats,
+          ordinalSeverity,
+          outcome: 'cantTell',
+          count: cantTellTotal
+        }));
+      }
+    });
+  }
+  // Return the data, totals, and standard instances.
+  return {
+    data,
+    totals: totals as SeverityTotals,
+    standardInstances
+  };
+};
+// Adds a catalog index or, if necessary, an XPath to a proto-instance.
+const addCatalogIndex = async (
+  protoInstance: StandardInstance, locator: Locator, report: Report
+): Promise<StandardInstance> => {
+  // Get the XPath of the element referenced by the locator.
+  const xPath = await locator.evaluate(element => window.getXPath(element) ?? '/html');
+  // Add a catalog index to the proto-instance.
+  protoInstance.catalogIndex = getXPathCatalogIndex(report, xPath);
+  // Return the proto-instance with any modification.
+  return protoInstance;
+};
+// Tests for a doTest-ineligible Testaro rule.
+export const getBasicResult = async (
+  report: Report,
+  withItems: boolean,
+  ruleID: string,
+  ordinalSeverity: StandardInstance['ordinalSeverity'],
+  whats: string,
+  data: {prevented?: boolean; [key: string]: unknown},
+  violations: BasicViolation[]
+): Promise<RuleResult> => {
+  // If the test was prevented:
+  if (data.prevented) {
+    // Return this.
+    return {
+      data,
+      totals: [0, 0, 0, 0],
+      standardInstances: []
+    };
+  }
+  // Otherwise, i.e. if the test was not prevented:
+  const totals: SeverityTotals = [0, 0, 0, 0];
+  totals[ordinalSeverity] = violations.length;
+  const standardInstances: StandardInstance[] = [];
+  // If itemization is required:
+  if (withItems) {
+    // For each violation:
+    for (const violation of violations) {
+      const {loc, what, outcome, uncertainty, needed} = violation;
+      // Initialize a standard instance.
+      const protoInstance = getRuleInstance({
+        ruleID,
+        what,
+        ordinalSeverity,
+        outcome,
+        uncertainty,
+        needed
+      });
+      // Add a catalog index to it, awaited so the index is present before the
+      // report can be serialized (issue #100).
+      await addCatalogIndex(protoInstance, loc, report);
+      // Add the standard instance to the standard instances.
+      standardInstances.push(protoInstance);
+    }
+  }
+  // Otherwise, i.e. if itemization is not required:
+  else {
+    // Add a summary instance per outcome to the instances.
+    const outcomeCounts: Partial<Record<Outcome, number>> = {};
+    violations.forEach(violation => {
+      const outcome = violation.outcome || 'failed';
+      outcomeCounts[outcome] = (outcomeCounts[outcome] || 0) + 1;
+    });
+    (Object.keys(outcomeCounts) as Outcome[]).forEach(outcome => {
+      standardInstances.push(getRuleInstance({
+        ruleID,
+        what: whats,
+        ordinalSeverity,
+        outcome,
+        count: outcomeCounts[outcome]
+      }));
+    });
+  }
+  // Return the result.
+  return {
+    data,
+    totals,
+    standardInstances
+  };
+};

package/procs/userPath.js

@@ -0,0 +1,126 @@
+/*
+  © 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
+*/
+
+/*
+  userPath.js
+  Converts a recorded user path (a start URL and a sequence of actions of the kinds a
+  Playwright codegen recording yields: click, fill, select, navigate, wait, checkpoint) into
+  the acts of a Testaro job, so that a job tests the page states the path reaches. Each
+  action becomes one act; each checkpoint action becomes a checkpoint act followed by the
+  test acts requested. See docs/checkpoint-scanning.md (Phase 4).
+
+  An action is {type, selector?, value?, url?, timeout?, label?}. Selectors are Playwright
+  selectors (CSS, or text=, role=, label= forms), used as the selector property of the act.
+*/
+
+// CONSTANTS
+
+// The action types and the act types they become.
+const actionActTypes = exports.actionActTypes = {
+  click: 'button',
+  fill: 'text',
+  select: 'select',
+  navigate: 'url',
+  wait: 'state',
+  checkpoint: 'checkpoint'
+};
+
+// FUNCTIONS
+
+// Returns a checkpoint name unique among those used, from a label or an ordinal.
+const getCheckpointName = (label, ordinal, used) => {
+  const base = (label || '').trim().replace(/\s+/g, ' ') || `checkpoint${ordinal}`;
+  let name = base === 'start' ? `${base}-${ordinal}` : base;
+  let suffix = 1;
+  while (used.has(name)) {
+    name = `${base}-${++suffix}`;
+  }
+  used.add(name);
+  return name;
+};
+/*
+  Returns the acts of a job for a user path, or throws if an action is invalid.
+    startUrl: the URL the path starts at (the launch act's target).
+    actions: the recorded actions.
+    testActs: the test acts (without checkpoint-dependent properties) to run at each
+      checkpoint, e.g. [{type: 'test', which: 'axe', detailLevel: 0}]; each is copied per
+      checkpoint. With scope 'changed', the first checkpoint's copies are given scope 'page',
+      since there is no earlier checkpoint to compare.
+    scanAtCheckpoints: whether checkpoints get the test acts (default true).
+    what: a description of the launch target.
+*/
+exports.getUserPathActs = ({startUrl, actions, testActs = [], scanAtCheckpoints = true, what}) => {
+  if (! startUrl || typeof startUrl !== 'string') {
+    throw new Error('User path has no start URL');
+  }
+  if (! Array.isArray(actions)) {
+    throw new Error('User path actions are not an array');
+  }
+  const acts = [{
+    type: 'launch',
+    target: {url: startUrl, what: what || 'start of the user path'}
+  }];
+  const usedNames = new Set();
+  let checkpointCount = 0;
+  actions.forEach((action, index) => {
+    const {type, selector, value, url, timeout, label} = action || {};
+    const comment = label || undefined;
+    const need = (condition, message) => {
+      if (! condition) {
+        throw new Error(`Action ${index} (${type}): ${message}`);
+      }
+    };
+    if (type === 'click') {
+      need(selector, 'requires a selector');
+      acts.push({type: 'button', selector, what: comment});
+    }
+    else if (type === 'fill') {
+      need(selector, 'requires a selector');
+      need(typeof value === 'string' && value.length, 'requires a value');
+      acts.push({type: 'text', selector, what: value, clear: true});
+    }
+    else if (type === 'select') {
+      need(selector, 'requires a selector');
+      need(typeof value === 'string' && value.length, 'requires a value');
+      acts.push({type: 'select', selector, what: value});
+    }
+    else if (type === 'navigate') {
+      need(url, 'requires a url');
+      acts.push({type: 'url', which: url, what: comment});
+    }
+    else if (type === 'wait') {
+      // A recorded pause becomes a wait for the page to be idle; the pause length is kept
+      // as a comment.
+      acts.push({type: 'state', which: 'idle', what: `pause ${timeout ?? 1000} ms`});
+    }
+    else if (type === 'checkpoint') {
+      const name = getCheckpointName(label, ++checkpointCount, usedNames);
+      acts.push({type: 'checkpoint', which: name, what: comment});
+      if (scanAtCheckpoints) {
+        testActs.forEach(testAct => {
+          const act = {... testAct};
+          if (act.scope === 'changed' && checkpointCount === 1) {
+            act.scope = 'page';
+          }
+          acts.push(act);
+        });
+      }
+    }
+    else {
+      throw new Error(`Action ${index}: unknown type ${type}`);
+    }
+  });
+  // Remove undefined comments, so the acts serialize cleanly.
+  acts.forEach(act => {
+    if (act.what === undefined) {
+      delete act.what;
+    }
+  });
+  return acts;
+};

package/procs/xPath.d.ts

@@ -0,0 +1,4 @@
+import type { Report } from '../types';
+export declare const getNormalizedXPath: (xPath: string | null | undefined) => string;
+export declare const getAttributeXPath: (html: string | null | undefined) => string;
+export declare const getXPathCatalogIndex: (report: Report, xPath: string, checkpoint?: number) => string;

package/procs/xPath.js

@@ -1,5 +1,7 @@
+"use strict";
 /*
   © 2024 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2026 Jeff Witt.
   © 2026 Jonathan Robert Pool.
 
   Licensed under the MIT License. See LICENSE file at the project root or
@@ -7,79 +9,95 @@
 
   SPDX-License-Identifier: MIT
 */
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getXPathCatalogIndex = exports.getAttributeXPath = exports.getNormalizedXPath = void 0;
 /*
-  xPath.js
-  Processes element XPaths.
+  xPath
+  Processes element XPaths. Compiled to xPath.js by tsc (issue #73); edit this
+  file, not the emitted one.
 */
-
 // FUNCTIONS
-
 // Normalizes an XPath.
-exports.getNormalizedXPath = xPath => {
-  if (xPath) {
-    if (xPath === '/') {
-      xPath = '/html';
+const getNormalizedXPath = (xPath) => {
+    if (xPath) {
+        if (xPath === '/') {
+            xPath = '/html';
+        }
+        xPath = xPath.replace(/^\.\/\//, '/');
+        const segments = xPath.split('/');
+        // Initialize an array of normalized segments.
+        const normalizedSegments = [];
+        // For each segment of the XPath:
+        segments.forEach(segment => {
+            // If the segment is html[1] or body[1]:
+            if (/html\[1\]|body\[1\]/.test(segment)) {
+                // Add it without its subscript to the array.
+                normalizedSegments.push(segment.replace(/\[1\]/, ''));
+            }
+            // Otherwise, if the segment is empty or html or body or ends with a subscript:
+            else if (segment === '' || ['html', 'body'].includes(segment) || segment.endsWith(']')) {
+                // Add it to the array.
+                normalizedSegments.push(segment);
+            }
+            // Otherwise, i.e. if the segment is a tag name with no subscript:
+            else {
+                // Add it with a subscript 1 to the array.
+                normalizedSegments.push(`${segment}[1]`);
+            }
+        });
+        // If the final segment contains any nonstandard character:
+        if (/[[^\]A-Za-z0-9]/.test(segments[segments.length - 1])) {
+            // Remove it.
+            normalizedSegments.pop();
+        }
+        // Return the concatenated segments as the normalized XPath.
+        return normalizedSegments.join('/');
     }
-    xPath = xPath.replace(/^\.\/\//, '/');
-    const segments = xPath.split('/');
-    // Initialize an array of normalized segments.
-    const normalizedSegments = [];
-    // For each segment of the XPath:
-    segments.forEach(segment => {
-      // If the segment is html[1] or body[1]:
-      if (/html\[1\]|body\[1\]/.test(segment)) {
-        // Add it without its subscript to the array.
-        normalizedSegments.push(segment.replace(/\[1\]/, ''));
-      }
-      // Otherwise, if the segment is empty or html or body or ends with a subscript:
-      else if (segment === '' || ['html', 'body'].includes(segment) || segment.endsWith(']')) {
-        // Add it to the array.
-        normalizedSegments.push(segment);
-      }
-      // Otherwise, i.e. if the segment is a tag name with no subscript:
-      else {
-        // Add it with a subscript 1 to the array.
-        normalizedSegments.push(`${segment}[1]`);
-      }
-    });
-    // If the final segment contains any nonstandard character:
-    if (/[[^\]A-Za-z0-9]/.test(segments[segments.length - 1])) {
-      // Remove it.
-      normalizedSegments.pop();
+    else {
+        return '/html';
     }
-    // Return the concatenated segments as the normalized XPath.
-    return normalizedSegments.join('/');
-  }
-  else {
-    return '/html';
-  }
 };
+exports.getNormalizedXPath = getNormalizedXPath;
 // Gets an XPath from a data-xpath attribute in an HTML excerpt.
-exports.getAttributeXPath = html => {
-  const match = html.match(/ data-xpath="([^" ]+)"/);
-  return match ? match[1] : '/html';
+const getAttributeXPath = (html) => {
+    // If there is no excerpt (e.g. a Nu Html Checker message without an extract):
+    if (!html) {
+        // Return the fallback XPath, as for an excerpt without a data-xpath attribute.
+        return '/html';
+    }
+    const match = html.match(/ data-xpath="([^" ]+)"/);
+    return match ? match[1] : '/html';
 };
+exports.getAttributeXPath = getAttributeXPath;
 // Gets a tag name from an XPath.
-const getXPathTagName = xPath => {
-  return xPath.split('/').pop().replace(/\[.+/, '').toUpperCase();
+const getXPathTagName = (xPath) => {
+    return xPath.split('/').pop().replace(/\[.+/, '').toUpperCase();
 };
-// Gets a catalog index as a string from an XPath.
-exports.getXPathCatalogIndex = (report, xPath) => {
-  const {catalog} = report;
-  report.pathIDs ??= {};
-  // Get the index of the catalog item with the XPath.
-  const index = report.pathIDs[xPath];
-  // If no such item exists (an index of '0' is a match, so test for absence, not falsity):
-  if (index === undefined) {
-    // Add an item to the catalog, keyed by the count of items already in it.
-    const newIndex = `${Object.keys(catalog).length}`;
-    catalog[newIndex] = {
-      pathID: xPath,
-      tagName: getXPathTagName(xPath)
-    };
-    report.pathIDs[xPath] = newIndex;
-    return newIndex;
-  }
-  return index;
+// Gets a catalog index as a string from an XPath, within a checkpoint (the active one by
+// default). An XPath the checkpoint's catalog lacks gets a stub entry, keyed from the report's
+// monotonic counter so that entries of different checkpoints never collide.
+const getXPathCatalogIndex = (report, xPath, checkpoint = report.activeCheckpoint ?? 0) => {
+    // The catalog always exists by the time tests cite elements (getCatalog ran first).
+    const { catalog } = report;
+    report.pathIDs ??= {};
+    const pathIDs = (report.pathIDs[checkpoint] ??= {});
+    // Get the index of the catalog item with the XPath.
+    const index = pathIDs[xPath];
+    // If no such item exists (an index of '0' is a match, so test for absence, not falsity):
+    if (index === undefined) {
+        // Add an item to the catalog, keyed by the counter (or, in a report without one, by the
+        // count of items already in it).
+        const newIndex = report.catalogNextIndex === undefined
+            ? `${Object.keys(catalog).length}`
+            : `${report.catalogNextIndex++}`;
+        catalog[newIndex] = {
+            pathID: xPath,
+            tagName: getXPathTagName(xPath),
+            checkpoint
+        };
+        pathIDs[xPath] = newIndex;
+        return newIndex;
+    }
+    return index;
 };
+exports.getXPathCatalogIndex = getXPathCatalogIndex;