@afixt/test-utils 2.1.1 → 2.3.0

package/BROWSER_TESTING.md

@@ -6,13 +6,13 @@ This project uses **JSDOM** for the main test suite with **Playwright** for CSS
 
 ## Current Status
 
-- **943 tests passing** in JSDOM environment (8 conditionally skipped)
+- **1101 tests passing** in JSDOM environment (8 conditionally skipped)
 - **20 tests passing** in Playwright for CSS pseudo-element support
-- **Total: 963 tests passing** across both environments
+- **Total: 1121 tests passing** across both environments
 
 ### Implementation Complete
 
-✅ JSDOM tests for all standard functionality (943 tests)
+✅ JSDOM tests for all standard functionality (1101 tests)
 ✅ Standalone Playwright tests for CSS pseudo-elements (20 tests)
 ✅ 8 CSS pseudo-element tests conditionally skipped in JSDOM, covered by Playwright
 
@@ -30,12 +30,12 @@ The 20 CSS pseudo-element tests run with standalone Playwright tests that inject
 ### JSDOM Tests (Main Test Suite)
 
 ```bash
-npm test                    # Run all 943 JSDOM tests
+npm test                    # Run all 1101 JSDOM tests
 npm run test:coverage       # Run with coverage
 npm run test:watch          # Watch mode
 ```
 
-**Status:** 943 tests passing (8 conditionally skipped)
+**Status:** 1101 tests passing (8 conditionally skipped)
 
 **Pros:**
 
@@ -113,17 +113,17 @@ The Playwright tests inject browser-compatible versions of `getGeneratedContent`
 
 ```json
 {
-    "test": "vitest run", // JSDOM tests (943 tests)
+    "test": "vitest run", // JSDOM tests (1101 tests)
     "test:coverage": "vitest run --coverage", // JSDOM with coverage
     "test:playwright:css": "playwright test ...", // Playwright CSS tests (20 tests)
-    "test:all": "npm run test && npm run test:playwright:css" // All tests (963 tests)
+    "test:all": "npm run test && npm run test:playwright:css" // All tests (1121 tests)
 }
 ```
 
 ## Test Coverage
 
-- **87.75% statement coverage**
-- **82.11% branch coverage**
-- **95.58% function coverage**
-- **87.69% line coverage**
-- **963 total tests passing** (943 JSDOM + 20 Playwright)
+- **88.98% statement coverage**
+- **84.37% branch coverage**
+- **95.21% function coverage**
+- **89.04% line coverage**
+- **1121 total tests passing** (1101 JSDOM + 20 Playwright)

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.0] - 2026-03-03
+
+### Fixes
+
+- **domUtils**: Add `inert` attribute and `content-visibility: hidden` detection to `isHiddenFromAT` (#62)
+- **testContrast**: Return `null` (cannot-determine) instead of `true` for elements with background images (#63)
+- **testContrast**: Return `null` for elements with CSS `filter` or `mix-blend-mode` that alter perceived color (#64)
+- **getAccessibleName**: Replace internal `isNotVisible` with `isA11yVisible` for proper visibility checking, including aria-labelledby reference exceptions (#57)
+- **getAccessibleName**: Handle zero-width spaces and non-breaking spaces in aria-label with `isEmptyOrWhitespace` (#70)
+- **getComputedRole**: Add context-dependent implicit roles per HTML-AAM (td/gridcell in grid, header/footer as generic inside sectioning elements) (#68)
+- **isHidden**: Distinguish `hidden="until-found"` from plain `hidden` attribute (#69)
+- **formUtils**: Skip `aria-hidden="true"` labels when resolving `aria-labelledby` in `hasExplicitAccessibleName` (#67)
+- **constants**: Add `template` to `NON_VISIBLE_SELECTORS` (#71)
+- **domUtils, getAccessibleName**: Escape all ID interpolations in CSS selectors to handle special characters (#72)
+
+## [2.1.1] - 2026-03-01
+
+### Fixes
+
+- **isA11yVisible**: Escape element IDs in CSS selectors to handle special characters like colons
+
 ## [2.1.0] - 2026-02-25
 
 ### Features

package/CLAUDE.md

@@ -44,7 +44,7 @@
 
 ### Test Status
 
-- **1076 tests passing** in JSDOM environment
+- **1129 tests passing** in JSDOM environment
 - **8 tests skipped** - Conditionally skipped in JSDOM; require real browser CSS pseudo-element support
 - **20 Playwright tests** cover CSS pseudo-element functionality in a real browser
 - See `BROWSER_TESTING.md` for details on the hybrid testing approach

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/test-utils",
-    "version": "2.1.1",
+    "version": "2.3.0",
     "description": "Various utilities for accessibility testing",
     "main": "src/index.js",
     "scripts": {

package/src/constants.js

@@ -404,6 +404,7 @@ const NON_VISIBLE_SELECTORS = [
     'param',
     'noframes',
     'ruby > rp',
+    'template',
 ];
 
 /**

package/src/domUtils.js

@@ -6,6 +6,18 @@ const {
     SEMANTIC_CONTAINER_ROLES,
     INTERACTIVE_HANDLER_ATTRIBUTES,
 } = require('./constants.js');
+const { deepQuerySelector, deepQuerySelectorAll } = require('./shadowDomUtils.js');
+
+/**
+ * Escapes a string for use inside a CSS selector.
+ * Uses the native CSS.escape when available (all modern browsers),
+ * falls back to identity for environments that lack it (e.g. JSDOM).
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+const cssEscape =
+    typeof CSS !== 'undefined' && typeof CSS.escape === 'function' ? CSS.escape : value => value;
 
 const domUtils = {
     /**
@@ -98,7 +110,7 @@ const domUtils = {
      * @returns {Element[]} An array of elements that have duplicate IDs.
      */
     getElementsWithDuplicateIds() {
-        const nodes = document.querySelectorAll('[id]');
+        const nodes = deepQuerySelectorAll(document, '[id]');
         const ids = {};
         const duplicates = [];
         nodes.forEach(node => {
@@ -108,7 +120,7 @@ const domUtils = {
                 duplicates.push(id);
             }
         });
-        return duplicates.map(id => document.querySelector(`#${id}`));
+        return duplicates.map(id => deepQuerySelector(document, `#${cssEscape(id)}`));
     },
 
     /**
@@ -162,10 +174,10 @@ const domUtils = {
         }
 
         // CSS-escape the ID for use in attribute selectors
-        const escaped = CSS.escape(id);
+        const escaped = cssEscape(id);
 
         // Direct attribute references
-        if (document.querySelector('[for="' + escaped + '"]')) {
+        if (deepQuerySelector(document, '[for="' + escaped + '"]')) {
             return true;
         }
 
@@ -178,7 +190,7 @@ const domUtils = {
             'aria-flowto',
         ];
         for (const attr of ariaTokenAttrs) {
-            const elements = document.querySelectorAll('[' + attr + ']');
+            const elements = deepQuerySelectorAll(document, '[' + attr + ']');
             for (const el of elements) {
                 const ids = el.getAttribute(attr).trim().split(/\s+/);
                 if (ids.includes(id)) {
@@ -190,18 +202,18 @@ const domUtils = {
         // Single-ID ARIA references
         const ariaSingleAttrs = ['aria-activedescendant', 'aria-errormessage'];
         for (const attr of ariaSingleAttrs) {
-            if (document.querySelector('[' + attr + '="' + escaped + '"]')) {
+            if (deepQuerySelector(document, '[' + attr + '="' + escaped + '"]')) {
                 return true;
             }
         }
 
         // Fragment references in href
-        if (document.querySelector('a[href="#' + escaped + '"]')) {
+        if (deepQuerySelector(document, 'a[href="#' + escaped + '"]')) {
             return true;
         }
 
         // Table headers attribute (space-separated list of IDs)
-        const headerElements = document.querySelectorAll('[headers]');
+        const headerElements = deepQuerySelectorAll(document, '[headers]');
         for (const el of headerElements) {
             const ids = el.getAttribute('headers').trim().split(/\s+/);
             if (ids.includes(id)) {
@@ -210,7 +222,7 @@ const domUtils = {
         }
 
         // list attribute on input elements
-        if (document.querySelector('input[list="' + escaped + '"]')) {
+        if (deepQuerySelector(document, 'input[list="' + escaped + '"]')) {
             return true;
         }
 
@@ -226,10 +238,31 @@ const domUtils = {
         if (!element) {
             return false;
         }
-        return (
+
+        // Check aria-hidden (self or ancestor)
+        if (
             element.getAttribute('aria-hidden') === 'true' ||
             (element.closest && !!element.closest('[aria-hidden="true"]'))
-        );
+        ) {
+            return true;
+        }
+
+        // Check inert (self or ancestor) — inert elements are removed from the a11y tree
+        let el = element;
+        while (el) {
+            if (el.hasAttribute && el.hasAttribute('inert')) {
+                return true;
+            }
+            el = el.parentElement;
+        }
+
+        // Check content-visibility: hidden — genuinely hides content from AT
+        const style = window.getComputedStyle(element);
+        if (style.contentVisibility === 'hidden') {
+            return true;
+        }
+
+        return false;
     },
 
     /**
@@ -397,3 +430,4 @@ const domUtils = {
 };
 
 module.exports = domUtils;
+module.exports.cssEscape = cssEscape;

package/src/formUtils.js

@@ -3,6 +3,9 @@
  * @module formUtils
  */
 
+const { isHiddenFromAT } = require('./domUtils.js');
+const { deepGetElementById } = require('./shadowDomUtils.js');
+
 const formUtils = {
     /**
      * Check if an element is a labellable form control per HTML spec.
@@ -49,8 +52,8 @@ const formUtils = {
         if (element.hasAttribute('aria-labelledby')) {
             const ids = element.getAttribute('aria-labelledby').trim().split(/\s+/);
             for (let i = 0; i < ids.length; i++) {
-                const labelEl = document.getElementById(ids[i]);
-                if (labelEl && labelEl.textContent.trim()) {
+                const labelEl = deepGetElementById(document, ids[i]);
+                if (labelEl && !isHiddenFromAT(labelEl) && labelEl.textContent.trim()) {
                     return true;
                 }
             }

package/src/getAccessibleName.js

@@ -1,4 +1,4 @@
-const { isEmpty } = require('./stringUtils.js');
+const { isEmptyOrWhitespace } = require('./stringUtils.js');
 const { getAccessibleText } = require('./getAccessibleText.js');
 const {
     TEXT_ROLES,
@@ -6,6 +6,9 @@ const {
     LANDMARK_ROLES,
     LANDMARK_ELEMENT_MAP,
 } = require('./constants.js');
+const { cssEscape } = require('./domUtils.js');
+const { isA11yVisible } = require('./isA11yVisible.js');
+const { deepGetElementById, deepQuerySelector } = require('./shadowDomUtils.js');
 
 /**
  * Gets the accessible name of an element according to the accessible name calculation algorithm
@@ -26,9 +29,21 @@ function getAccessibleName(element) {
     // the title won't be used in any meaningful way by Accessibility APIs
     const unlabellable = 'head *, hr, param, caption, colgroup, col, tbody, tfoot, thead, tr';
 
-    // STEP 0 - verify item is visible and can be labelled
-    // if it isn't visible or can't be labelled then just bail
-    if (isNotVisible(element) || matchesSelector(element, unlabellable)) {
+    if (matchesSelector(element, unlabellable)) {
+        return false;
+    }
+
+    // Skip inherently non-visible semantic elements (script, style, template, etc.)
+    // but exclude 'area' since area elements have accessible names via alt attribute
+    const nonVisibleSelectorsWithoutArea = NON_VISIBLE_SELECTORS.filter(s => s !== 'area');
+    if (nonVisibleSelectorsWithoutArea.some(selector => matchesSelector(element, selector))) {
+        return false;
+    }
+
+    // STEP 0 - Use isA11yVisible (strict mode) for visibility check.
+    // This respects aria-labelledby/describedby references, preventing false
+    // negatives for display:none elements that provide names to other elements.
+    if (!isA11yVisible(element, true)) {
         return false;
     }
 
@@ -44,7 +59,7 @@ function getAccessibleName(element) {
 
         const text = [];
         for (const id of ids) {
-            const labelElement = document.getElementById(id);
+            const labelElement = deepGetElementById(document, id);
             if (!labelElement || !getAccessibleText(labelElement)) {
                 return false;
             }
@@ -58,7 +73,7 @@ function getAccessibleName(element) {
     // STEP 2.1 - if aria-label exists, return the text in it
     if (element.hasAttribute('aria-label')) {
         const ariaLabel = element.getAttribute('aria-label');
-        if (ariaLabel) {
+        if (!isEmptyOrWhitespace(ariaLabel)) {
             return ariaLabel;
         }
         // there is no 'else' here because an empty aria-label is/ should be ignored and calculation continued
@@ -75,7 +90,7 @@ function getAccessibleName(element) {
             // Use getAccessibleText which handles both text nodes and
             // image alt text in the subtree (not just textContent)
             const text = getAccessibleText(element);
-            if (!isEmpty(text)) {
+            if (!isEmptyOrWhitespace(text)) {
                 return text;
             }
         }
@@ -95,12 +110,15 @@ function getAccessibleName(element) {
         )
     ) {
         // first we choose the explicit relationship over all others.
-        if (element.id && document.querySelector('label[for="' + element.id + '"]')) {
+        if (
+            element.id &&
+            deepQuerySelector(document, 'label[for="' + cssEscape(element.id) + '"]')
+        ) {
             id = element.id;
             // Use only the *first* label that matches this ID.
             // Sometimes JS libraries screw this up by hiding one of the
             // labels or misnaming one
-            label = document.querySelector('label[for="' + id + '"]');
+            label = deepQuerySelector(document, 'label[for="' + cssEscape(id) + '"]');
             if (label) {
                 return getAccessibleText(label);
             }
@@ -210,11 +228,14 @@ function getAccessibleName(element) {
         )
     ) {
         // first we choose the explicit relationship over all others.
-        if (element.id && document.querySelector('label[for="' + element.id + '"]')) {
+        if (
+            element.id &&
+            deepQuerySelector(document, 'label[for="' + cssEscape(element.id) + '"]')
+        ) {
             id = element.id;
 
             //Use only the *first* label that matches this ID. Sometimes ppl screw this up
-            label = document.querySelector('label[for="' + id + '"]');
+            label = deepQuerySelector(document, 'label[for="' + cssEscape(id) + '"]');
             if (label) {
                 return getAccessibleText(label);
             }
@@ -359,7 +380,10 @@ function getAccessibleName(element) {
         if (element.tagName.toLowerCase() === 'meter') {
             // Check for label with for attribute
             if (element.id) {
-                const label = document.querySelector('label[for="' + element.id + '"]');
+                const label = deepQuerySelector(
+                    document,
+                    'label[for="' + cssEscape(element.id) + '"]'
+                );
                 if (label && strlen(getAccessibleText(label)) > 0) {
                     return getAccessibleText(label);
                 }
@@ -474,44 +498,6 @@ function getAccessibleName(element) {
     }
 }
 
-/**
- * Helper function to check if element is NOT visible
- * @param {Element} element - The element to check
- * @returns {boolean} True if element is not visible, false otherwise
- */
-function isNotVisible(element) {
-    // Importing isVisible would be better, but for this standalone function we'll check it this way
-    if (!element) {
-        return true;
-    }
-
-    // Note: 'area' is filtered out because area elements DO have accessible names
-    // via the alt attribute and should participate in accessible name calculation
-    const nonVisibleSelectorsWithoutArea = NON_VISIBLE_SELECTORS.filter(s => s !== 'area');
-
-    if (nonVisibleSelectorsWithoutArea.some(selector => matchesSelector(element, selector))) {
-        return true; // Not visible in accessibility tree
-    }
-
-    // Check if display is none
-    const isElemDisplayed = el => window.getComputedStyle(el).display === 'none';
-
-    if (isElemDisplayed(element)) {
-        return true;
-    }
-
-    // Check parent elements
-    let parent = element.parentElement;
-    while (parent) {
-        if (isElemDisplayed(parent)) {
-            return true;
-        }
-        parent = parent.parentElement;
-    }
-
-    return element.getAttribute('aria-hidden') === 'true';
-}
-
 /**
  * Helper function to check if an element matches a selector
  * @param {Element} element - Element to check
@@ -541,7 +527,7 @@ function matchesSelector(element, selector) {
  * @returns {number} The string length or 0
  */
 function strlen(str) {
-    return typeof str === 'string' && !isEmpty(str.trim()) ? str.trim().length : 0;
+    return typeof str === 'string' && !isEmptyOrWhitespace(str) ? str.trim().length : 0;
 }
 
 // Export the function for CommonJS module usage

package/src/getAccessibleText.js

@@ -1,4 +1,4 @@
-const { isEmpty } = require('./stringUtils.js');
+const { isEmptyOrWhitespace } = require('./stringUtils.js');
 
 /**
  * Get all accessible text for an element, including aria-labels and content from children.
@@ -27,7 +27,7 @@ function getAccessibleText(el, options) {
         // Check for aria-label first (highest priority)
         if (el.hasAttribute('aria-label')) {
             const ariaLabel = el.getAttribute('aria-label').trim();
-            if (ariaLabel) {
+            if (!isEmptyOrWhitespace(ariaLabel)) {
                 return ariaLabel;
             }
         }
@@ -65,7 +65,7 @@ function collectSubtreeText(node, visibleOnly) {
     for (let child = node.firstChild; child; child = child.nextSibling) {
         if (child.nodeType === Node.TEXT_NODE) {
             const text = child.nodeValue.trim();
-            if (!isEmpty(text)) {
+            if (!isEmptyOrWhitespace(text)) {
                 parts.push(text);
             }
         } else if (child.nodeType === Node.ELEMENT_NODE) {