@afixt/test-utils 2.1.1 → 2.3.0

package/src/getComputedRole.js

@@ -1,65 +1,65 @@
 const roleMapping = {
-    'a': {
+    a: {
         '[href]': 'link',
-        ':not([href])': 'text'
+        ':not([href])': 'text',
     },
-    'abbr': 'text',
-    'address': 'text',
-    'area': {
+    abbr: 'text',
+    address: 'text',
+    area: {
         '[href]': 'link',
-        ':not([href])': 'text'
+        ':not([href])': 'text',
     },
-    'article': 'article',
-    'aside': 'complementary',
-    'audio': 'group',
-    'b': 'text',
-    'base': 'noRole',
-    'bdi': 'noRole',
-    'bdo': 'text',
-    'blockquote': 'text',
-    'body': 'document',
-    'br': 'noRole',
-    'button': 'button',
-    'canvas': 'image',
-    'caption': 'text',
-    'cite': 'text',
-    'code': 'text',
-    'col': 'noRole',
-    'colgroup': 'group',
-    'data': 'noRole',
-    'datalist': 'listbox',
-    'dd': 'definition',
-    'del': 'text',
-    'details': 'group',
-    'dfn': 'term',
-    'dialog': 'dialog',
-    'div': 'group',
-    'dl': 'list',
-    'dt': 'term',
-    'em': 'text',
-    'embed': 'noRole',
-    'fieldset': 'group',
-    'figcaption': 'text',
-    'figure': 'figure',
-    'footer': 'contentinfo',
-    'form': 'form',
-    'h1': 'heading',
-    'h2': 'heading',
-    'h3': 'heading',
-    'h4': 'heading',
-    'h5': 'heading',
-    'h6': 'heading',
-    'head': 'noRole',
-    'header': 'banner',
-    'hr': 'separator',
-    'html': 'noRole',
-    'i': 'text',
-    'iframe': 'noRole',
-    'img': {
+    article: 'article',
+    aside: 'complementary',
+    audio: 'group',
+    b: 'text',
+    base: 'noRole',
+    bdi: 'noRole',
+    bdo: 'text',
+    blockquote: 'text',
+    body: 'document',
+    br: 'noRole',
+    button: 'button',
+    canvas: 'image',
+    caption: 'text',
+    cite: 'text',
+    code: 'text',
+    col: 'noRole',
+    colgroup: 'group',
+    data: 'noRole',
+    datalist: 'listbox',
+    dd: 'definition',
+    del: 'text',
+    details: 'group',
+    dfn: 'term',
+    dialog: 'dialog',
+    div: 'group',
+    dl: 'list',
+    dt: 'term',
+    em: 'text',
+    embed: 'noRole',
+    fieldset: 'group',
+    figcaption: 'text',
+    figure: 'figure',
+    footer: 'contentinfo',
+    form: 'form',
+    h1: 'heading',
+    h2: 'heading',
+    h3: 'heading',
+    h4: 'heading',
+    h5: 'heading',
+    h6: 'heading',
+    head: 'noRole',
+    header: 'banner',
+    hr: 'separator',
+    html: 'noRole',
+    i: 'text',
+    iframe: 'noRole',
+    img: {
         '[alt=""]': 'presentation',
-        'img': 'image'
+        img: 'image',
     },
-    'input': {
+    input: {
         '[type="button"]': 'button',
         '[type="checkbox"]': 'checkbox',
         '[type="hidden"]': 'noRole',
@@ -74,85 +74,150 @@ const roleMapping = {
         '[type="search"]': 'searchbox',
         '[type="tel"]': 'textbox',
         '[type="text"]': 'textbox',
-        '[type="url"]': 'textbox'
+        '[type="url"]': 'textbox',
     },
-    'ins': 'text',
-    'kbd': 'text',
-    'label': 'text',
-    'legend': 'text',
-    'li': 'listitem',
-    'link': 'noRole',
-    'main': 'main',
-    'map': 'noRole',
-    'mark': 'text',
-    'math': 'math',
-    'menu': 'menu',
-    'meta': 'noRole',
-    'meter': 'text',
-    'nav': 'navigation',
-    'noscript': 'noRole',
-    'object': 'noRole',
-    'ol': 'list',
-    'optgroup': 'group',
-    'option': 'option',
-    'output': 'status',
-    'p': 'text',
-    'param': 'noRole',
-    'picture': 'noRole',
-    'pre': 'text',
-    'progress': 'progressbar',
-    'q': 'text',
-    'rb': 'noRole',
-    'rp': 'noRole',
-    'rt': 'text',
-    'rtc': 'noRole',
-    'ruby': 'text',
-    's': 'text',
-    'samp': 'text',
-    'script': 'noRole',
-    'section': 'region',
-    'select': 'combobox',
-    'small': 'text',
-    'source': 'noRole',
-    'span': 'group',
-    'strong': 'text',
-    'style': 'noRole',
-    'sub': 'text',
-    'summary': 'button',
-    'sup': 'text',
-    'svg': 'noRole',
-    'table': 'table',
-    'tbody': 'rowgroup',
-    'td': 'cell',
-    'template': 'noRole',
-    'textarea': 'textbox',
-    'tfoot': 'rowgroup',
-    'th': 'columnheader',
-    'thead': 'rowgroup',
-    'time': 'text',
-    'title': 'noRole',
-    'tr': 'row',
-    'track': 'noRole',
-    'u': 'text',
-    'ul': 'list',
-    'var': 'text',
-    'video': 'group',
-    'wbr': 'noRole'
+    ins: 'text',
+    kbd: 'text',
+    label: 'text',
+    legend: 'text',
+    li: 'listitem',
+    link: 'noRole',
+    main: 'main',
+    map: 'noRole',
+    mark: 'text',
+    math: 'math',
+    menu: 'menu',
+    meta: 'noRole',
+    meter: 'text',
+    nav: 'navigation',
+    noscript: 'noRole',
+    object: 'noRole',
+    ol: 'list',
+    optgroup: 'group',
+    option: 'option',
+    output: 'status',
+    p: 'text',
+    param: 'noRole',
+    picture: 'noRole',
+    pre: 'text',
+    progress: 'progressbar',
+    q: 'text',
+    rb: 'noRole',
+    rp: 'noRole',
+    rt: 'text',
+    rtc: 'noRole',
+    ruby: 'text',
+    s: 'text',
+    samp: 'text',
+    script: 'noRole',
+    section: 'region',
+    select: 'combobox',
+    small: 'text',
+    source: 'noRole',
+    span: 'group',
+    strong: 'text',
+    style: 'noRole',
+    sub: 'text',
+    summary: 'button',
+    sup: 'text',
+    svg: 'noRole',
+    table: 'table',
+    tbody: 'rowgroup',
+    td: 'cell',
+    template: 'noRole',
+    textarea: 'textbox',
+    tfoot: 'rowgroup',
+    th: 'columnheader',
+    thead: 'rowgroup',
+    time: 'text',
+    title: 'noRole',
+    tr: 'row',
+    track: 'noRole',
+    u: 'text',
+    ul: 'list',
+    var: 'text',
+    video: 'group',
+    wbr: 'noRole',
 };
 
 /**
- * Gets the computed role of an HTML element.
+ * Sectioning elements that change the implicit role of header/footer
+ * from landmark (banner/contentinfo) to generic.
+ */
+const SECTIONING_ELEMENTS = ['article', 'aside', 'main', 'nav', 'section'];
+
+/**
+ * Check if an element has an ancestor with a given role or tag name.
+ * @param {HTMLElement} element - The element to check
+ * @param {Object} options - Search options
+ * @param {string[]} [options.roles] - ARIA roles to match
+ * @param {string[]} [options.tags] - Tag names (lowercase) to match
+ * @returns {boolean} True if a matching ancestor is found
+ */
+function hasAncestor(element, { roles = [], tags = [] }) {
+    let ancestor = element.parentElement;
+    while (ancestor) {
+        const ancestorRole = (ancestor.getAttribute('role') || '').toLowerCase();
+        if (roles.length && roles.includes(ancestorRole)) {
+            return true;
+        }
+        const ancestorTag = ancestor.tagName.toLowerCase();
+        if (tags.length && tags.includes(ancestorTag)) {
+            return true;
+        }
+        ancestor = ancestor.parentElement;
+    }
+    return false;
+}
+
+/**
+ * Gets the computed role of an HTML element, considering ancestor context
+ * for context-dependent implicit roles per HTML-AAM.
  *
  * @param {HTMLElement} element - The HTML element to get the role for.
  * @returns {string|undefined} The computed role of the element, or undefined if no role is found.
  */
 function getComputedRole(element) {
-    if (!element) return undefined;
+    if (!element) {
+        return undefined;
+    }
 
     const roleAttr = element.getAttribute('role');
-    if (roleAttr) return roleAttr;
+    if (roleAttr) {
+        return roleAttr;
+    }
 
     const tagName = element.tagName.toLowerCase();
+
+    // Context-dependent implicit roles per HTML-AAM
+    if (tagName === 'td') {
+        if (hasAncestor(element, { roles: ['grid', 'treegrid'] })) {
+            return 'gridcell';
+        }
+        return 'cell';
+    }
+
+    if (tagName === 'th') {
+        if (hasAncestor(element, { roles: ['grid', 'treegrid'] })) {
+            return 'columnheader';
+        }
+        return 'columnheader';
+    }
+
+    if (tagName === 'header') {
+        if (hasAncestor(element, { tags: SECTIONING_ELEMENTS })) {
+            return 'generic';
+        }
+        return 'banner';
+    }
+
+    if (tagName === 'footer') {
+        if (hasAncestor(element, { tags: SECTIONING_ELEMENTS })) {
+            return 'generic';
+        }
+        return 'contentinfo';
+    }
+
     const role = roleMapping[tagName];
 
     if (typeof role === 'string') {
@@ -170,5 +235,5 @@ function getComputedRole(element) {
 
 module.exports = {
     roleMapping,
-    getComputedRole
+    getComputedRole,
 };

package/src/getImageText.js

@@ -26,7 +26,14 @@ async function getImageText(imagePath, options = {}) {
     try {
         const {
             data: { text },
-        } = await _internal.recognize(imagePath, lang, { logger, ...tesseractOptions });
+            // errorHandler silences the bare `throw` in tesseract.js createWorker.js when a
+            // job is rejected — without it the throw escapes try/catch and becomes an uncaught
+            // exception in the host process. The promise rejection is still caught below.
+        } = await _internal.recognize(imagePath, lang, {
+            logger,
+            errorHandler: () => {},
+            ...tesseractOptions,
+        });
 
         const extractedText = text.trim();
         return extractedText.length > 0 ? extractedText : false;

package/src/index.js

@@ -82,6 +82,9 @@ const tableUtils = require('./tableUtils.js');
 // Query cache utilities
 const queryCache = require('./queryCache.js');
 
+// Shadow DOM utilities
+const shadowDomUtils = require('./shadowDomUtils.js');
+
 // List event listeners
 const listEventListeners = require('./listEventListeners.js');
 
@@ -126,4 +129,5 @@ module.exports = {
     ...tableUtils,
     ...queryCache,
     ...listEventListeners,
+    ...shadowDomUtils,
 };

package/src/isA11yVisible.js

@@ -1,5 +1,7 @@
 const { NON_VISIBLE_SELECTORS } = require('./constants.js');
 const isHidden = require('./isHidden.js');
+const { cssEscape } = require('./domUtils.js');
+const { deepQuerySelectorAll } = require('./shadowDomUtils.js');
 
 /**
  * Checks if an element is visible to assistive technologies (AT).
@@ -67,13 +69,17 @@ function isA11yVisible(element, strict = false) {
     }
 
     // Check if element is referenced by aria-labelledby or aria-describedby
-    document
-        .querySelectorAll(`*[aria-labelledby~="${id}"], *[aria-describedby~="${id}"]`)
-        .forEach(referencingElement => {
-            if (window.getComputedStyle(referencingElement).display !== 'none') {
-                visible = true;
-            }
-        });
+    // Use CSS.escape(id) to handle IDs containing special characters like colons
+    // (e.g. Radix UI generates IDs like "radix-:rj:-tab-account")
+    const escapedId = id ? cssEscape(id) : '';
+    deepQuerySelectorAll(
+        document,
+        `*[aria-labelledby~="${escapedId}"], *[aria-describedby~="${escapedId}"]`
+    ).forEach(referencingElement => {
+        if (window.getComputedStyle(referencingElement).display !== 'none') {
+            visible = true;
+        }
+    });
 
     // Check if any parent has aria-hidden="true" when strict mode is on
     if (visible && strict) {

package/src/isHidden.js

@@ -18,15 +18,22 @@ const isHidden = (element, options = {}) => {
 
     const { checkAriaHidden = false, checkOpacity = false, checkDimensions = false } = options;
 
-    // Check the hidden attribute
-    if (element.hasAttribute('hidden')) {
+    // Check the hidden attribute — but not hidden="until-found", which is
+    // visually hidden but still findable by Find-in-Page and accessible to AT.
+    // In real browsers, hidden="until-found" uses content-visibility:hidden
+    // rather than display:none.
+    const hiddenAttr = element.getAttribute('hidden');
+    const isUntilFound = hiddenAttr === 'until-found';
+    if (hiddenAttr !== null && !isUntilFound) {
         return true;
     }
 
-    // Use computed style to catch CSS class/stylesheet rules
+    // Use computed style to catch CSS class/stylesheet rules.
+    // Skip display:none check for hidden="until-found" because JSDOM
+    // incorrectly applies display:none (real browsers don't).
     const style = window.getComputedStyle(element);
 
-    if (style.display === 'none') {
+    if (style.display === 'none' && !isUntilFound) {
         return true;
     }
 

package/src/shadowDomUtils.js

@@ -0,0 +1,118 @@
+/**
+ * @file Shadow-DOM-aware element lookup utilities
+ * @module shadowDomUtils
+ * @description Provides deep traversal functions that cross open shadow DOM
+ * boundaries when looking up elements by ID or CSS selector.
+ *
+ * **Limitation:** Closed shadow roots (created with `{ mode: 'closed' }`) are
+ * inaccessible by spec — `.shadowRoot` returns `null` for them — so these
+ * utilities can only traverse *open* shadow roots.
+ */
+
+/**
+ * Finds an element by ID, searching through open shadow roots when the
+ * element is not found in the light DOM.
+ *
+ * @param {Document|ShadowRoot|Element} root - The root to start searching from.
+ *   Typically `document`, but can be any subtree root or ShadowRoot.
+ * @param {string} id - The ID to search for.
+ * @returns {Element|null} The first matching element, or `null`.
+ */
+function deepGetElementById(root, id) {
+    if (!root || !id) {
+        return null;
+    }
+
+    // Fast path: root supports getElementById (Document and ShadowRoot do)
+    if (typeof root.getElementById === 'function') {
+        const el = root.getElementById(id);
+        if (el) {
+            return el;
+        }
+    }
+
+    // Recurse into open shadow roots
+    const allElements = root.querySelectorAll ? root.querySelectorAll('*') : [];
+    for (const el of allElements) {
+        if (el.shadowRoot) {
+            const found = deepGetElementById(el.shadowRoot, id);
+            if (found) {
+                return found;
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Runs `querySelector` against the given root and, if no match is found,
+ * recursively searches open shadow roots.
+ *
+ * @param {Document|ShadowRoot|Element} root - The root to start searching from.
+ * @param {string} selector - A CSS selector string.
+ * @returns {Element|null} The first matching element, or `null`.
+ */
+function deepQuerySelector(root, selector) {
+    if (!root || !selector) {
+        return null;
+    }
+
+    // Fast path
+    if (typeof root.querySelector === 'function') {
+        const el = root.querySelector(selector);
+        if (el) {
+            return el;
+        }
+    }
+
+    // Recurse into open shadow roots
+    const allElements = root.querySelectorAll ? root.querySelectorAll('*') : [];
+    for (const el of allElements) {
+        if (el.shadowRoot) {
+            const found = deepQuerySelector(el.shadowRoot, selector);
+            if (found) {
+                return found;
+            }
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Runs `querySelectorAll` against the given root and then recursively
+ * collects matches from all open shadow roots.
+ *
+ * @param {Document|ShadowRoot|Element} root - The root to start searching from.
+ * @param {string} selector - A CSS selector string.
+ * @returns {Element[]} An array of all matching elements (may be empty).
+ */
+function deepQuerySelectorAll(root, selector) {
+    if (!root || !selector) {
+        return [];
+    }
+
+    const results = [];
+
+    // Collect from this root
+    if (typeof root.querySelectorAll === 'function') {
+        results.push(...root.querySelectorAll(selector));
+    }
+
+    // Recurse into open shadow roots
+    const allElements = root.querySelectorAll ? root.querySelectorAll('*') : [];
+    for (const el of allElements) {
+        if (el.shadowRoot) {
+            results.push(...deepQuerySelectorAll(el.shadowRoot, selector));
+        }
+    }
+
+    return results;
+}
+
+module.exports = {
+    deepGetElementById,
+    deepQuerySelector,
+    deepQuerySelectorAll,
+};

package/src/stringUtils.js

@@ -2,9 +2,12 @@ const { GENERIC_TITLES, GENERIC_LINK_TEXT } = require('./constants.js');
 
 const stringUtils = (function () {
     /**
-     * Check if a string is empty or only contains whitespace.
+     * Check if a string is empty or only contains standard whitespace.
+     * NOTE: For accessibility name/label checks, prefer {@link isEmptyOrWhitespace}
+     * which also catches non-breaking spaces (\u00A0), zero-width spaces (\u200B),
+     * and other invisible Unicode characters that do not constitute meaningful text.
      * @param {string} str - The string to check.
-     * @returns {boolean} Whether the string is empty.
+     * @returns {boolean} Whether the string is empty or whitespace-only.
      */
     function isEmpty(str) {
         return !str || str.trim().length === 0;

package/src/testContrast.js

@@ -45,6 +45,40 @@ function hasBackgroundImage(el) {
     return false;
 }
 
+/**
+ * Check if an element or any of its ancestors has a CSS filter or mix-blend-mode
+ * that would alter effective colors in ways that cannot be computed from CSS values alone.
+ * @param {Element} el - The element to check
+ * @returns {boolean} True if the element or an ancestor has a color-altering CSS property
+ */
+function hasEffectColorModifier(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 filter = styles.getPropertyValue('filter');
+        if (filter && filter !== 'none') {
+            return true;
+        }
+
+        const mixBlendMode = styles.getPropertyValue('mix-blend-mode');
+        if (mixBlendMode && mixBlendMode !== 'normal') {
+            return true;
+        }
+
+        current = current.parentElement;
+    }
+
+    return false;
+}
+
 /**
  * Get the computed background color for an element.
  * @param  {Element} el - the element to be tested
@@ -290,7 +324,13 @@ function testContrast(el, options = { level: 'AA' }) {
     // 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;
+        return null;
+    }
+
+    // Skip elements affected by CSS filters or mix-blend-mode (self or ancestor).
+    // These alter effective colors in ways that cannot be computed from CSS values alone.
+    if (hasEffectColorModifier(el)) {
+        return null;
     }
 
     const styles = window.getComputedStyle(el);
@@ -400,6 +440,7 @@ function testContrast(el, options = { level: 'AA' }) {
 module.exports = {
     testContrast,
     hasBackgroundImage,
+    hasEffectColorModifier,
     getComputedBackgroundColor,
     luminance,
     parseRGB,