testaro 78.0.6 → 78.4.0

package/testaro/hovInd.js

@@ -1,144 +1,178 @@
+"use strict";
 /*
   © 2023–2025 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
 */
-
-/*
-  hovInd
-  This test reports confusing hover indication.
-*/
-
-// IMPORTS
-
-const {doTest} = require('../procs/testaro');
-
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reporter = void 0;
+const playwright = __importStar(require("playwright"));
+const testaro_1 = require("../procs/testaro");
+const config_1 = require("../procs/config");
+// CONSTANTS
+// Standard non-default hover cursors of inputs, by type.
+const standardInputCursors = {
+    email: 'text',
+    image: 'pointer',
+    number: 'text',
+    password: 'text',
+    search: 'text',
+    tel: 'text',
+    text: 'text',
+    url: 'text'
+};
+// Style properties compared between states.
+const comparedStyles = ['backgroundColor', 'border', 'color', 'outline'];
+// Maximum count of triggers inspected, because each inspection performs 3 browser interactions.
+const MAX_TRIGGERS = 60;
 // FUNCTIONS
-
+// Returns the hover-related style properties of a trigger in its current state.
+const getStyles = async (loc) => await loc.evaluate(element => {
+    const { cursor, borderColor, borderStyle, borderWidth, outlineColor, outlineStyle, outlineWidth, outlineOffset, color, backgroundColor } = window.getComputedStyle(element);
+    return {
+        tagName: element.tagName,
+        inputType: element.tagName === 'INPUT' ? element.getAttribute('type') || 'text' : null,
+        // Ignore any custom cursor images and keep only the fallback keyword.
+        cursor: cursor.replace(/^.+, */, ''),
+        border: `${borderColor} ${borderStyle} ${borderWidth}`,
+        outline: `${outlineColor} ${outlineStyle} ${outlineWidth} ${outlineOffset}`,
+        color,
+        backgroundColor
+    };
+});
+// Returns whether the hover cursor of a trigger is standard. A computed value of auto is standard, because browsers render it as the type-appropriate cursor.
+const cursorIsStandard = (styles) => {
+    const { tagName, inputType, cursor } = styles;
+    if (tagName === 'A') {
+        return ['pointer', 'auto'].includes(cursor);
+    }
+    if (tagName === 'INPUT') {
+        return [standardInputCursors[inputType || 'text'], 'default', 'auto'].includes(cursor);
+    }
+    if (tagName === 'BUTTON') {
+        return ['default', 'auto'].includes(cursor);
+    }
+    // Any other trigger is one with a hover listener, and its cursor is assumed standard.
+    return true;
+};
+// Returns whether the compared styles of two states are identical.
+const areAlike = (styles0, styles1) => comparedStyles
+    .every(style => styles0[style] === styles1[style]);
 // Runs the test and returns the result.
-exports.reporter = async (page, report, _, withItems) => {
-  const getBadWhat = element => {
-    const violationTypes = [];
-    const isVisible = element.checkVisibility({
-      contentVisibilityAuto: true,
-      opacityProperty: true,
-      visibilityProperty: true
-    });
-    // If the element is visible:
-    if (isVisible) {
-      // Get its live style declaration.
-      const styleDec = window.getComputedStyle(element);
-      // FUNCTION DEFINITIONS START
-      // Returns hover-related style data on a trigger.
-      const getStyleData = () => {
-        const {
-          cursor,
-          borderColor,
-          borderStyle,
-          borderWidth,
-          outlineColor,
-          outlineStyle,
-          outlineWidth,
-          outlineOffset,
-          color,
-          backgroundColor
-        } = styleDec;
-        return {
-          tagName: element.tagName,
-          inputType: element.tagName === 'INPUT' ? element.getAttribute('type') || 'text' : null,
-          cursor: cursor.replace(/^.+, */, ''),
-          border: `${borderColor} ${borderStyle} ${borderWidth}`,
-          outline: `${outlineColor} ${outlineStyle} ${outlineWidth} ${outlineOffset}`,
-          color,
-          backgroundColor
-        };
-      };
-      // Returns whether the cursor is bad when the element is hovered over.
-      const cursorIsBad = hoverCursor => {
-        const {tagName, type} = element;
-        if (tagName === 'A' || tagName === 'INPUT' && type === 'image') {
-          return hoverCursor !== 'pointer';
-        }
-        if (tagName === 'INPUT') {
-          if (['button', 'radio', 'reset', 'submit'].some(typeName => type === typeName)) {
-            return hoverCursor !== 'default';
-          }
-          return hoverCursor !== 'text';
-        }
-        return ! ['auto', 'default'].includes(hoverCursor);
-      };
-      // Returns whether two hover styles are effectively identical.
-      const areAlike = (styles0, styles1) => {
-        // Return whether they are effectively identical.
-        const areAlike = ['cursor', 'backgroundColor', 'border', 'color', 'outline']
-        .every(style => styles1[style] === styles0[style]);
-        return areAlike;
-      };
-      // FUNCTION DEFINITIONS END
-      // Get its style data when neither focused nor hovered over.
-      const defaultStyleData = getStyleData();
-      // Correct the cursor value.
-      defaultStyleData.cursor = 'default';
-      // Get its style data when only focused.
-      element.focus();
-      const focusStyleData = getStyleData();
-      // Correct the cursor value.
-      focusStyleData.cursor = 'default';
-      // Get its style data when only hovered over.
-      element.blur();
-      element.dispatchEvent(new MouseEvent('mouseenter'));
-      const hoverStyleData = getStyleData();
-      const data = {};
-      // If the cursor is confusing when the element is only hovered over:
-      if (cursorIsBad(hoverStyleData.cursor)) {
-        // Add this to the violation types.
-        violationTypes.push(
-          `nonstandard mouse cursor (${hoverStyleData.cursor}) when hovered over`
-        );
-      }
-      // If the neutral and hover styles are indistinguishable:
-      if (areAlike(defaultStyleData, hoverStyleData)) {
-        // Add this to the violation types.
-        violationTypes.push('normal and hover styles are indistinguishable');
-        // Add the details to the data.
-        data.n_h = {
-          neutral: defaultStyleData,
-          hover: hoverStyleData
-        };
-      }
-      // If the focus and hoverstyles are indistinguishable:
-      if (areAlike(focusStyleData, hoverStyleData)) {
-        // Add this to the violation types.
-        violationTypes.push('focus and hover styles are indistinguishable');
-        // Add the details to the data.
-        data.f_h = {
-          focus: focusStyleData,
-          hover: hoverStyleData
-        };
-      }
-      // If any violations occurred:
-      if (violationTypes.length) {
-        const description = `Element styles do not clearly indicate hovering: ${violationTypes.join('; ')}`;
-        // If there are additional data:
-        if (Object.keys(data).length) {
-          // Return the violation description and data.
-          return {
-            description,
-            data
-          };
+const reporter = async (page, report, _, withItems) => {
+    // Get locators for the visible triggers.
+    const selector = ['a', 'button', 'input', '[onmouseenter]', '[onmouseover]']
+        .map(tagSelector => `body ${tagSelector}:visible`)
+        .join(', ');
+    const allLocs = await page.locator(selector).all();
+    // Inspect at most MAX_TRIGGERS of them, evenly spaced through the page.
+    const step = Math.max(1, Math.ceil(allLocs.length / MAX_TRIGGERS));
+    const locs = allLocs.filter((loc, index) => index % step === 0).slice(0, MAX_TRIGGERS);
+    const data = {
+        triggerCount: allLocs.length,
+        inspectedCount: locs.length
+    };
+    // Initialize the violations, by severity.
+    const cursorViolations = [];
+    const styleViolations = [];
+    const timeout = (0, config_1.applyMultiplier)(500);
+    // For each trigger:
+    for (const loc of locs) {
+        try {
+            // Move the mouse away from any previously hovered trigger.
+            await page.mouse.move(0, 0);
+            // Get its styles when neither focused nor hovered over.
+            const neutralStyles = await getStyles(loc);
+            // Get its styles when only focused.
+            await loc.focus({ timeout });
+            const focusStyles = await getStyles(loc);
+            await loc.blur({ timeout });
+            // Get its styles when only hovered over.
+            await loc.hover({ timeout });
+            const hoverStyles = await getStyles(loc);
+            await page.mouse.move(0, 0);
+            // If its hover cursor is nonstandard:
+            if (!cursorIsStandard(hoverStyles)) {
+                // Add a violation.
+                cursorViolations.push({
+                    loc,
+                    what: `Element has a nonstandard hover cursor (${hoverStyles.cursor})`
+                });
+            }
+            // If it is a button and its hover styles are indistinguishable from its neutral styles:
+            if (hoverStyles.tagName === 'BUTTON' && areAlike(neutralStyles, hoverStyles)) {
+                // Add a violation.
+                styleViolations.push({
+                    loc,
+                    what: 'Element border, outline, color, and background color do not change when hovered over'
+                });
+            }
+            // Otherwise, if its hover styles differ from its neutral styles but are indistinguishable from its focus styles:
+            else if (!areAlike(neutralStyles, hoverStyles) && areAlike(focusStyles, hoverStyles)) {
+                // Add a violation.
+                styleViolations.push({
+                    loc,
+                    what: 'Element border, outline, color, and background color are alike on hover and focus'
+                });
+            }
         }
-        // Otherwise, i.e. if there are no additional data:
-        else {
-          // Return the violation description.
-          return description;
+        // If focusing, blurring, or hovering throws an error:
+        catch (error) {
+            // If the error is a timeout, skip the trigger.
+            if (error instanceof playwright.errors.TimeoutError) {
+                continue;
+            }
+            // Otherwise, report this and quit.
+            data.prevented = true;
+            data.error = `ERROR inspecting a trigger (${error.message.slice(0, 200)})`;
+            break;
         }
-      }
     }
-  };
-  const selector = 'body a, body button, body input, body [onmouseenter], body [onmouseover]';
-  const whats = 'elements have confusing hover indicators';
-  return await doTest(page, report, withItems, 'hovInd', selector, whats, 1, getBadWhat.toString());
+    // Get results for the two severities and merge them.
+    const cursorResult = await (0, testaro_1.getBasicResult)(report, withItems, 'hovInd', 2, 'Elements have nonstandard hover cursors', data, cursorViolations);
+    const styleResult = await (0, testaro_1.getBasicResult)(report, withItems, 'hovInd', 1, 'Element styles do not distinguish hovering from the neutral or focus state', data, styleViolations);
+    const totals = cursorResult.totals.map((total, index) => total + styleResult.totals[index]);
+    return {
+        data,
+        totals,
+        standardInstances: [...cursorResult.standardInstances, ...styleResult.standardInstances]
+    };
 };
+exports.reporter = reporter;

package/testaro/hovInd.ts

@@ -0,0 +1,199 @@
+/*
+  © 2023–2025 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 * as playwright from 'playwright';
+import {getBasicResult} from '../procs/testaro';
+import {applyMultiplier} from '../procs/config';
+import type {Report, SeverityTotals} from '../types';
+
+/*
+  hovInd
+  This test reports confusing hover indication. The triggers are visible links, buttons, inputs, and elements with hover listeners. Each trigger is inspected in three states: neutral, focused, and hovered over. Hovering is performed by Playwright, because CSS :hover styles cannot be activated by synthetic mouse events dispatched inside the page. A trigger violates the rule if its hover cursor is nonstandard for its type (severity 2), if it is a button whose border, outline, color, and background color do not change when it is hovered over (severity 1), or if those styles change on hover but are indistinguishable from its focus styles (severity 1). A trigger may produce more than one instance.
+  Compiled to hovInd.js by tsc (issue #73); edit this file, not the emitted one.
+*/
+
+// TYPES
+
+// The hover-related style properties of a trigger in one state.
+interface TriggerStyles {
+  tagName: string;
+  inputType: string | null;
+  cursor: string;
+  border: string;
+  outline: string;
+  color: string;
+  backgroundColor: string;
+}
+// A violation to be reported.
+interface Violation {
+  loc: Locator;
+  what: string;
+}
+
+// CONSTANTS
+
+// Standard non-default hover cursors of inputs, by type.
+const standardInputCursors: Record<string, string> = {
+  email: 'text',
+  image: 'pointer',
+  number: 'text',
+  password: 'text',
+  search: 'text',
+  tel: 'text',
+  text: 'text',
+  url: 'text'
+};
+// Style properties compared between states.
+const comparedStyles: (keyof TriggerStyles)[] = ['backgroundColor', 'border', 'color', 'outline'];
+// Maximum count of triggers inspected, because each inspection performs 3 browser interactions.
+const MAX_TRIGGERS = 60;
+
+// FUNCTIONS
+
+// Returns the hover-related style properties of a trigger in its current state.
+const getStyles = async (loc: Locator): Promise<TriggerStyles> => await loc.evaluate(element => {
+  const {
+    cursor,
+    borderColor,
+    borderStyle,
+    borderWidth,
+    outlineColor,
+    outlineStyle,
+    outlineWidth,
+    outlineOffset,
+    color,
+    backgroundColor
+  } = window.getComputedStyle(element);
+  return {
+    tagName: element.tagName,
+    inputType: element.tagName === 'INPUT' ? element.getAttribute('type') || 'text' : null,
+    // Ignore any custom cursor images and keep only the fallback keyword.
+    cursor: cursor.replace(/^.+, */, ''),
+    border: `${borderColor} ${borderStyle} ${borderWidth}`,
+    outline: `${outlineColor} ${outlineStyle} ${outlineWidth} ${outlineOffset}`,
+    color,
+    backgroundColor
+  };
+});
+// Returns whether the hover cursor of a trigger is standard. A computed value of auto is standard, because browsers render it as the type-appropriate cursor.
+const cursorIsStandard = (styles: TriggerStyles) => {
+  const {tagName, inputType, cursor} = styles;
+  if (tagName === 'A') {
+    return ['pointer', 'auto'].includes(cursor);
+  }
+  if (tagName === 'INPUT') {
+    return [standardInputCursors[inputType || 'text'], 'default', 'auto'].includes(cursor);
+  }
+  if (tagName === 'BUTTON') {
+    return ['default', 'auto'].includes(cursor);
+  }
+  // Any other trigger is one with a hover listener, and its cursor is assumed standard.
+  return true;
+};
+// Returns whether the compared styles of two states are identical.
+const areAlike = (styles0: TriggerStyles, styles1: TriggerStyles) => comparedStyles
+.every(style => styles0[style] === styles1[style]);
+// Runs the test and returns the result.
+export const reporter = async (page: Page, report: Report, _: unknown, withItems: boolean) => {
+  // Get locators for the visible triggers.
+  const selector = ['a', 'button', 'input', '[onmouseenter]', '[onmouseover]']
+  .map(tagSelector => `body ${tagSelector}:visible`)
+  .join(', ');
+  const allLocs = await page.locator(selector).all();
+  // Inspect at most MAX_TRIGGERS of them, evenly spaced through the page.
+  const step = Math.max(1, Math.ceil(allLocs.length / MAX_TRIGGERS));
+  const locs = allLocs.filter((loc, index) => index % step === 0).slice(0, MAX_TRIGGERS);
+  const data: {
+    triggerCount: number; inspectedCount: number; prevented?: boolean; error?: string;
+  } = {
+    triggerCount: allLocs.length,
+    inspectedCount: locs.length
+  };
+  // Initialize the violations, by severity.
+  const cursorViolations: Violation[] = [];
+  const styleViolations: Violation[] = [];
+  const timeout = applyMultiplier(500);
+  // For each trigger:
+  for (const loc of locs) {
+    try {
+      // Move the mouse away from any previously hovered trigger.
+      await page.mouse.move(0, 0);
+      // Get its styles when neither focused nor hovered over.
+      const neutralStyles = await getStyles(loc);
+      // Get its styles when only focused.
+      await loc.focus({timeout});
+      const focusStyles = await getStyles(loc);
+      await loc.blur({timeout});
+      // Get its styles when only hovered over.
+      await loc.hover({timeout});
+      const hoverStyles = await getStyles(loc);
+      await page.mouse.move(0, 0);
+      // If its hover cursor is nonstandard:
+      if (! cursorIsStandard(hoverStyles)) {
+        // Add a violation.
+        cursorViolations.push({
+          loc,
+          what: `Element has a nonstandard hover cursor (${hoverStyles.cursor})`
+        });
+      }
+      // If it is a button and its hover styles are indistinguishable from its neutral styles:
+      if (hoverStyles.tagName === 'BUTTON' && areAlike(neutralStyles, hoverStyles)) {
+        // Add a violation.
+        styleViolations.push({
+          loc,
+          what: 'Element border, outline, color, and background color do not change when hovered over'
+        });
+      }
+      // Otherwise, if its hover styles differ from its neutral styles but are indistinguishable from its focus styles:
+      else if (! areAlike(neutralStyles, hoverStyles) && areAlike(focusStyles, hoverStyles)) {
+        // Add a violation.
+        styleViolations.push({
+          loc,
+          what: 'Element border, outline, color, and background color are alike on hover and focus'
+        });
+      }
+    }
+    // If focusing, blurring, or hovering throws an error:
+    catch(error) {
+      // If the error is a timeout, skip the trigger.
+      if (error instanceof playwright.errors.TimeoutError) {
+        continue;
+      }
+      // Otherwise, report this and quit.
+      data.prevented = true;
+      data.error = `ERROR inspecting a trigger (${(error as Error).message.slice(0, 200)})`;
+      break;
+    }
+  }
+  // Get results for the two severities and merge them.
+  const cursorResult = await getBasicResult(
+    report, withItems, 'hovInd', 2, 'Elements have nonstandard hover cursors', data, cursorViolations
+  );
+  const styleResult = await getBasicResult(
+    report,
+    withItems,
+    'hovInd',
+    1,
+    'Element styles do not distinguish hovering from the neutral or focus state',
+    data,
+    styleViolations
+  );
+  const totals = cursorResult.totals.map(
+    (total, index) => total + styleResult.totals[index]
+  ) as SeverityTotals;
+  return {
+    data,
+    totals,
+    standardInstances: [... cursorResult.standardInstances, ... styleResult.standardInstances]
+  };
+};

package/testaro/hover.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>;