testaro 67.0.0 → 68.0.0

package/testaro/secHeading.js

@@ -1,10 +1,9 @@
 /*
   © 2025 CVS Health and/or one of its affiliates. All rights reserved.
   © 2025 Juan S. Casado.
-  © 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
 */
@@ -21,7 +20,7 @@ const {doTest} = require('../procs/testaro');
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (page, withItems) => {
+exports.reporter = async (page, catalog, withItems) => {
   const getBadWhat = element => {
     // Get the children of the element.
     const children = Array.from(element.children);
@@ -45,6 +44,6 @@ exports.reporter = async (page, withItems) => {
   const selector = 'section, article, nav, aside, main';
   const whats = 'First child headings of sectioning containers are deeper than others';
   return await doTest(
-    page, withItems, 'secHeading', selector, whats, 0, null, getBadWhat.toString()
+    page, catalog, withItems, 'secHeading', selector, whats, 0, getBadWhat.toString()
   );
 };

package/testaro/shoot0.js

@@ -1,5 +1,5 @@
 /*
-  © 2025 Jonathan Robert Pool.
+  © 2025–2026 Jonathan Robert Pool.
   Licensed under the MIT License. See LICENSE file for details.
 */
 
@@ -14,8 +14,9 @@ const {shoot} = require('../procs/shoot');
 
 // FUNCTIONS
 
+// Makes and saves the first screenshot.
 exports.reporter = async page => {
-  // Make and save the first screenshot.
+  // Make and save the screenshot.
   const pngPath = await shoot(page, 0);
   // Return whether the screenshot was prevented.
   return {

package/testaro/shoot1.js

@@ -1,5 +1,5 @@
 /*
-  © 2025 Jonathan Robert Pool.
+  © 2025–2026 Jonathan Robert Pool.
   Licensed under the MIT License. See LICENSE file for details.
 */
 
@@ -20,12 +20,13 @@ const tmpDir = os.tmpdir();
 
 // FUNCTIONS
 
+// Make and save the second screenshot.
 exports.reporter = async page => {
   const tempFileNames = await fs.readdir(tmpDir);
   let pngPath = '';
   // If there is a shoot0 file:
   if (tempFileNames.includes('testaro-shoot-0.png')) {
-    // Make and save the second screenshot.
+    // Make and save the screenshot.
     pngPath = await shoot(page, 1);
   }
   // Return whether the screenshot was prevented.

package/testaro/styleDiff.js

@@ -1,8 +1,8 @@
 /*
   © 2021–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.
+  Licensed under the MIT License. See LICENSE file at the project root or  https://opensource.org/license/mit/ for details.
 
   SPDX-License-Identifier: MIT
 */
@@ -76,7 +76,8 @@ const linksByType = async page => await page.evaluateHandle(() => {
     list: listLinks
   };
 });
-exports.reporter = async (page, withItems) => {
+// Runs the test and returns the result.
+exports.reporter = async (page, _, withItems) => {
   // Get an object with arrays of list links and adjacent links as properties.
   const linkTypes = await linksByType(page);
   return await page.evaluate(args => {
@@ -254,16 +255,8 @@ exports.reporter = async (page, withItems) => {
         standardInstances.push({
           ruleID: 'styleDiff',
           what: `${currentData[1]} have ${elementSubtotals.length} different styles`,
-          count: extraCount,
           ordinalSeverity: severity,
-          tagName: currentData[2],
-          id: '',
-          location: {
-            doc: '',
-            type: '',
-            spec: ''
-          },
-          excerpt: ''
+          count: extraCount
         });
       }
     });

package/testaro/tabNav.js

@@ -1,6 +1,6 @@
 /*
   © 2021–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.
@@ -13,88 +13,16 @@
   This test reports nonstandard keyboard navigation among tab elements in visible tab lists. Standards are based on https://www.w3.org/TR/wai-aria-practices-1.1/#tabpanel.
 */
 
+// IMPORTS
+
+const {getXPathCatalogIndex} = require('../procs/xPath');
+
 // CONSTANTS
 
 const data = {};
 
 // FUNCTIONS
 
-// Returns the text associated with an element.
-const allText = async (page, elementHandle) => await page.evaluate(element => {
-  // Identify the element, if specified, or else the focused element.
-  const el = element || document.activeElement;
-  // Initialize an array of its texts.
-  const texts = [];
-  // FUNCTION DEFINITION START
-  // Removes excess spacing from a string.
-  const debloat = text => text.trim().replace(/\s+/g, ' ');
-  // FUNCTION DEFINITION END
-  // Add any attribute label to the array.
-  const ariaLabel = el.getAttribute('aria-label');
-  if (ariaLabel) {
-    const trimmedLabel = debloat(ariaLabel);
-    if (trimmedLabel) {
-      texts.push(trimmedLabel);
-    }
-  }
-  // Add any explicit and implicit labels to the array.
-  const labelNodeList = el.labels;
-  if (labelNodeList && labelNodeList.length) {
-    const labels = Array.from(labelNodeList);
-    const labelTexts = labels
-    .map(label => label.textContent && debloat(label.textContent))
-    .filter(text => text);
-    if (labelTexts.length) {
-      texts.push(...labelTexts);
-    }
-  }
-  // Add any referenced labels to the array.
-  if (el.hasAttribute('aria-labelledby')) {
-    const labelerIDs = el.getAttribute('aria-labelledby').split(/\s+/);
-    labelerIDs.forEach(id => {
-      const labeler = document.getElementById(id);
-      if (labeler) {
-        const labelerText = debloat(labeler.textContent);
-        if (labelerText) {
-          texts.push(labelerText);
-        }
-      }
-    });
-  }
-  // Add any image text alternatives to the array.
-  const altTexts = Array
-  .from(element.querySelectorAll('img[alt]:not([alt=""])'))
-  .map(img => debloat(img.alt))
-  .join('; ');
-  if (altTexts.length) {
-    texts.push(altTexts);
-  }
-  // Add the first 100 characters of any text content of the element to the array.
-  const ownText = element.textContent;
-  if (ownText) {
-    const minText = debloat(ownText);
-    if (minText) {
-      texts.push(minText.slice(0, 100));
-    }
-  }
-  // Add any ID of the element to the array.
-  const id = element.id;
-  if (id) {
-    texts.push(`#${id}`);
-  }
-  // Identify a concatenation of the texts.
-  let textChain = texts.join('; ');
-  // If it is empty:
-  if (! textChain) {
-    // Substitute the HTML of the element.
-    textChain = `{${debloat(element.outerHTML)}}`;
-    if (textChain === '{}') {
-      textChain = '';
-    }
-  }
-  // Return a concatenation of the texts in the array.
-  return textChain;
-}, elementHandle);
 // Returns the index of the focused tab in an array of tabs.
 const focusedTab = async (tabs, page) => await page.evaluate(tabs => {
   const focus = document.activeElement;
@@ -104,7 +32,7 @@ const focusedTab = async (tabs, page) => await page.evaluate(tabs => {
   console.log(`ERROR: could not find focused tab (${error.message})`);
   return -1;
 });
-// Tests a navigation on a tab element.
+// Tests a navigation on a focused tab element.
 const testKey = async (
   tabs, tabElement, keyName, keyProp, goodIndex, elementIsCorrect, itemData, withItems, page
 ) => {
@@ -234,24 +162,9 @@ const testTabs = async (tabs, index, listOrientation, listIsCorrect, withItems,
     const itemData = {};
     // If itemization is required:
     if (withItems) {
-      let found = true;
       // Initialize a report on the element.
-      const moreItemData = await page.evaluate(element => ({
-        tagName: element.tagName,
-        id: element.id
-      }), currentTab)
-      .catch(error => {
-        console.log(`ERROR: could not get tag name (${error.message})`);
-        found = false;
-        data.prevented = true;
-        return 'ERROR: not found';
-      });
-      if (found) {
-        itemData.tagName = moreItemData.tagName;
-        itemData.id = moreItemData.id;
-        itemData.text = await allText(page, currentTab);
-        itemData.navigationErrors = [];
-      }
+      itemData.xPath = await page.evaluate(element => window.getXPath(element));
+      itemData.navigationErrors = [];
     }
     // Test the element with each navigation key.
     isCorrect = await testKey(
@@ -370,8 +283,8 @@ const testTabLists = async (tabLists, withItems, page) => {
     }
   }
 };
-// Tests tab-list navigation and reports results.
-exports.reporter = async (page, withItems) => {
+// Runs the test and returns the result.
+exports.reporter = async (page, catalog, withItems) => {
   // Initialize the results.
   data.totals = {
     navigations: {
@@ -453,38 +366,37 @@ exports.reporter = async (page, withItems) => {
   if (withItems) {
     // For each bad tab:
     data.tabElements.incorrect.forEach(item => {
-      // Create a standard instance.
-      standardInstances.push({
+      // Create a proto-instance.
+      const protoInstance = {
         ruleID: 'tabNav',
         what: `Tab responds nonstandardly to ${item.navigationErrors.join(', ')}`,
         ordinalSeverity: 1,
-        tagName: item.tagName,
-        id: item.id,
-        location: {
-          doc: '',
-          type: '',
-          spec: ''
-        },
-        excerpt: item.text
-      });
+        count: 1
+      };
+      // Try to get a catalog index from the xPath of the tab.
+      const catalogIndex = getXPathCatalogIndex(catalog, item.xPath);
+      // If the acquisition succeeded:
+      if (catalogIndex) {
+        // Add the catalog index to the proto-instance.
+        protoInstance.catalogIndex = catalogIndex;
+      }
+      // Otherwise, i.e. if the acquisition failed:
+      else {
+        // Add the XPath to the proto-instance as a path ID.
+        protoInstance.pathID = item.xPath;
+      }
+      // Add the proto-instance to the standard instances.
+      standardInstances.push(protoInstance);
     });
   }
-  // Otherwise, if navigation is not required and any navigations are bad:
+  // Otherwise, if navigation is not required and any navigations were bad:
   else if (data.totals.navigations.all.incorrect) {
     // Create a standard instance.
     standardInstances.push({
       ruleID: 'tabNav',
       what: 'Tab lists have nonstandard navigation',
       ordinalSeverity: 1,
-      count: data.totals.navigations.all.incorrect,
-      tagName: '',
-      id: '',
-      location: {
-        doc: '',
-        type: '',
-        spec: ''
-      },
-      excerpt: ''
+      count: data.totals.navigations.all.incorrect
     });
   }
   // Return the result.

package/testaro/targetSmall.js

@@ -1,9 +1,8 @@
 /*
   © 2023–2025 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
 */
@@ -17,9 +16,9 @@
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (page, withItems) => {
+exports.reporter = async (page, _, withItems) => {
   // Return totals and standard instances for the rule.
-  return await page.evaluate(withItems => {
+  const protoResult = await page.evaluate(withItems => {
     // Get all pointer targets.
     const allPTs = Array.from(document.body.querySelectorAll('label, button, input, a'));
     // Get the visible ones.
@@ -41,7 +40,7 @@ exports.reporter = async (page, withItems) => {
     });
     // Initialize the counts of minor and major violations.
     let violationCounts = [0, 0];
-    const instances = [];
+    const protoInstances = [];
     // For each visible pointer target:
     visiblePTs.forEach((element, index) => {
       const [centerX, centerY] = ptsData[index];
@@ -71,8 +70,14 @@ exports.reporter = async (page, withItems) => {
           // If itemization is required:
           if (withItems) {
             const what = `Pointer-target centerpoint is only ${Math.round(minPlanarDistance)}px from another one`;
-            // Add an instance to the instances.
-            instances.push(window.getInstance(element, 'targetSmall', what, 1, ordinalSeverity));
+            // Add a proto-instance to the proto-instances.
+            protoInstances.push({
+              ruleID: 'targetSmall',
+              what,
+              ordinalSeverity,
+              count: 1,
+              xPath: window.getXPath(element)
+            });
           }
         }
       }
@@ -81,21 +86,31 @@ exports.reporter = async (page, withItems) => {
     if (! withItems) {
       // If there were any major violations:
       if (violationCounts[1]) {
-        const what = 'Pointer-target centerpoints are less than 24px from others';
-        // Add a summary instance to the instances.
-        instances.push(window.getInstance(null, 'targetSmall', what, violationCounts[1], 1));
+        // Add a summary instance to the proto-instances.
+        protoInstances.push({
+          ruleID: 'targetSmall',
+          what: 'Pointer-target centerpoints are less than 24px from others',
+          ordinalSeverity: 1,
+          count: violationCounts[1]
+        });
       }
       // If there were any minor violations:
       if (violationCounts[0]) {
-        const what = 'Pointer-target centerpoints are less than 44px from others';
-        // Add a summary instance to the instances.
-        instances.push(window.getInstance(null, 'targetSmall', what, violationCounts[0], 0));
+        // Add a summary instance to the proto-instances.
+        protoInstances.push({
+          ruleID: 'targetSmall',
+          what: 'Pointer-target centerpoints are less than 44px from others',
+          ordinalSeverity: 0,
+          count: violationCounts[0]
+        });
       }
     }
     return {
       data: {},
       totals: [...violationCounts, 0, 0],
-      standardInstances: instances
+      standardInstances: protoInstances
     };
   }, withItems);
+  // Return the result.
+  return protoResult;
 };

package/testaro/textNodes.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.
@@ -16,7 +17,8 @@
 
 // FUNCTIONS
 
-exports.reporter = async (page, withItems, detailLevel, text = '') => {
+// Runs the test and returns the result.
+exports.reporter = async (page, _, _, detailLevel, text = '') => {
   let data = {};
   // Get the data on the text nodes.
   try {

package/testaro/textSem.js

@@ -1,9 +1,8 @@
 /*
   © 2025 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
 */
@@ -20,7 +19,7 @@ const {doTest} = require('../procs/testaro');
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (page, withItems) => {
+exports.reporter = async (page, catalog, withItems) => {
   const getBadWhat = element => {
     const isVisible = element.checkVisibility({
       contentVisibilityAuto: true,
@@ -39,6 +38,6 @@ exports.reporter = async (page, withItems) => {
   const selector = 'i, b, small';
   const whats = 'Semantically vague elements i, b, and/or small are used';
   return await doTest(
-    page, withItems, 'textSem', selector, whats, 0, null, getBadWhat.toString()
+    page, catalog, withItems, 'textSem', selector, whats, 0, getBadWhat.toString()
   );
 };

package/testaro/title.js

@@ -1,8 +1,8 @@
 /*
   © 2022–2023 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.
+  Licensed under the MIT License. See LICENSE file at the project root or   https://opensource.org/license/mit/ for details.
 
   SPDX-License-Identifier: MIT
 */
@@ -11,6 +11,8 @@
   title
   This test reports the page title.
 */
+
+// Runs the test and returns the result.
 exports.reporter = async page => {
   const title = await page.title();
   return {

package/testaro/titledEl.js

@@ -1,6 +1,6 @@
 /*
   © 2023–2025 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.
@@ -20,7 +20,7 @@ const {doTest} = require('../procs/testaro');
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (page, withItems) => {
+exports.reporter = async (page, catalog, withItems) => {
   const getBadWhat = element => {
     const elementType = element.tagName.toLowerCase();
     // Return a violation description.
@@ -29,6 +29,6 @@ exports.reporter = async (page, withItems) => {
   const selector = '[title]:not(iframe, link, style)';
   const whats = 'title attributes are used on elements they are likely ineffective on';
   return await doTest(
-    page, withItems, 'titledEl', selector, whats, 0, null, getBadWhat.toString()
+    page, catalog, withItems, 'titledEl', selector, whats, 0, getBadWhat.toString()
   );
 };

package/testaro/zIndex.js

@@ -1,6 +1,6 @@
 /*
   © 2021–2023 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.
@@ -20,7 +20,7 @@ const {doTest} = require('../procs/testaro');
 // FUNCTIONS
 
 // Runs the test and returns the result.
-exports.reporter = async (page, withItems) => {
+exports.reporter = async (page, catalog, withItems) => {
   const getBadWhat = element => {
     // Get whether the element violates the rule.
     const styleDec = window.getComputedStyle(element);
@@ -33,6 +33,6 @@ exports.reporter = async (page, withItems) => {
   };
   const whats = 'Elements have non-default Z indexes';
   return await doTest(
-    page, withItems, 'zIndex', 'body *', whats, 0, null, getBadWhat.toString()
+    page, catalog, withItems, 'zIndex', 'body *', whats, 0, getBadWhat.toString()
   );
 };

package/tests/alfa.js

@@ -1,6 +1,6 @@
 /*
   © 2021–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.
@@ -17,9 +17,7 @@
 
 let alfaRules = require('@siteimprove/alfa-rules').default;
 const {Audit} = require('@siteimprove/alfa-act');
-const {cap, tidy} = require('../procs/job');
-const {getIdentifiers} = require('../procs/standardize');
-const {getNormalizedXPath} = require('../procs/identify');
+const {getNormalizedXPath, getXPathCatalogIndex} = require('../procs/xPath');
 const {Playwright} = require('@siteimprove/alfa-playwright');
 
 // FUNCTIONS
@@ -56,8 +54,6 @@ exports.reporter = async (page, report, actIndex) => {
     };
   }
   try {
-    // Wait for a stable page to make the page and its alfa version consistent.
-    await page.waitForLoadState('networkidle', {timeout: 2000});
     const doc = await page.evaluateHandle('document');
     const alfaPage = await Playwright.toPage(doc);
     // Test the page content with the specified rules.
@@ -65,13 +61,14 @@ exports.reporter = async (page, report, actIndex) => {
     // Get the evaluations.
     const evaluations = Array.from(await audit.evaluate());
     const {nativeResult, standardResult} = result;
+    const {catalog} = report;
     // For each of them:
     for (const index in evaluations) {
       const evaluation = evaluations[index];
       const targetClass = evaluation.target;
       // If it has a non-collection violator:
       if (targetClass && ! targetClass._members) {
-        // Convert the evaluation to an item.
+        // Convert the evaluation to an element-specific item.
         const item = evaluation.toJSON();
         const {diagnostic, expectations, outcome, rule, target} = item;
         // If the outcome of the item is a failure or warning:
@@ -105,44 +102,16 @@ exports.reporter = async (page, report, actIndex) => {
           // If standard results are to be reported:
           if (standard) {
             const {requirements, uri} = rule;
-            // Get properties required for a standard instance.
-            const pathID = getNormalizedXPath(item.path.replace(/\/text\(\).*$/, ''));
-            const {name} = target;
-            let tagName = name?.toUpperCase();
-            if (pathID && tagName?.startsWith('TEXT') || ! tagName) {
-              tagName = pathID.split('/').pop().replace(/\[.+/, '').toUpperCase() || '';
-            }
-            let boxID = '';
-            const targetLoc = page.locator(`xpath=${pathID}`);
-            try {
-              const box = await targetLoc.boundingBox({timeout: 50});
-              if (box) {
-                boxID = Object.values(box).join(':');
-              }
-            }
-            catch(error) {}
-            const text = [];
-            try {
-              const textRaw = await targetLoc.innerText({timeout: 50});
-              const segments = textRaw?.trim().split(/[\t\n]+/).filter(segment => segment.length);
-              if (segments?.length) {
-                if (segments.length > 1) {
-                  text.push(segments[0], segments[segments.length - 1]);
-                }
-                else {
-                  text.push(segments[0]);
-                }
-              }
-            }
-            catch(error) {}
-            // Get rule-specific properties of a standard instance.
+            // Get the rule ID of the item.
             let ruleID = uri.replace(/^.+-/, '');
-            let what = tidy(expectations?.[0]?.[1]?.error?.message || '');
+            // Get the rule description of the item.
+            let what = (expectations?.[0]?.[1]?.error?.message || '').trim().replace(/\s+/g, ' ');
             if (! what) {
               if (requirements && requirements.length && requirements[0].title) {
                 what = requirements[0].title;
               }
             }
+            // Get the ordinal severity of the item.
             let ordinalSeverity = 2;
             // If the outcome is untestability:
             if (outcome === 'cantTell') {
@@ -153,24 +122,29 @@ exports.reporter = async (page, report, actIndex) => {
             }
             // Increment the standard total.
             standardResult.totals[ordinalSeverity]++;
-            // Add a standard instance to the standard result.
-            standardResult.instances.push({
+            // Initialize a proto-instance.
+            const protoInstance = {
               ruleID,
               what,
               ordinalSeverity,
-              count: 1,
-              tagName,
-              id: getIdentifiers(code)[1],
-              location: {
-                doc: 'dom',
-                type: 'xpath',
-                spec: pathID
-              },
-              excerpt: cap(tidy(item.code)),
-              text,
-              boxID,
-              pathID
-            });
+              count: 1
+            };
+            // Get the pathID of the element or, if none, the document pathID.
+            const pathID = getNormalizedXPath(item.path.replace(/\/text\(\).*$/, '')) || '/html';
+            // Use it to get the index of the element in the catalog.
+            const catalogIndex = getXPathCatalogIndex(catalog, pathID);
+            // If the acquisition succeeded:
+            if (catalogIndex) {
+              // Add the catalog index to the proto-instance.
+              protoInstance.catalogIndex = catalogIndex;
+            }
+            // Otherwise, i.e. if the acquisition failed:
+            else {
+              // Add the pathID to the proto-instance.
+              protoInstance.pathID = pathID;
+            }
+            // Add the proto-instance to the instances of the standard result.
+            standardResult.instances.push(protoInstance);
           }
         }
       }