@afixt/test-utils 2.1.1 → 2.3.0

package/test/isA11yVisible.test.js

@@ -259,4 +259,37 @@ describe('isA11yVisible', () => {
         const element = document.getElementById('test');
         expect(isA11yVisible(element)).toBe(false);
     });
+
+    it('should treat <template> as inherently non-visible (AT-visible) even with display:none', () => {
+        // In real browsers, <template> has display:none by default via UA stylesheet.
+        // It should be treated as inherently non-visible (like script/style) and
+        // return true (exempt from accessibility checks), not false (hidden).
+        document.body.innerHTML =
+            '<template id="test" style="display:none"><div>Template content</div></template>';
+        const element = document.getElementById('test');
+        expect(isA11yVisible(element)).toBe(true);
+    });
+
+    describe('shadow DOM integration', () => {
+        it('should detect aria-labelledby reference from inside a shadow root', () => {
+            // Create a hidden element that provides an accessible name
+            const hidden = document.createElement('span');
+            hidden.id = 'shadow-ref-source';
+            hidden.style.display = 'none';
+            hidden.textContent = 'Label text';
+            document.body.appendChild(hidden);
+
+            // Create shadow host with an element that references the hidden element
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const button = document.createElement('button');
+            button.setAttribute('aria-labelledby', 'shadow-ref-source');
+            shadow.appendChild(button);
+
+            // The hidden element should still be considered AT-visible because
+            // it's referenced by an aria-labelledby from the shadow DOM
+            expect(isA11yVisible(hidden)).toBe(true);
+        });
+    });
 });

package/test/isHidden.test.js

@@ -240,6 +240,24 @@ describe('isHidden', () => {
         expect(isHidden(element, { checkDimensions: true })).toBe(true);
     });
 
+    it('should return false for elements with hidden="until-found"', () => {
+        const element = document.createElement('div');
+        element.setAttribute('hidden', 'until-found');
+        document.body.appendChild(element);
+
+        // hidden="until-found" is NOT fully hidden — content is findable by
+        // browser Find-in-Page and may be accessible to AT
+        expect(isHidden(element)).toBe(false);
+    });
+
+    it('should return true for elements with plain hidden attribute (empty string)', () => {
+        const element = document.createElement('div');
+        element.setAttribute('hidden', '');
+        document.body.appendChild(element);
+
+        expect(isHidden(element)).toBe(true);
+    });
+
     it('should detect visibility:hidden applied via CSS class', () => {
         // Arrange
         const style = document.createElement('style');

package/test/playwright/colon-id-a11y-visible.spec.js

@@ -0,0 +1,160 @@
+/**
+ * Playwright tests for isA11yVisible with colon-containing IDs
+ *
+ * Issue #61: CSS.escape is needed when building attribute selectors from
+ * element IDs. Colons in IDs (e.g. Radix UI "radix-:rj:-tab-account")
+ * break unescaped CSS selectors.
+ *
+ * Run with: npm run test:playwright:css
+ */
+
+const { test, expect } = require('@playwright/test');
+const path = require('path');
+
+test.describe('isA11yVisible with colon-containing IDs', () => {
+    test.beforeEach(async ({ page }) => {
+        const fixturePath = path.join(__dirname, 'fixtures', 'colon-id-a11y-visible.html');
+        await page.goto(`file://${fixturePath}`);
+
+        // Inject browser-compatible isA11yVisible (mirrors src/isA11yVisible.js)
+        await page.addScriptTag({
+            content: `
+                const NON_VISIBLE_SELECTORS = [
+                    'base','head','meta','title','link','style','script','br','nobr',
+                    'col','embed','input[type="hidden"]','keygen','source','track',
+                ];
+
+                function isHidden(element, options) {
+                    if (!element || !(element instanceof Element)) return false;
+                    options = options || {};
+                    if (element.hasAttribute('hidden')) return true;
+                    const style = window.getComputedStyle(element);
+                    if (style.display === 'none') return true;
+                    if (style.visibility === 'hidden') return true;
+                    if (options.checkOpacity && style.opacity === '0') return true;
+                    return false;
+                }
+
+                function isA11yVisible(element, strict) {
+                    if (strict === undefined) strict = false;
+                    if (!element || !(element instanceof Element)) return false;
+                    if (!element.isConnected) return false;
+
+                    const id = element.id;
+                    let visible = true;
+
+                    if (NON_VISIBLE_SELECTORS.some(function(s) { return element.matches(s); })) {
+                        return true;
+                    }
+
+                    function optionalAriaHidden(el, strictCheck) {
+                        return strictCheck && el.getAttribute('aria-hidden') === 'true';
+                    }
+
+                    if (isHidden(element, { checkOpacity: true })) {
+                        visible = false;
+                    } else {
+                        let parent = element.parentElement;
+                        while (parent) {
+                            const style = window.getComputedStyle(parent);
+                            if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
+                                visible = false;
+                                break;
+                            }
+                            parent = parent.parentElement;
+                        }
+                    }
+
+                    if (visible && optionalAriaHidden(element, strict)) {
+                        visible = false;
+                    }
+
+                    if (id) {
+                        document
+                            .querySelectorAll(
+                                '*[aria-labelledby~="' + CSS.escape(id) + '"], *[aria-describedby~="' + CSS.escape(id) + '"]'
+                            )
+                            .forEach(function(referencingElement) {
+                                if (window.getComputedStyle(referencingElement).display !== 'none') {
+                                    visible = true;
+                                }
+                            });
+                    }
+
+                    if (visible && strict) {
+                        let parent = element.parentElement;
+                        while (parent) {
+                            if (optionalAriaHidden(parent, strict)) {
+                                visible = false;
+                                break;
+                            }
+                            parent = parent.parentElement;
+                        }
+                    }
+
+                    return visible;
+                }
+
+                window.isA11yVisible = isA11yVisible;
+            `,
+        });
+    });
+
+    test('baseline: hidden element with simple ID referenced by aria-labelledby is AT-visible', async ({
+        page,
+    }) => {
+        const result = await page.evaluate(() => {
+            const el = document.getElementById('simple-label');
+            return window.isA11yVisible(el);
+        });
+        expect(result).toBe(true);
+    });
+
+    test('hidden element with colon ID referenced by aria-labelledby is AT-visible', async ({
+        page,
+    }) => {
+        const result = await page.evaluate(() => {
+            const el = document.getElementById('radix-:rj:-tab-account');
+            return window.isA11yVisible(el);
+        });
+        expect(result).toBe(true);
+    });
+
+    test('hidden element with colon ID referenced by aria-describedby is AT-visible', async ({
+        page,
+    }) => {
+        const result = await page.evaluate(() => {
+            const el = document.getElementById('desc-:r1:-help');
+            return window.isA11yVisible(el);
+        });
+        expect(result).toBe(true);
+    });
+
+    test('hidden element with multiple colons in ID referenced by aria-labelledby is AT-visible', async ({
+        page,
+    }) => {
+        const result = await page.evaluate(() => {
+            const el = document.getElementById('ns:component:instance:42');
+            return window.isA11yVisible(el);
+        });
+        expect(result).toBe(true);
+    });
+
+    test('visible element with colon ID (no aria reference) is AT-visible', async ({ page }) => {
+        const result = await page.evaluate(() => {
+            const el = document.getElementById('colon:visible');
+            return window.isA11yVisible(el);
+        });
+        expect(result).toBe(true);
+    });
+
+    test('hidden element with colon ID and no aria reference is NOT AT-visible', async ({
+        page,
+    }) => {
+        const result = await page.evaluate(() => {
+            const el = document.getElementById('colon:hidden');
+            return window.isA11yVisible(el);
+        });
+        expect(result).toBe(false);
+    });
+});

package/test/playwright/fixtures/colon-id-a11y-visible.html

@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>isA11yVisible - Colon ID Test Fixtures</title>
+  <style>
+    .sr-only {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
+    }
+  </style>
+</head>
+<body>
+  <!-- Standard ID: baseline reference -->
+  <span id="simple-label" class="sr-only" style="display:none">Account settings</span>
+  <button aria-labelledby="simple-label">Settings</button>
+
+  <!-- Colon-containing ID: Radix UI style -->
+  <span id="radix-:rj:-tab-account" class="sr-only" style="display:none">Account tab</span>
+  <button aria-labelledby="radix-:rj:-tab-account">Account</button>
+
+  <!-- Colon-containing ID: aria-describedby -->
+  <span id="desc-:r1:-help" class="sr-only" style="display:none">Help text for input</span>
+  <input aria-describedby="desc-:r1:-help" type="text" />
+
+  <!-- Multiple colons -->
+  <span id="ns:component:instance:42" class="sr-only" style="display:none">Namespaced label</span>
+  <div aria-labelledby="ns:component:instance:42">Namespaced widget</div>
+
+  <!-- Visible element with colon ID (no aria reference, just visible) -->
+  <div id="colon:visible">Visible colon ID</div>
+
+  <!-- Hidden element with colon ID, no aria reference (should be hidden) -->
+  <div id="colon:hidden" style="display:none">Hidden colon ID</div>
+
+  <script>
+    window.testReady = true;
+  </script>
+</body>
+</html>

package/test/shadowDomUtils.test.js

@@ -0,0 +1,248 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+    deepGetElementById,
+    deepQuerySelector,
+    deepQuerySelectorAll,
+} from '../src/shadowDomUtils.js';
+
+describe('shadowDomUtils', () => {
+    beforeEach(() => {
+        document.body.innerHTML = '';
+    });
+
+    // =========================================================================
+    // Batch 1: deepGetElementById — basic cases
+    // =========================================================================
+    describe('deepGetElementById', () => {
+        it('should return null when root is null', () => {
+            expect(deepGetElementById(null, 'foo')).toBeNull();
+        });
+
+        it('should return null when id is null or empty', () => {
+            expect(deepGetElementById(document, null)).toBeNull();
+            expect(deepGetElementById(document, '')).toBeNull();
+        });
+
+        it('should find an element in the light DOM', () => {
+            document.body.innerHTML = '<div id="target">Hello</div>';
+            const result = deepGetElementById(document, 'target');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Hello');
+        });
+
+        it('should find an element inside an open shadow root', () => {
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const inner = document.createElement('span');
+            inner.id = 'shadow-target';
+            inner.textContent = 'Inside shadow';
+            shadow.appendChild(inner);
+
+            const result = deepGetElementById(document, 'shadow-target');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Inside shadow');
+        });
+
+        it('should find an element in a nested shadow root', () => {
+            const host1 = document.createElement('div');
+            document.body.appendChild(host1);
+            const shadow1 = host1.attachShadow({ mode: 'open' });
+
+            const host2 = document.createElement('div');
+            shadow1.appendChild(host2);
+            const shadow2 = host2.attachShadow({ mode: 'open' });
+
+            const inner = document.createElement('span');
+            inner.id = 'nested-target';
+            inner.textContent = 'Nested';
+            shadow2.appendChild(inner);
+
+            const result = deepGetElementById(document, 'nested-target');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Nested');
+        });
+
+        it('should return null when element is not found anywhere', () => {
+            document.body.innerHTML = '<div id="other">Other</div>';
+            expect(deepGetElementById(document, 'nonexistent')).toBeNull();
+        });
+
+        it('should prefer light DOM match (fast path)', () => {
+            // Light DOM element
+            document.body.innerHTML = '<div id="dup">Light</div>';
+
+            // Also put one in shadow DOM
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const inner = document.createElement('span');
+            inner.id = 'dup';
+            inner.textContent = 'Shadow';
+            shadow.appendChild(inner);
+
+            const result = deepGetElementById(document, 'dup');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Light');
+        });
+
+        it('should work when root is a ShadowRoot', () => {
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const inner = document.createElement('span');
+            inner.id = 'sr-target';
+            inner.textContent = 'Direct';
+            shadow.appendChild(inner);
+
+            const result = deepGetElementById(shadow, 'sr-target');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Direct');
+        });
+    });
+
+    // =========================================================================
+    // Batch 3-4: deepQuerySelector
+    // =========================================================================
+    describe('deepQuerySelector', () => {
+        it('should return null when root is null', () => {
+            expect(deepQuerySelector(null, 'div')).toBeNull();
+        });
+
+        it('should return null when selector is null or empty', () => {
+            expect(deepQuerySelector(document, null)).toBeNull();
+            expect(deepQuerySelector(document, '')).toBeNull();
+        });
+
+        it('should find an element in the light DOM', () => {
+            document.body.innerHTML = '<label for="name">Name</label>';
+            const result = deepQuerySelector(document, 'label[for="name"]');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Name');
+        });
+
+        it('should find a label[for] inside a shadow root', () => {
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const label = document.createElement('label');
+            label.setAttribute('for', 'email');
+            label.textContent = 'Email';
+            shadow.appendChild(label);
+
+            const result = deepQuerySelector(document, 'label[for="email"]');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Email');
+        });
+
+        it('should find an element in a nested shadow root', () => {
+            const host1 = document.createElement('div');
+            document.body.appendChild(host1);
+            const shadow1 = host1.attachShadow({ mode: 'open' });
+
+            const host2 = document.createElement('div');
+            shadow1.appendChild(host2);
+            const shadow2 = host2.attachShadow({ mode: 'open' });
+
+            const el = document.createElement('span');
+            el.className = 'deep-nested';
+            el.textContent = 'Found';
+            shadow2.appendChild(el);
+
+            const result = deepQuerySelector(document, '.deep-nested');
+            expect(result).not.toBeNull();
+            expect(result.textContent).toBe('Found');
+        });
+
+        it('should return null when no match is found', () => {
+            document.body.innerHTML = '<div>Nothing matching</div>';
+            expect(deepQuerySelector(document, '.nonexistent')).toBeNull();
+        });
+
+        it('should prefer light DOM match (fast path)', () => {
+            document.body.innerHTML = '<span class="item">Light</span>';
+
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const inner = document.createElement('span');
+            inner.className = 'item';
+            inner.textContent = 'Shadow';
+            shadow.appendChild(inner);
+
+            const result = deepQuerySelector(document, '.item');
+            expect(result.textContent).toBe('Light');
+        });
+    });
+
+    // =========================================================================
+    // Batch 5-6: deepQuerySelectorAll
+    // =========================================================================
+    describe('deepQuerySelectorAll', () => {
+        it('should return empty array when root is null', () => {
+            expect(deepQuerySelectorAll(null, 'div')).toEqual([]);
+        });
+
+        it('should return empty array when selector is null or empty', () => {
+            expect(deepQuerySelectorAll(document, null)).toEqual([]);
+            expect(deepQuerySelectorAll(document, '')).toEqual([]);
+        });
+
+        it('should find elements in the light DOM', () => {
+            document.body.innerHTML = '<div class="x">A</div><div class="x">B</div>';
+            const results = deepQuerySelectorAll(document, '.x');
+            expect(results).toHaveLength(2);
+        });
+
+        it('should collect elements from multiple shadow roots', () => {
+            document.body.innerHTML = '<span class="item">Light</span>';
+
+            const host1 = document.createElement('div');
+            document.body.appendChild(host1);
+            const shadow1 = host1.attachShadow({ mode: 'open' });
+            const inner1 = document.createElement('span');
+            inner1.className = 'item';
+            shadow1.appendChild(inner1);
+
+            const host2 = document.createElement('div');
+            document.body.appendChild(host2);
+            const shadow2 = host2.attachShadow({ mode: 'open' });
+            const inner2 = document.createElement('span');
+            inner2.className = 'item';
+            shadow2.appendChild(inner2);
+
+            const results = deepQuerySelectorAll(document, '.item');
+            expect(results).toHaveLength(3);
+        });
+
+        it('should collect from nested shadow roots', () => {
+            const host1 = document.createElement('div');
+            document.body.appendChild(host1);
+            const shadow1 = host1.attachShadow({ mode: 'open' });
+
+            const host2 = document.createElement('div');
+            shadow1.appendChild(host2);
+            const shadow2 = host2.attachShadow({ mode: 'open' });
+
+            const inner = document.createElement('span');
+            inner.className = 'nested-item';
+            shadow2.appendChild(inner);
+
+            const results = deepQuerySelectorAll(document, '.nested-item');
+            expect(results).toHaveLength(1);
+            expect(results[0].className).toBe('nested-item');
+        });
+
+        it('should return an array (not NodeList)', () => {
+            document.body.innerHTML = '<div class="y">A</div>';
+            const results = deepQuerySelectorAll(document, '.y');
+            expect(Array.isArray(results)).toBe(true);
+        });
+
+        it('should return empty array when nothing matches', () => {
+            document.body.innerHTML = '<div>Nothing</div>';
+            const results = deepQuerySelectorAll(document, '.missing');
+            expect(results).toHaveLength(0);
+        });
+    });
+});

package/test/testContrast.test.js

@@ -95,18 +95,18 @@ describe('testContrast', () => {
         expect(testContrast(div)).toBe(true);
     });
 
-    it('should skip elements with a background image', () => {
+    it('should return null for elements with a background image (cannot determine)', () => {
         const div = document.createElement('div');
         div.textContent = 'Text with background image';
         div.style.color = 'rgb(0, 0, 0)';
         div.style.backgroundImage = 'url(image.jpg)';
         document.body.appendChild(div);
 
-        // Should skip because contrast can't be reliably tested against background images
-        expect(testContrast(div)).toBe(true);
+        // Should return null because contrast can't be reliably tested against background images
+        expect(testContrast(div)).toBe(null);
     });
 
-    it('should skip elements whose ancestor has a background image', () => {
+    it('should return null for elements whose ancestor has a background image (cannot determine)', () => {
         const parent = document.createElement('div');
         parent.style.backgroundImage = 'url(bg.jpg)';
 
@@ -118,7 +118,7 @@ describe('testContrast', () => {
         parent.appendChild(child);
         document.body.appendChild(parent);
 
-        expect(testContrast(child)).toBe(true);
+        expect(testContrast(child)).toBe(null);
     });
 
     it('should not skip elements with opaque background over ancestor background image', () => {
@@ -138,6 +138,43 @@ describe('testContrast', () => {
         expect(testContrast(child)).toBe(true);
     });
 
+    it('should return null for elements with CSS filter (cannot determine)', () => {
+        const div = document.createElement('div');
+        div.textContent = 'Filtered text';
+        div.style.color = 'rgb(0, 0, 0)';
+        div.style.backgroundColor = 'rgb(255, 255, 255)';
+        div.style.filter = 'brightness(0.5)';
+        document.body.appendChild(div);
+
+        expect(testContrast(div)).toBe(null);
+    });
+
+    it('should return null for elements with mix-blend-mode (cannot determine)', () => {
+        const div = document.createElement('div');
+        div.textContent = 'Blended text';
+        div.style.color = 'rgb(0, 0, 0)';
+        div.style.backgroundColor = 'rgb(255, 255, 255)';
+        div.style.mixBlendMode = 'multiply';
+        document.body.appendChild(div);
+
+        expect(testContrast(div)).toBe(null);
+    });
+
+    it('should return null when ancestor has CSS filter (cannot determine)', () => {
+        const parent = document.createElement('div');
+        parent.style.filter = 'invert(1)';
+
+        const child = document.createElement('div');
+        child.textContent = 'Child of filtered parent';
+        child.style.color = 'rgb(0, 0, 0)';
+        child.style.backgroundColor = 'rgb(255, 255, 255)';
+
+        parent.appendChild(child);
+        document.body.appendChild(parent);
+
+        expect(testContrast(child)).toBe(null);
+    });
+
     it('should handle invisible elements', () => {
         const div = document.createElement('div');
         div.textContent = 'Hidden text';

package/todo.md

@@ -6,6 +6,7 @@ _No pending tasks_
 
 ## Completed
 
-- ✅ Test coverage improvements (87.69% line coverage, 82.11% branch coverage)
+- ✅ Test coverage improvements (89.04% line coverage, 84.37% branch coverage)
 - ✅ Playwright integration for CSS pseudo-element tests
-- ✅ 963 total tests passing (943 JSDOM + 20 Playwright)
+- ✅ 1121 total tests passing (1101 JSDOM + 20 Playwright)
+- ✅ v2.2.0 release (issues #57, #62, #63, #64, #67, #68, #69, #70, #71, #72)