@afixt/test-utils 2.1.0 → 2.2.0

package/src/isA11yVisible.js

@@ -1,5 +1,6 @@
 const { NON_VISIBLE_SELECTORS } = require('./constants.js');
 const isHidden = require('./isHidden.js');
+const { cssEscape } = require('./domUtils.js');
 
 /**
  * Checks if an element is visible to assistive technologies (AT).
@@ -67,8 +68,11 @@ function isA11yVisible(element, strict = false) {
     }
 
     // Check if element is referenced by aria-labelledby or aria-describedby
+    // 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) : '';
     document
-        .querySelectorAll(`*[aria-labelledby~="${id}"], *[aria-describedby~="${id}"]`)
+        .querySelectorAll(`*[aria-labelledby~="${escapedId}"], *[aria-describedby~="${escapedId}"]`)
         .forEach(referencingElement => {
             if (window.getComputedStyle(referencingElement).display !== 'none') {
                 visible = true;

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/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,

package/test/domUtils.test.js

@@ -552,6 +552,26 @@ describe('domUtils', () => {
             const child = document.getElementById('child');
             expect(domUtils.isHiddenFromAT(child)).toBe(false);
         });
+
+        it('should return true when element has inert attribute', () => {
+            document.body.innerHTML = '<div inert><span id="child">Inert child</span></div>';
+            const child = document.getElementById('child');
+            expect(domUtils.isHiddenFromAT(child)).toBe(true);
+        });
+
+        it('should return true when element itself is inert', () => {
+            const el = document.createElement('div');
+            el.setAttribute('inert', '');
+            document.body.appendChild(el);
+            expect(domUtils.isHiddenFromAT(el)).toBe(true);
+        });
+
+        it('should return true when element has content-visibility hidden', () => {
+            document.body.innerHTML = '<div id="target">Content</div>';
+            const el = document.getElementById('target');
+            el.style.contentVisibility = 'hidden';
+            expect(domUtils.isHiddenFromAT(el)).toBe(true);
+        });
     });
 
     describe('isEffectivelyInteractive', () => {

package/test/formUtils.test.js

@@ -120,6 +120,24 @@ describe('formUtils', () => {
             expect(formUtils.hasExplicitAccessibleName(el)).toBe(false);
         });
 
+        it('should return true when aria-labelledby points to sr-only element', () => {
+            document.body.innerHTML = `
+                <span id="lbl" style="position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)">SR-only Label</span>
+                <div id="target" aria-labelledby="lbl"></div>
+            `;
+            const target = document.getElementById('target');
+            expect(formUtils.hasExplicitAccessibleName(target)).toBe(true);
+        });
+
+        it('should return false when aria-labelledby points to aria-hidden="true" element', () => {
+            document.body.innerHTML = `
+                <span id="lbl" aria-hidden="true">Hidden Label</span>
+                <div id="target" aria-labelledby="lbl"></div>
+            `;
+            const target = document.getElementById('target');
+            expect(formUtils.hasExplicitAccessibleName(target)).toBe(false);
+        });
+
         it('should handle multiple ids in aria-labelledby', () => {
             document.body.innerHTML = `
                 <span id="lbl1"></span>

package/test/getAccessibleName.test.js

@@ -467,4 +467,48 @@ describe('getAccessibleName', () => {
             });
         });
     });
+
+    describe('whitespace-only accessible name handling', () => {
+        it('should ignore aria-label with only non-breaking spaces and use text content instead', () => {
+            document.body.innerHTML = '<button aria-label="\u00A0\u00A0">Click</button>';
+            const button = document.querySelector('button');
+            // NBSP-only aria-label is treated as empty; falls through to text content
+            expect(getAccessibleName(button)).toBe('Click');
+        });
+
+        it('should ignore aria-label with only zero-width spaces and use text content instead', () => {
+            document.body.innerHTML = '<button aria-label="\u200B\u200B">Click</button>';
+            const button = document.querySelector('button');
+            expect(getAccessibleName(button)).toBe('Click');
+        });
+
+        it('should return false when aria-label is NBSP-only and element has no other name source', () => {
+            document.body.innerHTML = '<div role="button" aria-label="\u00A0"></div>';
+            const div = document.querySelector('[role="button"]');
+            expect(getAccessibleName(div)).toBe(false);
+        });
+    });
+
+    describe('visibility handling for aria-labelledby referenced elements', () => {
+        it('should return accessible name for display:none element referenced by aria-labelledby', () => {
+            document.body.innerHTML = `
+                <li style="display:none">
+                    <button id="expand-btn">Expand subnavigation</button>
+                </li>
+                <ul aria-labelledby="expand-btn">Items</ul>
+            `;
+            const button = document.getElementById('expand-btn');
+            expect(getAccessibleName(button)).toBe('Expand subnavigation');
+        });
+
+        it('should return false for truly hidden element not referenced by aria-labelledby', () => {
+            document.body.innerHTML = `
+                <div aria-hidden="true">
+                    <button id="hidden-btn">Hidden button</button>
+                </div>
+            `;
+            const button = document.getElementById('hidden-btn');
+            expect(getAccessibleName(button)).toBe(false);
+        });
+    });
 });

package/test/getComputedRole.test.js

@@ -2,179 +2,251 @@ import { describe, it, expect, beforeEach } from 'vitest';
 import { getComputedRole, roleMapping } from '../src/getComputedRole.js';
 
 describe('getComputedRole', () => {
-  beforeEach(() => {
-    document.body.innerHTML = '';
-  });
-
-  it('should return undefined for null or undefined element', () => {
-    expect(getComputedRole(null)).toBeUndefined();
-    expect(getComputedRole(undefined)).toBeUndefined();
-  });
-
-  it('should return the role attribute value if present', () => {
-    // Arrange
-    const element = document.createElement('div');
-    element.setAttribute('role', 'button');
-    document.body.appendChild(element);
-    
-    // Act
-    const result = getComputedRole(element);
-    
-    // Assert
-    expect(result).toBe('button');
-  });
-
-  it('should return the correct role for basic elements with simple string mapping', () => {
-    // Test cases for elements with simple string mapping
-    const testCases = [
-      { tag: 'div', expectedRole: 'group' },
-      { tag: 'p', expectedRole: 'text' },
-      { tag: 'ul', expectedRole: 'list' },
-      { tag: 'h1', expectedRole: 'heading' },
-      { tag: 'button', expectedRole: 'button' },
-      { tag: 'nav', expectedRole: 'navigation' },
-      { tag: 'header', expectedRole: 'banner' },
-      { tag: 'footer', expectedRole: 'contentinfo' },
-      { tag: 'main', expectedRole: 'main' }
-    ];
-    
-    testCases.forEach(({ tag, expectedRole }) => {
-      // Arrange
-      const element = document.createElement(tag);
-      document.body.appendChild(element);
-      
-      // Act
-      const result = getComputedRole(element);
-      
-      // Assert
-      expect(result).toBe(expectedRole);
-    });
-  });
-
-  it('should handle link elements (a) correctly based on href attribute', () => {
-    // Arrange
-    const linkWithHref = document.createElement('a');
-    linkWithHref.setAttribute('href', 'https://example.com');
-    
-    const linkWithoutHref = document.createElement('a');
-    
-    document.body.appendChild(linkWithHref);
-    document.body.appendChild(linkWithoutHref);
-    
-    // Act
-    const withHrefResult = getComputedRole(linkWithHref);
-    const withoutHrefResult = getComputedRole(linkWithoutHref);
-    
-    // Assert
-    expect(withHrefResult).toBe('link');
-    expect(withoutHrefResult).toBe('text');
-  });
-
-  it('should handle image elements based on alt attribute', () => {
-    // Arrange
-    const imgWithAlt = document.createElement('img');
-    imgWithAlt.setAttribute('alt', 'Description of image');
-    
-    const imgWithEmptyAlt = document.createElement('img');
-    imgWithEmptyAlt.setAttribute('alt', '');
-    
-    document.body.appendChild(imgWithAlt);
-    document.body.appendChild(imgWithEmptyAlt);
-    
-    // Act
-    const withAltResult = getComputedRole(imgWithAlt);
-    const withEmptyAltResult = getComputedRole(imgWithEmptyAlt);
-    
-    // Assert
-    expect(withAltResult).toBe('image');
-    expect(withEmptyAltResult).toBe('presentation');
-  });
-
-  it('should handle various input types correctly', () => {
-    const inputTypes = [
-      { type: 'button', expectedRole: 'button' },
-      { type: 'checkbox', expectedRole: 'checkbox' },
-      { type: 'hidden', expectedRole: 'noRole' },
-      { type: 'image', expectedRole: 'button' },
-      { type: 'number', expectedRole: 'spinbutton' },
-      { type: 'radio', expectedRole: 'radio' },
-      { type: 'range', expectedRole: 'slider' },
-      { type: 'reset', expectedRole: 'button' },
-      { type: 'submit', expectedRole: 'button' },
-      { type: 'password', expectedRole: 'textbox' },
-      { type: 'text', expectedRole: 'textbox' },
-      { type: 'search', expectedRole: 'searchbox' }
-    ];
-    
-    inputTypes.forEach(({ type, expectedRole }) => {
-      // Arrange
-      const input = document.createElement('input');
-      input.setAttribute('type', type);
-      document.body.appendChild(input);
-      
-      // Act
-      const result = getComputedRole(input);
-      
-      // Assert
-      expect(result).toBe(expectedRole);
-    });
-  });
-
-  it('should handle elements with no role mapping', () => {
-    // Create a custom element that's not in the roleMapping
-    const customElement = document.createElement('custom-element');
-    document.body.appendChild(customElement);
-    
-    // Act
-    const result = getComputedRole(customElement);
-    
-    // Assert
-    expect(result).toBeUndefined();
-  });
-
-  it('should prioritize role attribute over computed role', () => {
-    // Arrange
-    const element = document.createElement('button'); // Inherent role is 'button'
-    element.setAttribute('role', 'menuitem'); // Override with custom role
-    document.body.appendChild(element);
-    
-    // Act
-    const result = getComputedRole(element);
-    
-    // Assert
-    expect(result).toBe('menuitem'); // Should use the explicit role
-  });
-
-  it('should handle empty or whitespace role attribute', () => {
-    // Arrange
-    const emptyRoleElement = document.createElement('div');
-    emptyRoleElement.setAttribute('role', '');
-    
-    const whitespaceRoleElement = document.createElement('div');
-    whitespaceRoleElement.setAttribute('role', '  ');
-    
-    document.body.appendChild(emptyRoleElement);
-    document.body.appendChild(whitespaceRoleElement);
-    
-    // Act
-    const emptyResult = getComputedRole(emptyRoleElement);
-    const whitespaceResult = getComputedRole(whitespaceRoleElement);
-    
-    // Assert
-    // The implementation returns the fallback 'group' role for div when the role attribute is empty
-    expect(emptyResult).toBe('group');
-    expect(whitespaceResult).toBe('  '); // Whitespace is preserved
-  });
-
-  it('should handle case insensitivity for tag names', () => {
-    // Arrange - create element with uppercase tag
-    const upperElement = document.createElement('DIV');
-    document.body.appendChild(upperElement);
-    
-    // Act
-    const result = getComputedRole(upperElement);
-    
-    // Assert
-    expect(result).toBe('group'); // Should match 'div' in the mapping
-  });
-});
+    beforeEach(() => {
+        document.body.innerHTML = '';
+    });
+
+    it('should return undefined for null or undefined element', () => {
+        expect(getComputedRole(null)).toBeUndefined();
+        expect(getComputedRole(undefined)).toBeUndefined();
+    });
+
+    it('should return the role attribute value if present', () => {
+        // Arrange
+        const element = document.createElement('div');
+        element.setAttribute('role', 'button');
+        document.body.appendChild(element);
+
+        // Act
+        const result = getComputedRole(element);
+
+        // Assert
+        expect(result).toBe('button');
+    });
+
+    it('should return the correct role for basic elements with simple string mapping', () => {
+        // Test cases for elements with simple string mapping
+        const testCases = [
+            { tag: 'div', expectedRole: 'group' },
+            { tag: 'p', expectedRole: 'text' },
+            { tag: 'ul', expectedRole: 'list' },
+            { tag: 'h1', expectedRole: 'heading' },
+            { tag: 'button', expectedRole: 'button' },
+            { tag: 'nav', expectedRole: 'navigation' },
+            { tag: 'header', expectedRole: 'banner' },
+            { tag: 'footer', expectedRole: 'contentinfo' },
+            { tag: 'main', expectedRole: 'main' },
+        ];
+
+        testCases.forEach(({ tag, expectedRole }) => {
+            // Arrange
+            const element = document.createElement(tag);
+            document.body.appendChild(element);
+
+            // Act
+            const result = getComputedRole(element);
+
+            // Assert
+            expect(result).toBe(expectedRole);
+        });
+    });
+
+    it('should handle link elements (a) correctly based on href attribute', () => {
+        // Arrange
+        const linkWithHref = document.createElement('a');
+        linkWithHref.setAttribute('href', 'https://example.com');
+
+        const linkWithoutHref = document.createElement('a');
+
+        document.body.appendChild(linkWithHref);
+        document.body.appendChild(linkWithoutHref);
+
+        // Act
+        const withHrefResult = getComputedRole(linkWithHref);
+        const withoutHrefResult = getComputedRole(linkWithoutHref);
+
+        // Assert
+        expect(withHrefResult).toBe('link');
+        expect(withoutHrefResult).toBe('text');
+    });
+
+    it('should handle image elements based on alt attribute', () => {
+        // Arrange
+        const imgWithAlt = document.createElement('img');
+        imgWithAlt.setAttribute('alt', 'Description of image');
+
+        const imgWithEmptyAlt = document.createElement('img');
+        imgWithEmptyAlt.setAttribute('alt', '');
+
+        document.body.appendChild(imgWithAlt);
+        document.body.appendChild(imgWithEmptyAlt);
+
+        // Act
+        const withAltResult = getComputedRole(imgWithAlt);
+        const withEmptyAltResult = getComputedRole(imgWithEmptyAlt);
+
+        // Assert
+        expect(withAltResult).toBe('image');
+        expect(withEmptyAltResult).toBe('presentation');
+    });
+
+    it('should handle various input types correctly', () => {
+        const inputTypes = [
+            { type: 'button', expectedRole: 'button' },
+            { type: 'checkbox', expectedRole: 'checkbox' },
+            { type: 'hidden', expectedRole: 'noRole' },
+            { type: 'image', expectedRole: 'button' },
+            { type: 'number', expectedRole: 'spinbutton' },
+            { type: 'radio', expectedRole: 'radio' },
+            { type: 'range', expectedRole: 'slider' },
+            { type: 'reset', expectedRole: 'button' },
+            { type: 'submit', expectedRole: 'button' },
+            { type: 'password', expectedRole: 'textbox' },
+            { type: 'text', expectedRole: 'textbox' },
+            { type: 'search', expectedRole: 'searchbox' },
+        ];
+
+        inputTypes.forEach(({ type, expectedRole }) => {
+            // Arrange
+            const input = document.createElement('input');
+            input.setAttribute('type', type);
+            document.body.appendChild(input);
+
+            // Act
+            const result = getComputedRole(input);
+
+            // Assert
+            expect(result).toBe(expectedRole);
+        });
+    });
+
+    it('should handle elements with no role mapping', () => {
+        // Create a custom element that's not in the roleMapping
+        const customElement = document.createElement('custom-element');
+        document.body.appendChild(customElement);
+
+        // Act
+        const result = getComputedRole(customElement);
+
+        // Assert
+        expect(result).toBeUndefined();
+    });
+
+    it('should prioritize role attribute over computed role', () => {
+        // Arrange
+        const element = document.createElement('button'); // Inherent role is 'button'
+        element.setAttribute('role', 'menuitem'); // Override with custom role
+        document.body.appendChild(element);
+
+        // Act
+        const result = getComputedRole(element);
+
+        // Assert
+        expect(result).toBe('menuitem'); // Should use the explicit role
+    });
+
+    it('should handle empty or whitespace role attribute', () => {
+        // Arrange
+        const emptyRoleElement = document.createElement('div');
+        emptyRoleElement.setAttribute('role', '');
+
+        const whitespaceRoleElement = document.createElement('div');
+        whitespaceRoleElement.setAttribute('role', '  ');
+
+        document.body.appendChild(emptyRoleElement);
+        document.body.appendChild(whitespaceRoleElement);
+
+        // Act
+        const emptyResult = getComputedRole(emptyRoleElement);
+        const whitespaceResult = getComputedRole(whitespaceRoleElement);
+
+        // Assert
+        // The implementation returns the fallback 'group' role for div when the role attribute is empty
+        expect(emptyResult).toBe('group');
+        expect(whitespaceResult).toBe('  '); // Whitespace is preserved
+    });
+
+    it('should return gridcell for td inside role="grid"', () => {
+        document.body.innerHTML = `
+      <table role="grid">
+        <tr><td id="target">Cell</td></tr>
+      </table>
+    `;
+        const td = document.getElementById('target');
+        expect(getComputedRole(td)).toBe('gridcell');
+    });
+
+    it('should return cell for td inside regular table', () => {
+        document.body.innerHTML = `
+      <table>
+        <tr><td id="target">Cell</td></tr>
+      </table>
+    `;
+        const td = document.getElementById('target');
+        expect(getComputedRole(td)).toBe('cell');
+    });
+
+    it('should return gridcell for td inside role="treegrid"', () => {
+        document.body.innerHTML = `
+      <table role="treegrid">
+        <tr><td id="target">Cell</td></tr>
+      </table>
+    `;
+        const td = document.getElementById('target');
+        expect(getComputedRole(td)).toBe('gridcell');
+    });
+
+    it('should return generic for header inside article', () => {
+        document.body.innerHTML = `
+      <article>
+        <header id="target">Article Header</header>
+      </article>
+    `;
+        const header = document.getElementById('target');
+        expect(getComputedRole(header)).toBe('generic');
+    });
+
+    it('should return generic for header inside section', () => {
+        document.body.innerHTML = `
+      <section>
+        <header id="target">Section Header</header>
+      </section>
+    `;
+        const header = document.getElementById('target');
+        expect(getComputedRole(header)).toBe('generic');
+    });
+
+    it('should return banner for header that is direct child of body', () => {
+        document.body.innerHTML = '<header id="target">Page Header</header>';
+        const header = document.getElementById('target');
+        expect(getComputedRole(header)).toBe('banner');
+    });
+
+    it('should return generic for footer inside article', () => {
+        document.body.innerHTML = `
+      <article>
+        <footer id="target">Article Footer</footer>
+      </article>
+    `;
+        const footer = document.getElementById('target');
+        expect(getComputedRole(footer)).toBe('generic');
+    });
+
+    it('should return contentinfo for footer that is direct child of body', () => {
+        document.body.innerHTML = '<footer id="target">Page Footer</footer>';
+        const footer = document.getElementById('target');
+        expect(getComputedRole(footer)).toBe('contentinfo');
+    });
+
+    it('should handle case insensitivity for tag names', () => {
+        // Arrange - create element with uppercase tag
+        const upperElement = document.createElement('DIV');
+        document.body.appendChild(upperElement);
+
+        // Act
+        const result = getComputedRole(upperElement);
+
+        // Assert
+        expect(result).toBe('group'); // Should match 'div' in the mapping
+    });
+});