testaro 67.0.0 → 68.0.0

package/procs/testaro.js

@@ -1,9 +1,8 @@
 /*
   © 2023–2024 CVS Health and/or one of its affiliates. All rights reserved.
-  © 2025 Jonathan Robert Pool.
+  © 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.
+  Licensed under the MIT License. See LICENSE file at the project root or  https://opensource.org/license/mit/ for details.
 
   SPDX-License-Identifier: MIT
 */
@@ -15,49 +14,45 @@
 
 // ########## IMPORTS
 
-// Module to get locator data.
-const {getLocatorData} = require('../procs/getLocatorData');
-// Module to get element IDs.
-const {boxOf, boxToString} = require('./identify');
-// Module to get the XPath of an element.
-const {xPath} = require('playwright-dompath');
+// Function to add a catalog index to a standard instance.
+const {addCatalogIndex} = require('./catalog');
+// Function to get a catalog index from an XPath.
+const {getXPathCatalogIndex} = require('./xPath');
 
 // ########## FUNCTIONS
 
-// Performs a standard test.
+// Tests for a testaro rule.
 exports.doTest = async (
   page,
+  catalog,
   withItems,
   ruleID,
   candidateSelector,
   whats,
   severity,
-  summaryTagName,
   getBadWhatString
 ) => {
-  // Return totals and standard instances for the rule.
-  return await page.evaluate(async args => {
-    // Get the arguments (summaryTagName must be upper-case or null).
+  const ruleData = await page.evaluate(async args => {
+    // Get the arguments.
     const [
       withItems,
-      ruleID,
       candidateSelector,
-      whats,
       severity,
-      summaryTagName,
       getBadWhatString
     ] = args;
-    // Get all candidates.
+    // Get all violator candidates.
     const candidates = document.body.querySelectorAll(candidateSelector);
     let violationCount = 0;
-    const standardInstances = [];
-    // Get a function that returns a violation description, if any, for the candidate.
+    // Initialize proto-instances.
+    const protoInstances = [];
+    // Parse the supplied string to get the classifier.
     const getBadWhat = eval(`(${getBadWhatString})`);
+    // Initialize data on the rule.
     let data = {};
     const totals = [0, 0, 0, 0];
     // For each candidate:
     for (const candidate of candidates) {
-      // Get the violation description, if any.
+      // 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) {
@@ -65,7 +60,7 @@ exports.doTest = async (
         violationCount++;
         let ruleWhat;
         const violationType = typeof violationWhat;
-        // If data on the violation were provided:
+        // If data on the violation were provided (unusual):
         if (violationType === 'object') {
           // Get the description and add the data to the rule data.
           ruleWhat = violationWhat.description;
@@ -76,57 +71,100 @@ exports.doTest = async (
           // Get it.
           ruleWhat = violationWhat;
         }
+        const ruleWhatStart = ruleWhat.slice(0, 2);
+        let ordinalSeverity = severity;
+        // If this violation has a custom severity:
+        if (/[0-3]:/.test(ruleWhatStart)) {
+          // Get it.
+          ordinalSeverity = Number(ruleWhat[0]);
+          // Remove it from the violation description.
+          ruleWhat = ruleWhat.slice(2);
+        }
+        // Increment the applicable rule-violation total.
+        totals[ordinalSeverity]++;
         // If itemization is required:
         if (withItems) {
-          const ruleWhatStart = ruleWhat.slice(0, 2);
-          let instanceSeverity = severity;
-          // If this violation has a custom severity:
-          if (/[0-3]:/.test(ruleWhatStart)) {
-            // Get it.
-            instanceSeverity = Number(ruleWhat[0]);
-            // Remove it from the violation description.
-            ruleWhat = ruleWhat.slice(2);
-          }
-          // Increment the violation totals.
-          totals[instanceSeverity]++;
-          // Add an instance to the instances.
-          standardInstances.push(
-            window.getInstance(candidate, ruleID, ruleWhat, 1, instanceSeverity)
-          );
-        }
-        // Otherwise, i.e. if itemization is not required:
-        else {
-          // Increment the violation totals.
-          totals[severity]++;
+          // Add a proto-instance to the proto-instances.
+          protoInstances.push({
+            what: ruleWhat,
+            ordinalSeverity,
+            pathID: window.getXPath(candidate)
+          });
         }
       }
     }
-    // If there are any violations and itemization is not required:
-    if (violationCount && ! withItems) {
-      // Add a summary instance to the instances.
-      standardInstances.push(
-        window.getInstance(null, ruleID, whats, violationCount, severity, summaryTagName)
-      );
-    }
     return {
       data,
       totals,
-      standardInstances
+      protoInstances
     }
   }, [
       withItems,
-      ruleID,
       candidateSelector,
-      whats,
       severity,
-      summaryTagName,
       getBadWhatString
     ]
   );
+  // Initialize the standard instances.
+  let standardInstances = [];
+  const {data, totals, protoInstances} = ruleData;
+  // If itemization is required:
+  if (withItems) {
+    // For each proto-instance:
+    protoInstances.forEach(protoInstance => {
+      const {what, ordinalSeverity, pathID} = protoInstance;
+      // Initialize a standard instance.
+      const standardInstance = {
+        ruleID,
+        what,
+        ordinalSeverity,
+        count: 1
+      };
+      // If the proto-instance includes an XPath:
+      if (pathID) {
+        // Use it to get the catalog index of the element.
+        const catalogIndex = getXPathCatalogIndex(catalog, pathID);
+        // If the acquisition succeeded:
+        if (catalogIndex) {
+          // Add the catalog index to the standard instance.
+          standardInstance.catalogIndex = catalogIndex;
+        }
+        // Otherwise, i.e. if the acquisition failed:
+        else {
+          // Add the XPath to the standard instance as its path ID.
+          standardInstance.pathID = pathID;
+        }
+      }
+      // Add the standard instance to the standard instances.
+      standardInstances.push(standardInstance);
+    });
+  }
+  // Otherwise, i.e. if itemization is not required:
+  else {
+    // For each ordinal severity:
+    for (const index in totals) {
+      // If there were any violations at that severity:
+      if (totals[index]) {
+        // Add a summary standard instance to the standard instances.
+        standardInstances.push({
+          ruleID,
+          what: whats,
+          ordinalSeverity: index,
+          count: totals[index]
+        });
+      }
+    }
+  }
+  // Return the data, totals, and standard instances.
+  return {
+    data,
+    totals,
+    standardInstances
+  };
 };
-// Returns a result from a basic test.
+// Tests for a doTest-ineligible Testaro rule.
 exports.getBasicResult = async (
-  page, withItems, ruleID, ordinalSeverity, summaryTagName, whats, data, violations
+  catalog, withItems, ruleID, ordinalSeverity, whats, data, violations
 ) => {
   // If the test was prevented:
   if (data.prevented) {
@@ -146,22 +184,17 @@ exports.getBasicResult = async (
     // For each violation:
     for (const violation of violations) {
       const {loc, what} = violation;
-      const elData = await getLocatorData(loc);
-      // Get the bounding box of the element.
-      const {tagName, id, location, excerpt} = elData;
-      const box = location.type === 'box' ? location.spec : await boxOf(loc);
-      // Add a standard instance to the instances.
-      standardInstances.push({
+      // Initialize a standard instance.
+      const protoInstance = {
         ruleID,
         what,
         ordinalSeverity,
-        tagName,
-        id,
-        location,
-        excerpt,
-        boxID: boxToString(box),
-        pathID: tagName === 'HTML' ? '/html' : await xPath(loc)
-      });
+        count: 1
+      };
+      // Add a catalog index or path ID to it.
+      addCatalogIndex(protoInstance, loc, catalog);
+      // Add the standard instance to the standard instances.
+      standardInstances.push(protoInstance);
     }
   }
   // Otherwise, i.e. if itemization is not required:
@@ -171,12 +204,7 @@ exports.getBasicResult = async (
       ruleID,
       what: whats,
       ordinalSeverity,
-      summaryTagName,
-      id: '',
-      location: {},
-      excerpt: '',
-      boxID: '',
-      pathID: ''
+      count: violations.length
     });
   }
   // Return the result.
@@ -186,54 +214,3 @@ exports.getBasicResult = async (
     standardInstances
   };
 };
-// Returns an awaited change in a visible element count.
-exports.getVisibleCountChange = async (
-  rootLoc, elementCount0, timeLimit = 400, settleInterval = 75
-) => {
-  const startTime = Date.now();
-  let timeout;
-  let settleChecker;
-  let elementCount1 = elementCount0;
-  // Set a time limit on the change.
-  const timeoutPromise = new Promise(resolve => {
-    timeout = setTimeout(() => {
-      clearInterval(settleChecker);
-      resolve();
-    }, timeLimit);
-  });
-  // Until the time limit expires, periodically:
-  const settlePromise = new Promise(resolve => {
-    settleChecker = setInterval(async () => {
-      const visiblesLoc = await rootLoc.locator('*:visible');
-      // Get the count.
-      elementCount1 = await visiblesLoc.count();
-      // If the count has changed:
-      if (elementCount1 !== elementCount0) {
-        // Stop.
-        clearTimeout(timeout);
-        clearInterval(settleChecker);
-        resolve();
-      }
-    }, settleInterval);
-  });
-  // When a change occurs or the time limit expires:
-  await Promise.race([timeoutPromise, settlePromise]);
-  const elapsedTime = Math.round(Date.now() - startTime);
-  // Return the change.
-  return {
-    change: elementCount1 - elementCount0,
-    elapsedTime
-  };
-};
-// Annotates every element on a page with a unique identifier.
-exports.addTestaroIDs = async page => {
-  // Wait for the page to be fully loaded.
-  await page.waitForLoadState('networkidle');
-  await page.evaluate(() => {
-    let serialID = 0;
-    for (const element of Array.from(document.querySelectorAll('*'))) {
-      const xPath = window.getXPath(element);
-      element.setAttribute('data-testaro-id', `${serialID++}#${xPath}`);
-    }
-  });
-};

package/procs/xPath.js

@@ -0,0 +1,62 @@
+/*
+  © 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.
+
+  SPDX-License-Identifier: MIT
+*/
+
+/*
+  xPath.js
+  Processes element XPaths.
+*/
+
+// FUNCTIONS
+
+// Normalizes an XPath.
+exports.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]`);
+      }
+    });
+    // Return the concatenated segments as the normalized XPath.
+    return normalizedSegments.join('/');
+  }
+  else {
+    return '';
+  }
+};
+// 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] : '';
+};
+// Gets a catalog index as a string from an XPath.
+exports.getXPathCatalogIndex = (catalog, xPath) => {
+  const index = catalog.pathID[xPath]?.[0] ?? '';
+  return index;
+};