testaro 78.0.8 → 78.4.0

package/testaro/buttonMenu.ts

@@ -0,0 +1,391 @@
+/*
+  © 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
+
+import type {Locator, Page} from 'playwright';
+import {getXPathCatalogIndex} from '../procs/xPath';
+import type {Report, StandardInstance} from '../types';
+
+// TYPES
+
+// Location of an element, as recorded in locator data.
+interface LocatorLocation {
+  doc: string;
+  type: string;
+  spec: string | Record<string, number>;
+}
+// Data on the element referenced by a locator.
+interface LocatorData {
+  tagName: string;
+  id: string;
+  location: LocatorLocation;
+  excerpt: string;
+}
+
+/*
+  buttonMenu
+  This test reports nonstandard navigation among menu items of button-controlled menus. Standards are based on https://www.w3.org/TR/wai-aria-practices-1.1/#menu. The trialKeys argument is an array of strings, each of which may be 'Home', 'End', '+', or '-'. The '+' string represents the ArrowDown or ArrowRight key, and the '-' string represents the ArrowUp or ArrowLeft key, depending on the orientation of the current menu. When the trialKeys argument is missing or is an empty array, 12 keys are selected at random.
+  Compiled to buttonMenu.js by tsc (issue #73); edit this file, not the emitted one.
+*/
+
+// ########## FUNCTIONS
+
+// Returns data about the element referenced by a locator.
+const getLocatorData = async (loc: Locator): Promise<LocatorData | null> => {
+  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): LocatorData => {
+      // 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 as HTMLInputElement).labels || [];
+        const labelTexts: (string | null)[] = [];
+        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: LocatorLocation = {
+        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 as Record<string, number>)[specName] = Math.round(
+            rawSpec[specName as keyof typeof rawSpec]
+          );
+        });
+      }
+      // 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 an adjacent index, with wrapping.
+const getAdjacentIndexWithWrap = (groupSize: number, startIndex: number, increment: number) => {
+  let newIndex = startIndex + increment;
+  if (newIndex < 0) {
+    newIndex = groupSize - 1;
+  }
+  else if (newIndex > groupSize - 1) {
+    newIndex = 0;
+  }
+  return newIndex;
+};
+// Returns whether a key created the expected effective focus.
+const focusSuccess = async (
+  miLocsDir: Locator[], priorIndex: number, key: string, isPseudo: boolean
+) => {
+  // Initialize the result.
+  const result: {isOK: boolean; newFocIndex: number | null} = {
+    isOK: false,
+    newFocIndex: null
+  };
+  // For each of the menu items directly descending from the menu:
+  for (const miLocDir of miLocsDir) {
+    // Get whether it is effectively focused.
+    const hasFocus = await miLocDir.evaluate((el, isPseudo) => {
+      if (isPseudo) {
+        // The page has an active element whenever this runs; verbatim from the original.
+        const effectiveID = document.activeElement!.getAttribute('aria-activeDescendant');
+        if (effectiveID) {
+          const effectiveEl = document.getElementById(effectiveID);
+          return effectiveEl === el;
+        }
+        else {
+          return false;
+        }
+      }
+      else {
+        return document.activeElement === el;
+      }
+    }, isPseudo);
+    // If it is:
+    if (hasFocus) {
+      // Get whether the effective focus is as expected and update the result.
+      const miFocIndex = miLocsDir.indexOf(miLocDir);
+      const miCount = miLocsDir.length;
+      if (key === 'Home' && miFocIndex === 0) {
+        result.isOK = true;
+        result.newFocIndex = 0;
+      }
+      else if (key === 'End' && miFocIndex === miCount - 1) {
+        result.isOK = true;
+        result.newFocIndex = miCount - 1;
+      }
+      else if (['ArrowLeft', 'ArrowUp'].includes(key)) {
+        const expectedIndex = getAdjacentIndexWithWrap(miCount, priorIndex, -1);
+        if (miFocIndex === expectedIndex) {
+          result.isOK = true;
+          result.newFocIndex = expectedIndex;
+        }
+      }
+      else if (['ArrowRight', 'ArrowDown'].includes(key)) {
+        const expectedIndex = getAdjacentIndexWithWrap(miCount, priorIndex, 1);
+        if (miFocIndex === expectedIndex) {
+          result.isOK = true;
+          result.newFocIndex = expectedIndex;
+        }
+      }
+      break;
+    }
+  }
+  // Return the result.
+  return result;
+};
+// Performs the test and reports the result.
+export const reporter = async (
+  page: Page, report: Report, _0: unknown, withItems: boolean, trialKeySpecs: string[] = []
+) => {
+  // Initialize the result.
+  const data: {trialKeys?: string[]} = {};
+  const totals = [0, 0, 0, 0];
+  const standardInstances: StandardInstance[] = [];
+  // Get locators for all menu buttons.
+  const mbLocAll = page.locator(
+    'button[aria-controls][aria-expanded][aria-haspopup=true], button[aria-controls][aria-expanded][aria-haspopup=menu]'
+  );
+  const mbLocsAll = await mbLocAll.all();
+  // For each menu button:
+  for (const mbLoc of mbLocsAll) {
+    // Get a locator for its menu.
+    const menuID = await mbLoc.getAttribute('aria-controls');
+    const menuLoc = page.locator(`[id=${menuID}][role=menu], [id=${menuID}][role=menubar]`);
+    // If the button controls exactly 1 menu:
+    if (menuLoc && await menuLoc.count() === 1) {
+      // Get data on the menu.
+      const elData = await getLocatorData(menuLoc);
+      // If data were obtained:
+      if (elData) {
+        // Get the orientation and focus-management type of the menu.
+        const extraData = await menuLoc.evaluate(element => {
+          const extraData: {orientation?: string | null; isPseudo?: boolean} = {};
+          let orientation = element.getAttribute('aria-orientation');
+          if (! orientation) {
+            const role = element.getAttribute('role');
+            if (role === 'menubar') {
+              orientation = 'horizontal';
+            }
+            else if (role === 'menu') {
+              orientation = 'vertical';
+            }
+            else {
+              orientation = null;
+            }
+          }
+          extraData.orientation = orientation;
+          const isPseudo = !! element.getAttribute('aria-activedescendant');
+          extraData.isPseudo = isPseudo;
+          return extraData;
+        });
+        // If they were obtained:
+        if (extraData) {
+          // Get locators for its descendant non-menu menu items.
+          const miLocAll = menuLoc.locator('[role=menuitem]:not([role=menu], [role=menubar])');
+          // Get which of them are direct descendants.
+          const areDirect = await miLocAll.evaluateAll((els, menuID) => {
+            return els.map(el => {
+              // Menu items are inside a menu by definition; verbatim from the original.
+              const itsMenu = el.closest('[role=menu], [role=menubar]')!;
+              return itsMenu.id && itsMenu.id === menuID;
+            });
+          }, menuID);
+          const miLocsAll = await miLocAll.all();
+          const miLocsDir = miLocsAll.filter((loc, index) => areDirect[index]);
+          // If there are at least 2 of them:
+          if (miLocsDir.length > 1) {
+            // Ensure that the menu is collapsed.
+            await menuLoc.evaluate(element => {
+              // The boolean is coerced to 'false' at runtime; verbatim from the original.
+              element.setAttribute('aria-expanded', false as unknown as string);
+            });
+            // Focus the menu button and press the key that opens its menu from the top.
+            await mbLoc.press(extraData.orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown');
+            // If trial keys have been specified:
+            const trialKeys: string[] = [];
+            if (trialKeySpecs.length) {
+              // Implement them.
+              trialKeySpecs.forEach(spec => {
+                if (['Home', 'End'].includes(spec)) {
+                  trialKeys.push(spec);
+                }
+                else if (spec === '-') {
+                  trialKeys.push(extraData.orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp');
+                }
+                else if (spec === '+') {
+                  trialKeys.push(
+                    extraData.orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown'
+                  );
+                }
+              });
+            }
+            // Otherwise, i.e. if trial keys have not been specified:
+            else {
+              // Randomly draw 12 keys from Home, End, and the applicable arrow keys.
+              const keys = ['Home', 'End'];
+              if (extraData.orientation === 'horizontal') {
+                keys.push('ArrowLeft', 'ArrowRight');
+              }
+              else {
+                keys.push('ArrowUp', 'ArrowDown');
+              }
+              let trialKeyCount = 0;
+              while (trialKeyCount++ < 12) {
+                trialKeys.push(keys[Math.floor(4 * Math.random())]);
+              }
+            }
+            // Add the list of trial keys to the result.
+            data.trialKeys = trialKeys;
+            let focIndex = 0;
+            // For each key in the trial:
+            for (const key of trialKeys) {
+              // Press it.
+              await page.keyboard.press(key);
+              // Get whether the expected focus occurred.
+              const focData = await focusSuccess(miLocsDir, focIndex, key, extraData.isPseudo!);
+              // If so:
+              if (focData.isOK) {
+                // Update the index of the effective focus.
+                focIndex = focData.newFocIndex as number;
+              }
+              // Otherwise, i.e. if the expected focus did not occur:
+              else {
+                // Add to the totals.
+                totals[2]++;
+                // If itemization is required:
+                if (withItems) {
+                  // Get the XPath of the menu button.
+                  const mbXPath = await mbLoc.evaluate(element => window.getXPath(element));
+                  // Add an instance to the standard instances.
+                  standardInstances.push({
+                    ruleID: 'buttonMenu',
+                    what: `Menu responds nonstandardly to the ${key} key`,
+                    ordinalSeverity: 2,
+                    count: 1,
+                    catalogIndex: getXPathCatalogIndex(report, mbXPath as string)
+                  });
+                }
+                // Stop testing the menu button.
+                break;
+              }
+            }
+          }
+        }
+        // Otherwise, i.e. if the orientation and focus-management type were not obtained:
+        else {
+          // Report this.
+          console.log('ERROR: Menu orientation and focus-management type not obtained');
+        }
+      }
+      // Otherwise, i.e. if the data were not obtained:
+      else {
+        // Report this.
+        console.log('ERROR: Menu data not obtained');
+      }
+    }
+    // Otherwise, i.e. if it does not control exactly 1 menu:
+    else {
+      // Add to the totals.
+      totals[2]++;
+      // If itemization is required:
+      if (withItems) {
+        // Get the XPath of the menu button.
+        const mbXPath = await mbLoc.evaluate(element => window.getXPath(element));
+        // Add an instance to the standard instances.
+        standardInstances.push({
+          ruleID: 'buttonMenu',
+          what: 'Menu button does not control exactly 1 menu',
+          ordinalSeverity: 2,
+          count: 1,
+          catalogIndex: getXPathCatalogIndex(report, mbXPath as string)
+        });
+      }
+    }
+  }
+  // If itemization is not required and there are any instances:
+  if (! withItems && totals[2]) {
+    // Add a summary instance to the result.
+    standardInstances.push({
+      ruleID: 'buttonMenu',
+      what: 'Menu buttons and menus behave nonstandardly',
+      count: totals[2],
+      ordinalSeverity: 2
+    });
+  }
+  return {
+    data,
+    totals,
+    standardInstances
+  };
+};

package/testaro/captionLoc.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from 'playwright';
+import type { Report } from '../types';
+export declare const reporter: (page: Page, report: Report, _: unknown, withItems: boolean) => Promise<import("../procs/testaro").RuleResult>;

package/testaro/captionLoc.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
   © 2025 CVS Health and/or one of its affiliates. All rights reserved.
   © 2025 Juan S. Casado.
@@ -9,29 +10,25 @@
 
   SPDX-License-Identifier: MIT
 */
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reporter = void 0;
+const testaro_1 = require("../procs/testaro");
 /*
   captionLoc
   This test reports caption elements that are not the first children of table elements.
+  Compiled to captionLoc.js by tsc (issue #73); edit this file, not the emitted one.
 */
-
-// IMPORTS
-
-const {doTest} = require('../procs/testaro');
-
 // FUNCTIONS
-
-exports.reporter = async (page, report, _, withItems) => {
-  const getBadWhat = element => {
-    const parent = element.parentElement;
-    // If the element is not the first child of a table element:
-    if (! parent || parent.tagName !== 'TABLE' || parent.firstElementChild !== element) {
-      // Return a violation description.
-      return 'caption element is not the first child of a table element';
-    }
-  };
-  const whats = 'caption elements are not the first children of table elements';
-  return await doTest(
-    page, report, withItems, 'captionLoc', 'body caption', whats, 3, getBadWhat.toString()
-  );
+const reporter = async (page, report, _, withItems) => {
+    const getBadWhat = element => {
+        const parent = element.parentElement;
+        // If the element is not the first child of a table element:
+        if (!parent || parent.tagName !== 'TABLE' || parent.firstElementChild !== element) {
+            // Return a violation description.
+            return 'caption element is not the first child of a table element';
+        }
+    };
+    const whats = 'caption elements are not the first children of table elements';
+    return await (0, testaro_1.doTest)(page, report, withItems, 'captionLoc', 'body caption', whats, 3, getBadWhat.toString());
 };
+exports.reporter = reporter;

package/testaro/captionLoc.ts

@@ -0,0 +1,40 @@
+/*
+  © 2025 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2025 Juan S. Casado.
+  © 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
+
+import type {Page} from 'playwright';
+import {doTest} from '../procs/testaro';
+import type {GetBadWhat, Report} from '../types';
+
+/*
+  captionLoc
+  This test reports caption elements that are not the first children of table elements.
+  Compiled to captionLoc.js by tsc (issue #73); edit this file, not the emitted one.
+*/
+
+// FUNCTIONS
+
+export const reporter = async (page: Page, report: Report, _: unknown, withItems: boolean) => {
+  const getBadWhat: GetBadWhat = element => {
+    const parent = element.parentElement;
+    // If the element is not the first child of a table element:
+    if (! parent || parent.tagName !== 'TABLE' || parent.firstElementChild !== element) {
+      // Return a violation description.
+      return 'caption element is not the first child of a table element';
+    }
+  };
+  const whats = 'caption elements are not the first children of table elements';
+  return await doTest(
+    page, report, withItems, 'captionLoc', 'body caption', whats, 3, getBadWhat.toString()
+  );
+};

package/testaro/datalistRef.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from 'playwright';
+import type { Report } from '../types';
+export declare const reporter: (page: Page, report: Report, _: unknown, withItems: boolean) => Promise<import("../procs/testaro").RuleResult>;

package/testaro/datalistRef.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
   © 2025 CVS Health and/or one of its affiliates. All rights reserved.
   © 2025 Juan S. Casado.
@@ -8,45 +9,41 @@
 
   SPDX-License-Identifier: MIT
 */
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reporter = void 0;
+const testaro_1 = require("../procs/testaro");
 /*
   datalistRef
   This test reports inputs whose list attributes reference missing or ambiguous datalists.
+  Compiled to datalistRef.js by tsc (issue #73); edit this file, not the emitted one.
 */
-
-// IMPORTS
-
-const {doTest} = require('../procs/testaro');
-
 // FUNCTIONS
-
-exports.reporter = async (page, report, _, withItems) => {
-  const getBadWhat = element => {
-    // Get the ID of the datalist element referenced by the list attribute of the element.
-    const listID = element.getAttribute('list');
-    // If the element has a list attribute with a non-empty value:
-    if (listID) {
-      // Get the element it references.
-      const listElement = document.getElementById(listID);
-      // If no such element exists:
-      if (! listElement) {
-        // Return a violation description.
-        return 'input element list attribute references a missing element';
-      }
-      // Otherwise, if the element it references is not a datalist:
-      if (listElement.tagName.toLowerCase() !== 'datalist') {
-        // Return a violation description.
-        return 'input element list attribute references a non-datalist element';
-      }
-    }
-    // Otherwise, i.e. if it has no list attribute with a non-empty value:
-    else {
-      // Return a violation description.
-      return 'input element list attribute is empty';
-    }
-  };
-  const whats = 'list attributes of input elements are empty or IDs of no or non-datalist elements';
-  return await doTest(
-    page, report, withItems, 'datalistRef', 'body input[list]', whats, 3, getBadWhat.toString()
-  );
+const reporter = async (page, report, _, withItems) => {
+    const getBadWhat = element => {
+        // Get the ID of the datalist element referenced by the list attribute of the element.
+        const listID = element.getAttribute('list');
+        // If the element has a list attribute with a non-empty value:
+        if (listID) {
+            // Get the element it references.
+            const listElement = document.getElementById(listID);
+            // If no such element exists:
+            if (!listElement) {
+                // Return a violation description.
+                return 'input element list attribute references a missing element';
+            }
+            // Otherwise, if the element it references is not a datalist:
+            if (listElement.tagName.toLowerCase() !== 'datalist') {
+                // Return a violation description.
+                return 'input element list attribute references a non-datalist element';
+            }
+        }
+        // Otherwise, i.e. if it has no list attribute with a non-empty value:
+        else {
+            // Return a violation description.
+            return 'input element list attribute is empty';
+        }
+    };
+    const whats = 'list attributes of input elements are empty or IDs of no or non-datalist elements';
+    return await (0, testaro_1.doTest)(page, report, withItems, 'datalistRef', 'body input[list]', whats, 3, getBadWhat.toString());
 };
+exports.reporter = reporter;

package/testaro/datalistRef.ts

@@ -0,0 +1,55 @@
+/*
+  © 2025 CVS Health and/or one of its affiliates. All rights reserved.
+  © 2025 Juan S. Casado.
+  © 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
+
+import type {Page} from 'playwright';
+import {doTest} from '../procs/testaro';
+import type {GetBadWhat, Report} from '../types';
+
+/*
+  datalistRef
+  This test reports inputs whose list attributes reference missing or ambiguous datalists.
+  Compiled to datalistRef.js by tsc (issue #73); edit this file, not the emitted one.
+*/
+
+// FUNCTIONS
+
+export const reporter = async (page: Page, report: Report, _: unknown, withItems: boolean) => {
+  const getBadWhat: GetBadWhat = element => {
+    // Get the ID of the datalist element referenced by the list attribute of the element.
+    const listID = element.getAttribute('list');
+    // If the element has a list attribute with a non-empty value:
+    if (listID) {
+      // Get the element it references.
+      const listElement = document.getElementById(listID);
+      // If no such element exists:
+      if (! listElement) {
+        // Return a violation description.
+        return 'input element list attribute references a missing element';
+      }
+      // Otherwise, if the element it references is not a datalist:
+      if (listElement.tagName.toLowerCase() !== 'datalist') {
+        // Return a violation description.
+        return 'input element list attribute references a non-datalist element';
+      }
+    }
+    // Otherwise, i.e. if it has no list attribute with a non-empty value:
+    else {
+      // Return a violation description.
+      return 'input element list attribute is empty';
+    }
+  };
+  const whats = 'list attributes of input elements are empty or IDs of no or non-datalist elements';
+  return await doTest(
+    page, report, withItems, 'datalistRef', 'body input[list]', whats, 3, getBadWhat.toString()
+  );
+};

package/testaro/distortion.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from 'playwright';
+import type { Report } from '../types';
+export declare const reporter: (page: Page, report: Report, _: unknown, withItems: boolean) => Promise<import("../procs/testaro").RuleResult>;