testaro 67.0.0 → 68.0.0

package/tests/wave.js

@@ -1,5 +1,6 @@
 /*
   © 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.
@@ -13,6 +14,10 @@
   specifies a WAVE report type: 1, 2, 3, or 4.
 */
 
+// IMPORTS
+
+const {getXPathCatalogIndex} = require('../procs/xPath');
+
 // CONSTANTS
 
 const https = require('https');
@@ -21,6 +26,7 @@ const https = require('https');
 
 // Conducts and reports the WAVE tests.
 exports.reporter = async (page, report, actIndex) => {
+  // Create a host and a path for a request to the WAVE API.
   const act = report.acts[actIndex];
   const {reportType, url, prescript, postscript, rules} = act;
   const waveKey = process.env.WAVE_KEY;
@@ -41,133 +47,152 @@ exports.reporter = async (page, report, actIndex) => {
   ];
   const query = queryParams.filter(param => param).join('&');
   const path = [wavePath, query].join('?');
-  // Initialize the results.
+  // Initialize the act report.
   const data = {};
-  let result = {};
-  try {
-    result = await new Promise(resolve => {
-      // Get the test results.
-      https.get(
-        {
-          host,
-          path
-        },
-        response => {
-          let rawReport = '';
-          response.on('data', chunk => {
-            rawReport += chunk;
-          });
-          // When they arrive:
-          response.on('end', async () => {
-            let actResult = {};
-            // Delete unnecessary properties.
-            try {
-              actResult = JSON.parse(rawReport);
-              const {categories, statistics} = actResult;
-              delete categories.feature;
-              delete categories.structure;
-              delete categories.aria;
-              // If rules were specified:
+  const result = {
+    nativeResult: {},
+    standardResult: {}
+  };
+  const standard = report.standard !== 'no';
+  // If standard results are to be reported:
+  if (standard) {
+    // Initialize the standard result.
+    result.standardResult = {
+      prevented: false,
+      totals: [0, 0, 0, 0],
+      instances: []
+    };
+  }
+  // Get and process a WAVE API report and return the results.
+  return await new Promise(resolve => https.get(
+    {
+      host,
+      path
+    },
+    response => {
+      let rawReport = '';
+      response.on('data', chunk => {
+        rawReport += chunk;
+      });
+      // When the response arrives:
+      response.on('end', async () => {
+        try {
+          // Parse it as JSON.
+          result.nativeResult = JSON.parse(rawReport);
+        }
+        // If it was not parsable:
+        catch (error) {
+          // Report this.
+          data.prevented = true;
+          data.error = error.message;
+          result.nativeResult = {};
+        }
+        // If the response was parsed:
+        if (! data.prevented) {
+          const {categories} = result.nativeResult;
+          // Delete its unnecessary properties.
+          delete categories.feature;
+          delete categories.structure;
+          delete categories.aria;
+          // For each WAVE rule category:
+          for (const categoryName of ['error', 'contrast', 'alert']) {
+            const category = categories[categoryName];
+            const ordinalSeverity = categoryName === 'alert' ? 0 : 3;
+            // If any violated rules (named items by WAVE) were reported:
+            if (
+              category?.items
+              && Object.keys(category.items).length
+            ) {
+              const {items} = category;
+              // If rules to be tested for were specified:
               if (rules && rules.length) {
-                // For each WAVE rule category:
-                ['error', 'contrast', 'alert'].forEach(categoryName => {
-                  const category = categories[categoryName];
-                  // If any violations were reported:
-                  if (
-                    category
-                    && category.items
-                    && Object.keys(category.items).length
-                  ) {
-                    const {items} = category;
-                    // For each rule violated:
-                    Object.keys(items).forEach(ruleID => {
-                      // If it was not a specified rule:
-                      if (! rules.includes(ruleID)) {
-                        // Decrease the category violation count by the count of its violations.
-                        category.count -= items[ruleID].count;
-                        // Remove its violations from the report.
-                        delete items[ruleID];
-                      }
-                    });
+                // For each rule violated:
+                Object.keys(items).forEach(ruleID => {
+                  // If it was not a specified rule:
+                  if (! rules.includes(ruleID)) {
+                    // Decrease the category violation count by the count of its violations.
+                    category.count -= items[ruleID].count;
+                    // Remove its violations from the native result.
+                    delete items[ruleID];
                   }
                 });
               }
-              // Get the WAVE WCAG documentation.
-              const waveDocResponse = await fetch('https://wave.webaim.org/api/docs');
-              const waveDoc = waveDocResponse.ok ? await waveDocResponse.json() : [];
-              // For each rule category:
-              for (const categoryName of Object.keys(categories)) {
-                const category = categories[categoryName];
-                // If any violations were reported in the category:
-                if (
-                  category
-                  && category.items
-                  && Object.keys(category.items).length
-                ) {
-                  const {items} = category;
-                  // For each rule violated (named item by WAVE):
-                  for (const ruleName of Object.keys(items)) {
-                    const ruleDoc = waveDoc.find((rule => rule.name === ruleName));
-                    const {guidelines} = ruleDoc;
-                    const rule = items[ruleName];
-                    // Add WCAG information to the rule data.
-                    rule.wcag = guidelines || [];
-                    // For each violation:
-                    for (const index in rule.selectors) {
-                      const selector = rule.selectors[index] || '';
-                      let excerpt = '';
-                      // If a selector is provided:
-                      if (selector) {
-                        // Get an excerpt of the element.
-                        excerpt = await page.evaluate(selector => {
-                          const element = document.querySelector(selector);
-                          // If the selector matches an element:
-                          if (element) {
-                            // Get an excerpt of the element.
-                            const rawExcerpt = element.textContent.trim() || element.outerHTML.trim();
-                            const normalizedExcerpt = rawExcerpt.replace(/\s+/g, ' ');
-                            return normalizedExcerpt.slice(0, 300);
-                          }
-                          else {
-                            return '';
-                          }
-                        }, selector);
+              // If standard results are to be reported:
+              if (standard) {
+                const {standardResult} = result;
+                const {totals, instances} = standardResult;
+                // Add the category violation count to the standard-result totals.
+                totals[ordinalSeverity] += category.count;
+                const annotatedItems = await page.evaluate(items => {
+                  const ruleIDs = Object.keys(items);
+                  // For each rule of the category with any violations:
+                  ruleIDs.forEach(ruleID => {
+                    const {selectors} = items[ruleID];
+                    // For each of those violations:
+                    for (const index in selectors) {
+                      const selector = selectors[index];
+                      // Get the violator.
+                      const violator = document.querySelector(selector);
+                      // Concatenate its selector with its XPath in the native result.
+                      selectors[index] = [selector, window.getXPath(violator) ?? ''];
+                    }
+                  });
+                  return items;
+                }, items);
+                const ruleIDs = Object.keys(annotatedItems);
+                // For each rule of the category with any violations:
+                for (const ruleID of ruleIDs) {
+                  const {description, selectors} = annotatedItems[ruleID];
+                  // For each violation of the rule:
+                  for (const violation of selectors) {
+                    // Initialize a standard instance.
+                    const instance = {
+                      ruleID,
+                      what: description,
+                      ordinalSeverity,
+                      count: 1
+                    };
+                    const pathID = violation[1];
+                    // If the path ID of the violator was found:
+                    if (pathID) {
+                      // Get the catalog index of the violator.
+                      const catalogIndex = getXPathCatalogIndex(report.catalog, pathID);
+                      // If the acquisition succeeded:
+                      if (catalogIndex) {
+                        // Add the catalog index to the instance.
+                        instance.catalogIndex = catalogIndex;
+                      }
+                      // Otherwise, i.e. if the acquisition failed:
+                      else {
+                        // Add the path ID to the instance.
+                        instance.pathID = pathID;
                       }
-                      // Convert the violation selector to a selector-excerpt pair.
-                      rule.selectors[index] = [selector, excerpt];
                     }
+                    // Add the instance to the standard result.
+                    instances.push(instance);
                   }
                 }
-              };
-              // Add important data to the result.
-              if (statistics) {
-                data.pageTitle = statistics.pagetitle || '';
-                data.pageURL = statistics.pageurl || '';
-                data.elapsedSeconds = statistics.time || null;
-                data.creditsRemaining = statistics.creditsremaining || null;
-                data.allItemCount = statistics.allitemcount || null;
-                data.totalElements = statistics.totalelements || null;
-                data.waveURL = statistics.waveurl || '';
               }
-              // Return the result.
-              resolve(actResult);
             }
-            catch(error) {
-              data.prevented = true;
-              data.error = error.message;
-              resolve(actResult);
-            };
-          });
+          }
         }
-      );
-    });
-  }
-  catch (error) {
-    data.prevented = true;
-    data.error = error.message;
-  };
-  return {
-    data,
-    result
-  };
+        const {statistics} = result.nativeResult;
+        if (statistics) {
+          // Copy important data from the native result to the result.
+          data.pageTitle = statistics.pagetitle || '';
+          data.pageURL = statistics.pageurl || '';
+          data.elapsedSeconds = statistics.time || null;
+          data.creditsRemaining = statistics.creditsremaining || null;
+          data.allItemCount = statistics.allitemcount || null;
+          data.totalElements = statistics.totalelements || null;
+          data.waveURL = statistics.waveurl || '';
+        }
+        // Return the result.
+        resolve({
+          data,
+          result
+        });
+      });
+    }
+  ));
 };

package/tests/wax.js

@@ -1,6 +1,6 @@
 /*
   © 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.
@@ -15,11 +15,7 @@
 
 // IMPORTS
 
-// Function to add and use unique element IDs.
-const {addTestaroIDs} = require('../procs/testaro');
-// Function to get location data from an element.
-const {getElementData} = require('../procs/getLocatorData');
-// Modules to run WAX.
+const {getAttributeXPath, getXPathCatalogIndex} = require('../procs/xPath');
 const runWax = require('@wally-ax/wax-dev');
 const waxDev = {runWax};
 
@@ -28,12 +24,23 @@ const waxDev = {runWax};
 // Conducts and reports the WAX tests.
 exports.reporter = async (page, report, actIndex) => {
   // Initialize the act report.
-  let data = {};
-  let result = {};
+  const data = {};
+  const result = {
+    nativeResult: {},
+    standardResult: {}
+  };
+  const standard = report.standard !== 'no';
+  // If standard results are to be reported:
+  if (standard) {
+    // Initialize the standard result.
+    result.standardResult = {
+      prevented: false,
+      totals: [0, 0, 0, 0],
+      instances: []
+    };
+  }
   const act = report.acts[actIndex];
   const rules = act.rules || [];
-  // Annotate all elements on the page with unique identifiers.
-  await addTestaroIDs(page);
   const pageCode = await page.content();
   const waxOptions = {
     rules,
@@ -60,15 +67,44 @@ exports.reporter = async (page, report, actIndex) => {
       }
       // Otherwise, i.e. if it is a successful report:
       else {
-        // Add location data to its reported violations.
-        for (const violation of actReport) {
-          const {element} = violation;
-          const elementLocation = await getElementData(page, element);
-          Object.assign(violation, elementLocation);
-        }
-        // Populate the act report.
-        result = {
-          violations: actReport
+        // Populate the native result with it.
+        result.nativeResult = actReport;
+        // If standard results are to be reported:
+        if (standard) {
+          const {standardResult} = result;
+          const {instances, totals} = standardResult;
+          actReport.forEach(violation => {
+            const ordinalSeverity = ['Minor', 'Moderate', '', 'Severe'].indexOf(violation.severity);
+            // Increment the applicable total of the standard result.
+            totals[ordinalSeverity]++;
+            // Initialize a standard instance.
+            const instance = {
+              ruleID: violation.message,
+              what: violation.description || violation.message,
+              ordinalSeverity,
+              count: 1
+            };
+            const {element} = violation;
+            // Get the path ID of the element from its data-xpath attribute.
+            const pathID = getAttributeXPath(element);
+            // If the acquisition succeeded:
+            if (pathID) {
+              // Get the catalog index of the element.
+              const catalogIndex = getXPathCatalogIndex(report.catalog, pathID);
+              // If the acquisition succeeded:
+              if (catalogIndex) {
+                // Add the catalog index to the standard instance.
+                instance.catalogIndex = catalogIndex;
+              }
+              // Otherwise, i.e. if the acquisition failed:
+              else {
+                // Add the path ID to the standard instance.
+                instance.pathID = pathID;
+              }
+              // Add the standard instance to the standard result.
+              instances.push(instance);
+            }
+          });
         }
       }
     }
@@ -93,32 +129,15 @@ exports.reporter = async (page, report, actIndex) => {
         data.error = 'wax failure';
       }
     }
-    try {
-      JSON.stringify(data);
-    }
-    catch(error) {
-      const message = `ERROR: WAX result cannot be made JSON (${error.message.slice(0, 200)})`;
-      data = {
-        prevented: true,
-        error: message
-      };
-    }
-    // Return the results.
-    return {
-      data,
-      result
-    };
   }
   catch(error) {
     const message = `ERROR running WallyAX (${error.message})`;
-    data = {
-      prevented: true,
-      error: message
-    };
+    data.prevented = true;
+    data.error = message;
     console.log(message);
-    return {
-      data,
-      result
-    };
   }
+  return {
+    data,
+    result
+  };
 };

package/procs/getLocatorData.js

@@ -1,192 +0,0 @@
-/*
-  © 2023–2024 CVS Health and/or one of its affiliates. All rights reserved.
-
-  Licensed under the MIT License. See LICENSE file at the project root or
-  https://opensource.org/license/mit/ for details.
-
-  SPDX-License-Identifier: MIT
-*/
-
-/*
-  getLocatorData
-  Returns data about the element identified by a locator.
-*/
-exports.getLocatorData = async loc => {
-  const locCount = await loc.count();
-  // If the locator identifies exactly 1 element:
-  if (locCount === 1) {
-    // Get the facts obtainable from the browser.
-    const data = await loc.evaluate(element => {
-      // Tag name.
-      const tagName = element.tagName;
-      // ID.
-      const id = element.id || '';
-      // Texts.
-      const {textContent} = element;
-      const alts = Array.from(element.querySelectorAll('img[alt]:not([alt=""])'));
-      const altTexts = alts.map(alt => alt.getAttribute('alt'));
-      const altsText = altTexts.join(' ');
-      const ariaLabelText = element.ariaLabel || '';
-      const refLabelID = element.getAttribute('aria-labelledby');
-      const refLabel = refLabelID ? document.getElementById(refLabelID) : '';
-      const refLabelText = refLabel ? refLabel.textContent : '';
-      let labelsText = '';
-      if (tagName === 'INPUT') {
-        const labels = element.labels || [];
-        const labelTexts = [];
-        labels.forEach(label => {
-          labelTexts.push(label.textContent);
-        });
-        labelsText = labelTexts.join(' ');
-      }
-      let text = [textContent, altsText, ariaLabelText, refLabelText, labelsText]
-      .join(' ')
-      .replace(/\s+/g, ' ')
-      .trim();
-      if (! text) {
-        text = element.outerHTML.replace(/\s+/g, ' ').trim();
-      }
-      if (/^<[^<>]+>$/.test(text)) {
-        text = element.parentElement.outerHTML.replace(/\s+/g, ' ').trim();
-      }
-      // Location.
-      let location = {
-        doc: 'dom',
-        type: 'box',
-        spec: {}
-      };
-      if (id) {
-        location.type = 'selector';
-        location.spec = `#${id}`;
-      }
-      // Return the data.
-      return {
-        tagName,
-        id,
-        location,
-        excerpt: text
-      };
-    });
-    // If an ID-based selector could not be defined:
-    if (data.location.type === 'box') {
-      // Define a bounding-box-based location.
-      const rawSpec = await loc.boundingBox();
-      // If there is a bounding box (i.e. the element is visible):
-      if (rawSpec) {
-        // Populate the location.
-        Object.keys(rawSpec).forEach(specName => {
-          data.location.spec[specName] = Math.round(rawSpec[specName]);
-        });
-      }
-      // Otherwise, i.e. if there is no bounding box:
-      else {
-        // Empty the location.
-        data.location.doc = '';
-        data.location.type = '';
-        data.location.spec = '';
-      }
-    }
-    // If the text is long:
-    if (data.excerpt.length > 400) {
-      // Truncate its middle.
-      data.excerpt = `${data.excerpt.slice(0, 200)} … ${data.excerpt.slice(-200)}`;
-    }
-    // Return the data.
-    return data;
-  }
-  // Otherwise, i.e. if it does not identify exactly 1 element:
-  else {
-    // Report this.
-    console.log(`ERROR: Locator count to get data from is ${locCount} instead of 1`);
-    return null;
-  }
-};
-// Returns properties of an element with an excerpt when Testaro identifiers have been added.
-exports.getElementData = async (page, excerpt) => {
-  // Initialize the properties.
-  let data = {
-    tagName: '',
-    id: '',
-    text: '',
-    notInDOM: true,
-    boxID: '',
-    pathID: '',
-    originalExcerpt: excerpt,
-  };
-  let elementProperties = {};
-  const testaroIDArray = excerpt.match(/data-testaro-id="(\d+)#([^"]*)"/);
-  // If the excerpt contains a Testaro identifier:
-  if (testaroIDArray) {
-    // Remove the identifier.
-    originalExcerpt = excerpt.replace(/ data-testaro-id="\d+#[^" ]+"?/, '');
-    elementProperties = await page.evaluate(testaroIDArray => {
-      let tagName = '';
-      let id = '';
-      const text = [];
-      let notInDOM = false;
-      let boxID = '';
-      let pathID = '';
-      const testaroID = `${testaroIDArray[1]}#${testaroIDArray[2]}`;
-      const element = document.querySelector(`[data-testaro-id="${testaroID}"]`);
-      // If any element has the identifier:
-      if (element) {
-        // Get properties of the element.
-        ({tagName, id} = element);
-        const segments = element
-          .innerText
-          ?.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]);
-          }
-        }
-        const boundingBox = element.getBoundingClientRect() ?? {};
-        const box = {};
-        if (boundingBox.x) {
-          ['x', 'y', 'width', 'height'].forEach(coordinate => {
-            box[coordinate] = Math.round(boundingBox[coordinate]);
-          });
-        }
-        if (typeof box.x === 'number') {
-          boxID = Object.values(box).join(':');
-        }
-        // Get a path ID from the identifier or, if necessary, the element.
-        pathID = testaroIDArray[2];
-        if (! pathID) {
-          pathID = window.getXPath(element);
-        }
-      }
-      // Otherwise, i.e. if no element has the identifier:
-      else {
-        // Report this.
-        notInDOM = true;
-      }
-      // Report the properties.
-      return {
-        tagName,
-        id,
-        text,
-        notInDOM,
-        boxID,
-        pathID
-      };
-    }, testaroIDArray);
-    // Populate the data with any properties obtained from the element.
-    Object.assign(data, elementProperties);
-  }
-  // Otherwise, i.e. if the excerpt contains no Testaro identifier:
-  else {
-    // Get properties of the element that are gettable from the excerpt.
-    const tagNameArray = excerpt.match(/<([-a-z]+)/);
-    data.tagName = tagNameArray?.[1] ?? '';
-    const idArray = excerpt.match(/ id="([^"]*)"/);
-    data.id = idArray?.[1] ?? '';
-  }
-  // Return the properties.
-  return data;
-};