@afixt/test-utils 1.2.3 → 2.0.0

package/src/isFocusable.js

@@ -1,21 +1,29 @@
+const isHidden = require('./isHidden.js');
+const hasHiddenParent = require('./hasHiddenParent.js');
+
 /**
- * Determines if an element is focusable.
+ * Determines if an element is focusable via user interaction (tab order).
+ * Elements with tabindex="-1" are programmatically focusable via .focus()
+ * but are NOT considered focusable by this function, as they are not
+ * reachable through keyboard navigation.
  * @param {Element} element - The HTML element to check.
  * @returns {boolean} - Returns true if the element is focusable, otherwise false.
  */
 function isFocusable(element) {
-    if (!element) return false;
+    if (!element) {
+        return false;
+    }
 
     const nodeName = element.nodeName.toLowerCase();
-    const tabIndex = element.getAttribute("tabindex");
+    const tabIndex = element.getAttribute('tabindex');
 
     // The element and all of its ancestors must be visible
-    if (element.closest(":hidden")) {
+    if (isHidden(element) || hasHiddenParent(element)) {
         return false;
     }
 
-    // If tabindex is defined, its value must be greater than or equal to 0
-    if (!isNaN(tabIndex) && tabIndex < 0) {
+    // If tabindex is defined, its value must be >= 0
+    if (tabIndex !== null && !isNaN(tabIndex) && parseInt(tabIndex, 10) < 0) {
         return false;
     }
 
@@ -25,14 +33,26 @@ function isFocusable(element) {
     }
 
     // If the element is a link, href must be defined
-    if (nodeName === "a" || nodeName === "area") {
-        return element.hasAttribute("href");
+    if (nodeName === 'a' || nodeName === 'area') {
+        return element.hasAttribute('href');
+    }
+
+    // contenteditable elements are focusable
+    if (
+        element.getAttribute('contenteditable') === 'true' ||
+        element.getAttribute('contenteditable') === ''
+    ) {
+        return true;
+    }
+
+    // Any element with a non-negative tabindex is focusable
+    if (tabIndex !== null && !isNaN(tabIndex) && parseInt(tabIndex, 10) >= 0) {
+        return true;
     }
 
-    // This is some other page element that is not normally focusable
     return false;
 }
 
 module.exports = {
-    isFocusable
+    isFocusable,
 };

package/src/isHidden.js

@@ -1,17 +1,53 @@
-
 /**
  * Checks if a given DOM element is hidden.
  *
- * An element is considered hidden if its `display` style is set to "none"
- * or if it has the `hidden` attribute.
+ * By default checks: computed display:none, visibility:hidden, and the hidden attribute.
+ * Additional checks can be enabled via the options parameter.
  *
  * @param {HTMLElement} element - The DOM element to check.
- * @returns {boolean} - Returns `true` if the element is hidden, otherwise `false`.
+ * @param {Object} [options={}] - Optional configuration.
+ * @param {boolean} [options.checkAriaHidden=false] - Also check aria-hidden="true".
+ * @param {boolean} [options.checkOpacity=false] - Also treat opacity:0 as hidden.
+ * @param {boolean} [options.checkDimensions=false] - Also treat zero width+height as hidden.
+ * @returns {boolean} True if the element is hidden.
  */
-const isHidden = (element) => {
-    return (
-        element.style.display === "none" || element.hasAttribute("hidden")
-    );
+const isHidden = (element, options = {}) => {
+    if (!element || !(element instanceof Element)) {
+        return false;
+    }
+
+    const { checkAriaHidden = false, checkOpacity = false, checkDimensions = false } = options;
+
+    // Check the hidden attribute
+    if (element.hasAttribute('hidden')) {
+        return true;
+    }
+
+    // Use computed style to catch CSS class/stylesheet rules
+    const style = window.getComputedStyle(element);
+
+    if (style.display === 'none') {
+        return true;
+    }
+
+    if (style.visibility === 'hidden') {
+        return true;
+    }
+
+    // Optional checks
+    if (checkAriaHidden && element.getAttribute('aria-hidden') === 'true') {
+        return true;
+    }
+
+    if (checkOpacity && style.opacity === '0') {
+        return true;
+    }
+
+    if (checkDimensions && element.offsetWidth === 0 && element.offsetHeight === 0) {
+        return true;
+    }
+
+    return false;
 };
 
 module.exports = isHidden;

package/src/listEventListeners.js

@@ -5,6 +5,33 @@ const eventListenersMap = new WeakMap();
 const originalAddEventListener = EventTarget.prototype.addEventListener;
 const originalRemoveEventListener = EventTarget.prototype.removeEventListener;
 
+const KNOWN_EVENT_PROPERTIES = [
+    'onclick',
+    'ondblclick',
+    'oncontextmenu',
+    'onmousedown',
+    'onmouseup',
+    'onmouseover',
+    'onmouseout',
+    'onmouseenter',
+    'onmouseleave',
+    'onkeydown',
+    'onkeyup',
+    'onkeypress',
+    'onfocus',
+    'onblur',
+    'onchange',
+    'oninput',
+    'onsubmit',
+    'ontouchstart',
+    'ontouchend',
+    'ontouchmove',
+    'onscroll',
+    'onresize',
+    'onload',
+    'onerror',
+];
+
 // Override addEventListener to track event listeners
 EventTarget.prototype.addEventListener = function (type, listener, options) {
     if (!eventListenersMap.has(this)) {
@@ -25,14 +52,14 @@ EventTarget.prototype.removeEventListener = function (type, listener, options) {
     if (eventListenersMap.has(this)) {
         const listeners = eventListenersMap.get(this);
         if (listeners[type]) {
-            listeners[type] = listeners[type].filter((l) => l.listener !== listener);
+            listeners[type] = listeners[type].filter(l => l.listener !== listener);
         }
     }
     return originalRemoveEventListener.call(this, type, listener, options);
 };
 
 // Function to get XPath of an element
-const getXPath = (element) => {
+const getXPath = element => {
     if (element.id) {
         return `//*[@id="${element.id}"]`;
     }
@@ -52,9 +79,84 @@ const getXPath = (element) => {
     return path;
 };
 
-// Function to get all event listeners on an element
-const getEventListeners = (element) => {
-    return eventListenersMap.get(element) || {};
+/**
+ * Collect inline attribute event handlers from an element
+ * @param {Element} element - The element to inspect
+ * @returns {Object} Map of event names to listener entry arrays
+ */
+const getAttributeHandlers = element => {
+    const handlers = {};
+    if (!element || !element.attributes) {
+        return handlers;
+    }
+    for (let i = 0; i < element.attributes.length; i++) {
+        const attr = element.attributes[i];
+        if (attr.name.startsWith('on')) {
+            const eventName = attr.name.slice(2);
+            handlers[eventName] = [{ listener: attr.value, bindingType: 'attribute' }];
+        }
+    }
+    return handlers;
+};
+
+/**
+ * Collect property-based event handlers from an element
+ * @param {Element} element - The element to inspect
+ * @param {Object} attributeHandlers - Already-detected attribute handlers to avoid duplicates
+ * @returns {Object} Map of event names to listener entry arrays
+ */
+const getPropertyHandlers = (element, attributeHandlers) => {
+    const handlers = {};
+    if (!element) {
+        return handlers;
+    }
+    for (const prop of KNOWN_EVENT_PROPERTIES) {
+        if (typeof element[prop] === 'function') {
+            const eventName = prop.slice(2);
+            if (!attributeHandlers[eventName]) {
+                handlers[eventName] = [{ listener: element[prop], bindingType: 'property' }];
+            }
+        }
+    }
+    return handlers;
+};
+
+/**
+ * Get all event listeners on an element, including addEventListener, attribute, and property handlers
+ * @param {Element} element - The element to inspect
+ * @returns {Object} Map of event names to listener entry arrays
+ */
+const getEventListeners = element => {
+    const tracked = eventListenersMap.get(element) || {};
+
+    // Add bindingType to tracked entries
+    const result = {};
+    for (const eventName of Object.keys(tracked)) {
+        result[eventName] = tracked[eventName].map(entry => ({
+            ...entry,
+            bindingType: 'addEventListener',
+        }));
+    }
+
+    // Merge attribute handlers
+    const attrHandlers = getAttributeHandlers(element);
+    for (const eventName of Object.keys(attrHandlers)) {
+        if (!result[eventName]) {
+            result[eventName] = [];
+        }
+        result[eventName].push(...attrHandlers[eventName]);
+    }
+
+    // Merge property handlers (excluding those already found as attributes)
+    const propHandlers = getPropertyHandlers(element, attrHandlers);
+    for (const eventName of Object.keys(propHandlers)) {
+        if (!result[eventName]) {
+            result[eventName] = [];
+        }
+        result[eventName].push(...propHandlers[eventName]);
+    }
+
+    return result;
 };
 
 /**
@@ -72,11 +174,14 @@ const listEventListeners = (rootElement = document) => {
     function processElement(el) {
         const listeners = getEventListeners(el);
         if (Object.keys(listeners).length > 0) {
-            Object.keys(listeners).forEach((eventName) => {
-                eventListeners.push({
-                    element: el.tagName.toLowerCase(),
-                    xpath: getXPath(el),
-                    event: eventName
+            Object.keys(listeners).forEach(eventName => {
+                listeners[eventName].forEach(entry => {
+                    eventListeners.push({
+                        element: el.tagName.toLowerCase(),
+                        xpath: getXPath(el),
+                        event: eventName,
+                        bindingType: entry.bindingType,
+                    });
                 });
             });
         }

package/src/stringUtils.js

@@ -1,3 +1,5 @@
+const { GENERIC_TITLES, GENERIC_LINK_TEXT } = require('./constants.js');
+
 const stringUtils = (function () {
     /**
      * Check if a string is empty or only contains whitespace.
@@ -83,45 +85,6 @@ const stringUtils = (function () {
         return str.pathname;
     }
 
-    /**
-     * Extracts and concatenates all text content from a given DOM element, including text from text nodes,
-     * elements with aria-label attributes, and alt attributes of img elements.
-     *
-     * @param {Element} el - The DOM element from which to extract text.
-     * @returns {string} A string containing all concatenated text content from the element.
-     */
-    function getAllText(el) {
-        // Check for form element value (input, textarea, select)
-        if (el.value !== undefined && el.value !== '') {
-            return el.value;
-        }
-
-        const walker = document.createTreeWalker(el, NodeFilter.SHOW_ALL, null, false);
-        const textNodes = [];
-        let node;
-        let text;
-
-        while (walker.nextNode()) {
-            node = walker.currentNode;
-            if (node.nodeType === Node.TEXT_NODE) {
-                text = node.nodeValue.trim();
-                if (text) {
-                    textNodes.push(text);
-                } else {
-                    textNodes.push(node.textContent.trim());
-                }
-            } else if (node.nodeType === Node.ELEMENT_NODE) {
-                if (node.hasAttribute('aria-label')) {
-                    textNodes.push(node.getAttribute('aria-label'));
-                } else if (node.tagName === 'IMG' && node.hasAttribute('alt')) {
-                    textNodes.push(node.getAttribute('alt'));
-                }
-            }
-        }
-
-        return textNodes.join(' ');
-    }
-
     /**
      * Checks if the given element contains any text.
      *
@@ -129,7 +92,16 @@ const stringUtils = (function () {
      * @returns {boolean} True if the element contains text, false otherwise.
      */
     function hasText(element) {
-        return getAllText(element).trim() !== '';
+        if (!element) {
+            return false;
+        }
+        // Check form element value (input, textarea, select)
+        if (element.value !== undefined && element.value !== '') {
+            return true;
+        }
+        // Lazy require to avoid circular dependency (getAccessibleText requires stringUtils)
+        const { getAccessibleText } = require('./getAccessibleText.js');
+        return getAccessibleText(element).trim() !== '';
     }
 
     /**
@@ -156,14 +128,17 @@ const stringUtils = (function () {
         if (!title) {
             return false;
         }
-        const genericTitles = ['iframe', 'frame', 'untitled', 'title', 'content', 'main', 'page'];
         const normalized = title.toLowerCase().trim();
 
-        if (genericTitles.includes(normalized)) {
+        if (GENERIC_TITLES.includes(normalized)) {
             return true;
         }
 
-        if (/^(frame|iframe|untitled|title)\d*$/i.test(normalized)) {
+        if (
+            /^(frame|iframe|untitled|title|page|content|section|document|tab|slide|sheet|panel|window|screen|view|module|widget|region|form)\s?\d+$/i.test(
+                normalized
+            )
+        ) {
             return true;
         }
 
@@ -180,32 +155,7 @@ const stringUtils = (function () {
         if (!text) {
             return false;
         }
-        const defaults = [
-            'click here',
-            'here',
-            'more',
-            'read more',
-            'learn more',
-            'click',
-            'link',
-            'this',
-            'page',
-            'article',
-            'continue',
-            'go',
-            'see more',
-            'view',
-            'download',
-            'pdf',
-            'document',
-            'form',
-            'submit',
-            'button',
-            'press',
-            'select',
-            'choose',
-        ];
-        const list = genericList || defaults;
+        const list = genericList || GENERIC_LINK_TEXT;
         const lowerText = text.toLowerCase().trim();
         return list.some(function (generic) {
             return lowerText === generic;
@@ -248,33 +198,6 @@ const stringUtils = (function () {
         });
     }
 
-    /**
-     * Extracts DOM text content from an element, including img alt text,
-     * but excluding ARIA attributes (aria-label, aria-labelledby).
-     * Useful for detecting actual visible/DOM text that may conflict with ARIA labels.
-     *
-     * @param {Element} root - The DOM element from which to extract text.
-     * @returns {string} Concatenated text from text nodes and img alt attributes.
-     */
-    function textIncludingImgAlt(root) {
-        let out = '';
-        const walker = document.createTreeWalker(
-            root,
-            NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT // eslint-disable-line no-bitwise
-        );
-        let n = walker.currentNode;
-        while (n) {
-            if (n.nodeType === Node.TEXT_NODE) {
-                out += n.nodeValue;
-            }
-            if (n.nodeType === Node.ELEMENT_NODE && n.tagName === 'IMG') {
-                out += n.getAttribute('alt') || '';
-            }
-            n = walker.nextNode();
-        }
-        return out;
-    }
-
     return {
         isEmpty,
         isString,
@@ -283,9 +206,7 @@ const stringUtils = (function () {
         isUpperCase,
         isAlphaNumeric,
         getPathFromUrl,
-        getAllText,
         hasText,
-        textIncludingImgAlt,
         isEmptyOrWhitespace,
         isGenericTitle,
         isGenericLinkText,

package/src/tableUtils.js

@@ -3,6 +3,8 @@
  * @module tableUtils
  */
 
+const { GENERIC_SUMMARIES } = require('./constants.js');
+
 const tableUtils = {
     /**
      * Check if table has multiple header rows (rows containing th elements).
@@ -137,43 +139,9 @@ const tableUtils = {
      * @returns {boolean} True if the summary is generic
      */
     isGenericSummary(summary, genericList) {
-        const GENERIC_SUMMARIES = genericList || [
-            'table',
-            'data',
-            'data table',
-            'information',
-            'content',
-            'main content',
-            'layout',
-            'layout table',
-            'for layout',
-            'table for layout purposes',
-            'structural table',
-            'this table is used for page layout',
-            'header',
-            'footer',
-            'navigation',
-            'nav',
-            'body',
-            'combobox',
-            'links design table',
-            'title and navigation',
-            'main heading',
-            'spacer',
-            'spacer table',
-            'menu',
-            'n/a',
-            'na',
-            'none',
-            'null',
-            'empty',
-            'blank',
-            'undefined',
-            'table summary',
-            'summary',
-        ];
+        const list = genericList || GENERIC_SUMMARIES;
         const normalized = summary.toLowerCase().trim();
-        return GENERIC_SUMMARIES.includes(normalized);
+        return list.includes(normalized);
     },
 };
 

package/src/testContrast.js

@@ -1,3 +1,50 @@
+/**
+ * Check if an element or any of its ancestors has a background image set.
+ * Walks up the DOM tree until it finds a background image or an opaque background color.
+ * @param {Element} el - The element to check
+ * @returns {boolean} True if the element or a visible ancestor has a background image
+ */
+function hasBackgroundImage(el) {
+    if (!el || el.nodeType === 9 || !window.getComputedStyle) {
+        return false;
+    }
+
+    let current = el;
+    while (current && current.nodeType !== 9) {
+        const styles = window.getComputedStyle(current);
+        if (!styles) {
+            return false;
+        }
+
+        const bgImage = styles.getPropertyValue('background-image');
+        if (bgImage && bgImage !== 'none') {
+            return true;
+        }
+
+        // If this element has an opaque background color, stop traversal
+        // since no ancestor background image would be visible through it
+        const bgColor = styles.getPropertyValue('background-color');
+        const parsed = parseRGB(bgColor);
+        if (parsed) {
+            const isTransparent =
+                bgColor === 'rgba(0, 0, 0, 0)' ||
+                bgColor === 'transparent' ||
+                (parsed[4] !== undefined && parseFloat(parsed[4]) === 0);
+            const isSemiTransparent =
+                parsed[4] !== undefined && parseFloat(parsed[4]) > 0 && parseFloat(parsed[4]) < 1;
+
+            if (!isTransparent && !isSemiTransparent) {
+                // Opaque background color, no ancestor background image visible
+                return false;
+            }
+        }
+
+        current = current.parentElement;
+    }
+
+    return false;
+}
+
 /**
  * Get the computed background color for an element.
  * @param  {Element} el - the element to be tested
@@ -240,6 +287,12 @@ function testContrast(el, options = { level: 'AA' }) {
         return false;
     }
 
+    // Skip elements with a background image on the element itself or a visible ancestor.
+    // Contrast cannot be reliably tested against background images.
+    if (hasBackgroundImage(el)) {
+        return true;
+    }
+
     const styles = window.getComputedStyle(el);
     const selfFG = styles.getPropertyValue('color');
     const selfBG = getComputedBackgroundColor(el);
@@ -346,6 +399,7 @@ function testContrast(el, options = { level: 'AA' }) {
 
 module.exports = {
     testContrast,
+    hasBackgroundImage,
     getComputedBackgroundColor,
     luminance,
     parseRGB,