@afixt/test-utils 2.5.0 → 2.6.0

package/package.json

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

package/src/getAccessibleText.js

@@ -62,6 +62,11 @@ function getAccessibleText(el, options) {
 function collectSubtreeText(node, visibleOnly) {
     const parts = [];
 
+    // If the node itself has an open shadow root, traverse shadow children first
+    if (node.shadowRoot) {
+        parts.push(...collectSubtreeText(node.shadowRoot, visibleOnly));
+    }
+
     for (let child = node.firstChild; child; child = child.nextSibling) {
         if (child.nodeType === Node.TEXT_NODE) {
             const text = child.nodeValue.trim();
@@ -130,7 +135,7 @@ function collectSubtreeText(node, visibleOnly) {
                 }
             }
 
-            // Recurse into other element children
+            // Recurse into other element children (shadow roots handled at top of function)
             parts.push(...collectSubtreeText(child, visibleOnly));
         }
     }

package/src/shadowDomUtils.js

@@ -111,8 +111,91 @@ function deepQuerySelectorAll(root, selector) {
     return results;
 }
 
+/**
+ * Recursively extracts text content from an element, crossing open shadow
+ * DOM boundaries.  For closed shadow roots the host element's light-DOM
+ * `textContent` is used (the shadow internals are inaccessible by spec).
+ *
+ * @param {Element} element - The element to extract text from.
+ * @returns {string} The concatenated, whitespace-normalised text.
+ */
+function getDeepTextContent(element) {
+    if (!element) {
+        return '';
+    }
+
+    const parts = [];
+
+    /**
+     * Walk every child node, descending into open shadow roots.
+     * @param {Node} node - Current node in the walk.
+     */
+    function walk(node) {
+        // If this element has an open shadow root, walk its shadow children
+        // instead of (or in addition to) the light DOM children.
+        if (node.nodeType === Node.ELEMENT_NODE && node.shadowRoot) {
+            for (let sc = node.shadowRoot.firstChild; sc; sc = sc.nextSibling) {
+                walk(sc);
+            }
+            // Also walk slotted light-DOM children
+            for (let lc = node.firstChild; lc; lc = lc.nextSibling) {
+                walk(lc);
+            }
+            return;
+        }
+
+        if (node.nodeType === Node.TEXT_NODE) {
+            const text = node.nodeValue;
+            if (text && text.trim()) {
+                parts.push(text.trim());
+            }
+            return;
+        }
+
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            for (let child = node.firstChild; child; child = child.nextSibling) {
+                walk(child);
+            }
+        }
+    }
+
+    walk(element);
+    return parts.join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Checks whether an element or any of its descendants is a custom element
+ * (has a hyphen in its tag name per the HTML spec).
+ *
+ * Useful for detecting elements that *may* contain shadow DOM content
+ * which is inaccessible via `textContent` or `querySelectorAll`.
+ *
+ * @param {Element} element - The element to inspect.
+ * @returns {boolean} True if the element itself or a descendant is a custom element.
+ */
+function hasCustomElementDescendant(element) {
+    if (!element) {
+        return false;
+    }
+
+    if (element.tagName && element.tagName.indexOf('-') !== -1) {
+        return true;
+    }
+
+    const children = element.querySelectorAll ? element.querySelectorAll('*') : [];
+    for (let i = 0; i < children.length; i++) {
+        if (children[i].tagName && children[i].tagName.indexOf('-') !== -1) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
 module.exports = {
     deepGetElementById,
     deepQuerySelector,
     deepQuerySelectorAll,
+    getDeepTextContent,
+    hasCustomElementDescendant,
 };

package/src/stringUtils.js

@@ -167,6 +167,8 @@ const stringUtils = (function () {
 
     /**
      * Get the actual visible text content of an element, ignoring aria-label.
+     * Traverses open shadow DOM boundaries so that text rendered inside
+     * web components is included.
      * @param {Element} element - The DOM element
      * @returns {string} The visible text content
      */
@@ -174,7 +176,14 @@ const stringUtils = (function () {
         if (!element) {
             return '';
         }
-        return (element.textContent || '').trim();
+        // Fast path: no shadow roots in subtree
+        const text = (element.textContent || '').trim();
+        if (text) {
+            return text;
+        }
+        // Slow path: element may contain custom elements with shadow DOM
+        const { getDeepTextContent } = require('./shadowDomUtils.js');
+        return getDeepTextContent(element);
     }
 
     /**

package/test/getAccessibleText.test.js

@@ -548,4 +548,52 @@ describe('getAccessibleText', () => {
             expect(result).toBe('Valid Text');
         });
     });
+
+    describe('shadow DOM traversal', () => {
+        it('should extract text from 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.textContent = 'Shadow text';
+            shadow.appendChild(inner);
+
+            expect(getAccessibleText(host)).toBe('Shadow text');
+        });
+
+        it('should extract text 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.textContent = 'Deeply nested text';
+            shadow2.appendChild(inner);
+
+            expect(getAccessibleText(host1)).toBe('Deeply nested text');
+        });
+
+        it('should prefer aria-label over shadow DOM text', () => {
+            const host = document.createElement('div');
+            host.setAttribute('aria-label', 'Accessible Label');
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const inner = document.createElement('span');
+            inner.textContent = 'Shadow text';
+            shadow.appendChild(inner);
+
+            expect(getAccessibleText(host)).toBe('Accessible Label');
+        });
+
+        it('should return empty string for custom element with no content and no shadow root', () => {
+            const el = document.createElement('my-widget');
+            document.body.appendChild(el);
+
+            expect(getAccessibleText(el)).toBe('');
+        });
+    });
 });

package/test/shadowDomUtils.test.js

@@ -3,6 +3,8 @@ import {
     deepGetElementById,
     deepQuerySelector,
     deepQuerySelectorAll,
+    getDeepTextContent,
+    hasCustomElementDescendant,
 } from '../src/shadowDomUtils.js';
 
 describe('shadowDomUtils', () => {
@@ -245,4 +247,100 @@ describe('shadowDomUtils', () => {
             expect(results).toHaveLength(0);
         });
     });
+
+    // =========================================================================
+    // getDeepTextContent
+    // =========================================================================
+    describe('getDeepTextContent', () => {
+        it('should return empty string for null', () => {
+            expect(getDeepTextContent(null)).toBe('');
+        });
+
+        it('should return text from light DOM', () => {
+            document.body.innerHTML = '<div>Hello world</div>';
+            const el = document.querySelector('div');
+            expect(getDeepTextContent(el)).toBe('Hello world');
+        });
+
+        it('should return text from 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.textContent = 'Shadow content';
+            shadow.appendChild(inner);
+
+            expect(getDeepTextContent(host)).toBe('Shadow content');
+        });
+
+        it('should return text 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.textContent = 'Deeply nested';
+            shadow2.appendChild(inner);
+
+            expect(getDeepTextContent(host1)).toBe('Deeply nested');
+        });
+
+        it('should return empty string for element with no text', () => {
+            document.body.innerHTML = '<div><img src="test.png"></div>';
+            const el = document.querySelector('div');
+            expect(getDeepTextContent(el)).toBe('');
+        });
+
+        it('should combine text from shadow and light DOM', () => {
+            const host = document.createElement('div');
+            host.textContent = 'Light text';
+            document.body.appendChild(host);
+            const shadow = host.attachShadow({ mode: 'open' });
+            const inner = document.createElement('span');
+            inner.textContent = 'Shadow text';
+            shadow.appendChild(inner);
+
+            const result = getDeepTextContent(host);
+            expect(result).toContain('Shadow text');
+            expect(result).toContain('Light text');
+        });
+    });
+
+    // =========================================================================
+    // hasCustomElementDescendant
+    // =========================================================================
+    describe('hasCustomElementDescendant', () => {
+        it('should return false for null', () => {
+            expect(hasCustomElementDescendant(null)).toBe(false);
+        });
+
+        it('should return false for element with no custom elements', () => {
+            document.body.innerHTML = '<div><span>Text</span></div>';
+            const el = document.querySelector('div');
+            expect(hasCustomElementDescendant(el)).toBe(false);
+        });
+
+        it('should return true when the element itself is a custom element', () => {
+            const el = document.createElement('my-component');
+            document.body.appendChild(el);
+            expect(hasCustomElementDescendant(el)).toBe(true);
+        });
+
+        it('should return true when a descendant is a custom element', () => {
+            document.body.innerHTML = '<div><store-selector-addon></store-selector-addon></div>';
+            const el = document.querySelector('div');
+            expect(hasCustomElementDescendant(el)).toBe(true);
+        });
+
+        it('should return false for elements with hyphens in attributes but not tag names', () => {
+            document.body.innerHTML =
+                '<div data-my-attr="value"><span class="my-class">Text</span></div>';
+            const el = document.querySelector('div');
+            expect(hasCustomElementDescendant(el)).toBe(false);
+        });
+    });
 });