@afixt/test-utils 2.2.0 → 2.3.0

package/.claude/settings.local.json

@@ -18,8 +18,7 @@
       "Bash(node:*)",
       "Bash(npx vitest run:*)",
       "Bash(1)",
-      "Bash(npm run test:playwright:css:*)",
-      "Bash(gh issue:*)"
+      "Bash(npm run test:playwright:css:*)"
     ]
   },
   "enableAllProjectMcpServers": false

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.2.0",
+    "version": "2.3.0",
     "description": "Various utilities for accessibility testing",
     "main": "src/index.js",
     "scripts": {

package/src/domUtils.js

@@ -6,6 +6,7 @@ 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.
@@ -109,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 => {
@@ -119,7 +120,7 @@ const domUtils = {
                 duplicates.push(id);
             }
         });
-        return duplicates.map(id => document.querySelector(`#${cssEscape(id)}`));
+        return duplicates.map(id => deepQuerySelector(document, `#${cssEscape(id)}`));
     },
 
     /**
@@ -176,7 +177,7 @@ const domUtils = {
         const escaped = cssEscape(id);
 
         // Direct attribute references
-        if (document.querySelector('[for="' + escaped + '"]')) {
+        if (deepQuerySelector(document, '[for="' + escaped + '"]')) {
             return true;
         }
 
@@ -189,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)) {
@@ -201,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)) {
@@ -221,7 +222,7 @@ const domUtils = {
         }
 
         // list attribute on input elements
-        if (document.querySelector('input[list="' + escaped + '"]')) {
+        if (deepQuerySelector(document, 'input[list="' + escaped + '"]')) {
             return true;
         }
 

package/src/formUtils.js

@@ -4,6 +4,7 @@
  */
 
 const { isHiddenFromAT } = require('./domUtils.js');
+const { deepGetElementById } = require('./shadowDomUtils.js');
 
 const formUtils = {
     /**
@@ -51,7 +52,7 @@ 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]);
+                const labelEl = deepGetElementById(document, ids[i]);
                 if (labelEl && !isHiddenFromAT(labelEl) && labelEl.textContent.trim()) {
                     return true;
                 }

package/src/getAccessibleName.js

@@ -8,6 +8,7 @@ const {
 } = 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
@@ -58,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;
             }
@@ -109,12 +110,15 @@ function getAccessibleName(element) {
         )
     ) {
         // first we choose the explicit relationship over all others.
-        if (element.id && document.querySelector('label[for="' + cssEscape(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="' + cssEscape(id) + '"]');
+            label = deepQuerySelector(document, 'label[for="' + cssEscape(id) + '"]');
             if (label) {
                 return getAccessibleText(label);
             }
@@ -224,11 +228,14 @@ function getAccessibleName(element) {
         )
     ) {
         // first we choose the explicit relationship over all others.
-        if (element.id && document.querySelector('label[for="' + cssEscape(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="' + cssEscape(id) + '"]');
+            label = deepQuerySelector(document, 'label[for="' + cssEscape(id) + '"]');
             if (label) {
                 return getAccessibleText(label);
             }
@@ -373,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="' + cssEscape(element.id) + '"]');
+                const label = deepQuerySelector(
+                    document,
+                    'label[for="' + cssEscape(element.id) + '"]'
+                );
                 if (label && strlen(getAccessibleText(label)) > 0) {
                     return getAccessibleText(label);
                 }

package/src/getImageText.js

@@ -29,7 +29,11 @@ async function getImageText(imagePath, options = {}) {
             // 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 });
+        } = 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,6 +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).
@@ -71,13 +72,14 @@ function isA11yVisible(element, strict = false) {
     // 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~="${escapedId}"], *[aria-describedby~="${escapedId}"]`)
-        .forEach(referencingElement => {
-            if (window.getComputedStyle(referencingElement).display !== 'none') {
-                visible = true;
-            }
-        });
+    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/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/test/domUtils.test.js

@@ -1079,4 +1079,36 @@ describe('domUtils', () => {
             expect(domUtils.getHeadingLevel(el)).toBeNull();
         });
     });
+
+    describe('shadow DOM integration', () => {
+        it('isIdReferenced should find 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', 'shadow-ref-target');
+            shadow.appendChild(label);
+
+            expect(domUtils.isIdReferenced('shadow-ref-target')).toBe(true);
+        });
+
+        it('getElementsWithDuplicateIds should detect duplicate IDs across shadow roots', () => {
+            // Light DOM element with id="dup"
+            const div1 = document.createElement('div');
+            div1.id = 'dup';
+            document.body.appendChild(div1);
+
+            // Shadow DOM element with same id="dup"
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const div2 = document.createElement('div');
+            div2.id = 'dup';
+            shadow.appendChild(div2);
+
+            const duplicates = domUtils.getElementsWithDuplicateIds();
+            expect(duplicates.length).toBe(1);
+            expect(duplicates[0].id).toBe('dup');
+        });
+    });
 });

package/test/formUtils.test.js

@@ -357,4 +357,25 @@ describe('formUtils', () => {
             expect(text.trim()).toBe('');
         });
     });
+
+    describe('shadow DOM integration', () => {
+        it('hasExplicitAccessibleName should find aria-labelledby target inside shadow root', () => {
+            // Create shadow host with label element inside
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const labelEl = document.createElement('span');
+            labelEl.id = 'shadow-group-label';
+            labelEl.textContent = 'Group Name';
+            shadow.appendChild(labelEl);
+
+            // Create an element in light DOM referencing the shadow label
+            const group = document.createElement('div');
+            group.setAttribute('role', 'radiogroup');
+            group.setAttribute('aria-labelledby', 'shadow-group-label');
+            document.body.appendChild(group);
+
+            expect(formUtils.hasExplicitAccessibleName(group)).toBe(true);
+        });
+    });
 });

package/test/getAccessibleName.test.js

@@ -511,4 +511,43 @@ describe('getAccessibleName', () => {
             expect(getAccessibleName(button)).toBe(false);
         });
     });
+
+    describe('shadow DOM integration', () => {
+        it('should resolve aria-labelledby referencing an element inside a shadow root', () => {
+            // Create a shadow host with the label inside
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const labelSpan = document.createElement('span');
+            labelSpan.id = 'shadow-label';
+            labelSpan.textContent = 'Shadow Label';
+            shadow.appendChild(labelSpan);
+
+            // Create the button in light DOM that references the shadow label
+            const button = document.createElement('button');
+            button.setAttribute('aria-labelledby', 'shadow-label');
+            document.body.appendChild(button);
+
+            expect(getAccessibleName(button)).toBe('Shadow Label');
+        });
+
+        it('should resolve label[for] inside a shadow root for text inputs', () => {
+            // Create a shadow host with the label inside
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const label = document.createElement('label');
+            label.setAttribute('for', 'shadow-input');
+            label.textContent = 'Shadow Input Label';
+            shadow.appendChild(label);
+
+            // Create the input in light DOM
+            const input = document.createElement('input');
+            input.type = 'text';
+            input.id = 'shadow-input';
+            document.body.appendChild(input);
+
+            expect(getAccessibleName(input)).toBe('Shadow Input Label');
+        });
+    });
 });

package/test/isA11yVisible.test.js

@@ -269,4 +269,27 @@ describe('isA11yVisible', () => {
         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/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/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)