@afixt/test-utils 1.2.3 → 2.0.0

package/src/domUtils.js

@@ -1,3 +1,12 @@
+const {
+    VALID_ARIA_NESTING,
+    LANDMARK_TAGS,
+    LANDMARK_ROLES,
+    SEMANTIC_CONTAINER_TAGS,
+    SEMANTIC_CONTAINER_ROLES,
+    INTERACTIVE_HANDLER_ATTRIBUTES,
+} = require('./constants.js');
+
 const domUtils = {
     /**
      * Checks if the specified element has the given attribute.
@@ -250,21 +259,6 @@ const domUtils = {
      * @returns {boolean} True if this is a valid ARIA nesting pattern
      */
     isValidAriaNesting(parent, child) {
-        const VALID_ARIA_NESTING = {
-            listbox: ['option'],
-            menu: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
-            menubar: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
-            menuitem: ['menu', 'menubar'],
-            tablist: ['tab'],
-            tree: ['treeitem', 'group'],
-            treeitem: ['group', 'tree'],
-            grid: ['gridcell', 'row', 'rowgroup'],
-            row: ['gridcell', 'columnheader', 'rowheader', 'cell'],
-            rowgroup: ['row'],
-            radiogroup: ['radio'],
-            combobox: ['listbox', 'textbox', 'tree', 'grid', 'dialog'],
-        };
-
         const parentRole = (parent.getAttribute('role') || '').toLowerCase();
         const childRole = (child.getAttribute('role') || '').toLowerCase();
 
@@ -287,14 +281,7 @@ const domUtils = {
      * @returns {boolean} True if element has interactive handlers
      */
     hasInteractiveHandler(element) {
-        return (
-            element.hasAttribute('onclick') ||
-            element.hasAttribute('onmousedown') ||
-            element.hasAttribute('onmouseup') ||
-            element.hasAttribute('ontouchstart') ||
-            element.hasAttribute('onkeydown') ||
-            element.hasAttribute('onkeyup')
-        );
+        return INTERACTIVE_HANDLER_ATTRIBUTES.some(attr => element.hasAttribute(attr));
     },
 
     /**
@@ -321,22 +308,11 @@ const domUtils = {
      * @returns {boolean} True if element is a landmark
      */
     isLandmark(element) {
-        const landmarkTags = ['NAV', 'MAIN', 'HEADER', 'FOOTER', 'ASIDE', 'SECTION'];
-        const landmarkRoles = [
-            'navigation',
-            'main',
-            'banner',
-            'contentinfo',
-            'complementary',
-            'region',
-            'search',
-            'form',
-        ];
-        if (landmarkTags.includes(element.tagName)) {
+        if (LANDMARK_TAGS.includes(element.tagName)) {
             return true;
         }
         const role = (element.getAttribute('role') || '').toLowerCase();
-        return landmarkRoles.includes(role);
+        return LANDMARK_ROLES.includes(role);
     },
 
     /**
@@ -345,10 +321,13 @@ const domUtils = {
      * @returns {HTMLElement|null} The nearest semantic container
      */
     getSemanticContainer(el) {
-        const containerTags = ['ARTICLE', 'SECTION', 'LI', 'TD', 'TH', 'BLOCKQUOTE', 'FIGURE'];
         let ancestor = el.parentElement;
         while (ancestor && ancestor !== document.body) {
-            if (containerTags.includes(ancestor.tagName) || ancestor.hasAttribute('role')) {
+            if (SEMANTIC_CONTAINER_TAGS.includes(ancestor.tagName)) {
+                return ancestor;
+            }
+            const role = (ancestor.getAttribute('role') || '').toLowerCase();
+            if (role && SEMANTIC_CONTAINER_ROLES.includes(role)) {
                 return ancestor;
             }
             ancestor = ancestor.parentElement;

package/src/formUtils.js

@@ -35,8 +35,13 @@ const formUtils = {
 
     /**
      * Checks if an element has an explicit accessible name via aria-labelledby, aria-label, or title.
-     * Text content is NOT checked (useful for containers like radiogroup/group where
-     * text content is not a valid accessible name source).
+     *
+     * Unlike getAccessibleName/hasAccessibleName, this deliberately excludes text content.
+     * This is important for container roles (radiogroup, group) where text content of
+     * child elements is not a valid accessible name source per the ARIA spec — these
+     * roles require an author-provided label.
+     *
+     * Used by isProperlyGrouped() to enforce that ARIA groups have explicit labels.
      * @param {Element} element - The element to check
      * @returns {boolean} True if element has an explicit accessible name
      */
@@ -126,28 +131,6 @@ const formUtils = {
         return document.body;
     },
 
-    /**
-     * Check if a native form element has an associated label.
-     * Checks label[for], wrapping label, aria-label, aria-labelledby, and title.
-     * @param {HTMLElement} element - The element to check
-     * @returns {boolean} True if the element has an associated label
-     */
-    hasAssociatedLabel(element) {
-        if (element.id) {
-            const label = document.querySelector('label[for="' + element.id + '"]');
-            if (label && label.textContent.trim()) {
-                return true;
-            }
-        }
-
-        const parentLabel = element.closest('label');
-        if (parentLabel && parentLabel.textContent.trim()) {
-            return true;
-        }
-
-        return false;
-    },
-
     /**
      * Get the text content of an element, excluding form control children.
      * Useful for wrapped labels like <label><input type="checkbox"> Remember me</label>

package/src/getAccessibleName.js

@@ -1,5 +1,11 @@
 const { isEmpty } = require('./stringUtils.js');
 const { getAccessibleText } = require('./getAccessibleText.js');
+const {
+    TEXT_ROLES,
+    NON_VISIBLE_SELECTORS,
+    LANDMARK_ROLES,
+    LANDMARK_ELEMENT_MAP,
+} = require('./constants.js');
 
 /**
  * Gets the accessible name of an element according to the accessible name calculation algorithm
@@ -64,28 +70,8 @@ function getAccessibleName(element) {
     // We check all of those here.
     if (element.hasAttribute('role')) {
         const roleValue = element.getAttribute('role');
-        const textRoles = [
-            'button',
-            'checkbox',
-            'columnheader',
-            'gridcell',
-            'heading',
-            'link',
-            'listitem',
-            'menuitem',
-            'menuitemcheckbox',
-            'menuitemradio',
-            'option',
-            'radio',
-            'row',
-            'rowgroup',
-            'rowheader',
-            'tab',
-            'tooltip',
-            'treeitem',
-        ];
-
-        if (textRoles.includes(roleValue)) {
+
+        if (TEXT_ROLES.includes(roleValue)) {
             // Use getAccessibleText which handles both text nodes and
             // image alt text in the subtree (not just textContent)
             const text = getAccessibleText(element);
@@ -456,23 +442,23 @@ function getAccessibleName(element) {
     }
 
     // STEP 15: Landmark elements that require explicit accessible names
-    // Navigation landmarks (nav elements and role="navigation") should NOT get
-    // their accessible name from text content - they require explicit labeling
-    // via aria-labelledby, aria-label, or title attribute.
+    // Landmark roles do NOT support "Name From: contents" per WAI-ARIA spec.
+    // They only support "Name From: author" (aria-labelledby, aria-label, title).
     // Since steps 1 & 2 already checked aria-labelledby and aria-label,
     // we only need to check title here, then return false.
-    const isNavigation =
-        element.tagName.toLowerCase() === 'nav' || element.getAttribute('role') === 'navigation';
+    const tagName = element.tagName.toLowerCase();
+    const role = element.getAttribute('role');
+    const isLandmark = LANDMARK_ROLES.includes(role) || tagName in LANDMARK_ELEMENT_MAP;
 
-    if (isNavigation) {
-        // Title attribute is valid for navigation landmarks
+    if (isLandmark) {
+        // Title attribute is valid for landmark elements
         if (element.hasAttribute('title')) {
             const titleValue = element.getAttribute('title');
             if (strlen(titleValue) > 0) {
                 return titleValue;
             }
         }
-        // Navigation landmarks do not get accessible name from text content
+        // Landmark elements do not get accessible name from text content
         return false;
     }
 
@@ -499,33 +485,11 @@ function isNotVisible(element) {
         return true;
     }
 
-    // These elements are inherently not visible
-    // Note: 'area' is NOT included here because area elements DO have accessible names
+    // Note: 'area' is filtered out because area elements DO have accessible names
     // via the alt attribute and should participate in accessible name calculation
-    const nonVisibleSelectors = [
-        'base',
-        'head',
-        'meta',
-        'title',
-        'link',
-        'style',
-        'script',
-        'br',
-        'nobr',
-        'col',
-        'embed',
-        'input[type="hidden"]',
-        'keygen',
-        'source',
-        'track',
-        'wbr',
-        'datalist',
-        'param',
-        'noframes',
-        'ruby > rp',
-    ];
-
-    if (nonVisibleSelectors.some(selector => matchesSelector(element, selector))) {
+    const nonVisibleSelectorsWithoutArea = NON_VISIBLE_SELECTORS.filter(s => s !== 'area');
+
+    if (nonVisibleSelectorsWithoutArea.some(selector => matchesSelector(element, selector))) {
         return true; // Not visible in accessibility tree
     }
 

package/src/getCSSGeneratedContent.js

@@ -25,6 +25,8 @@ function extractMeaningfulContent(rawValue) {
  * not the element's own text content. Empty, whitespace-only, and blank content
  * values are filtered out as they do not convey meaningful information.
  *
+ * Use getGeneratedContent() if you need ::before + textContent + ::after combined.
+ *
  * @param {Element} el - The DOM element to check
  * @param {string} [pseudoElement='both'] - Which pseudo-element to check ('before', 'after', or 'both')
  * @returns {string|boolean} The generated content as a string or false if none exists

package/src/getFocusableElements.js

@@ -1,3 +1,5 @@
+const { FOCUSABLE_SELECTORS } = require('./constants.js');
+
 /**
  * Gets all focusable elements within the specified container element.
  * @param  {Element} el - the element to be tested
@@ -7,33 +9,22 @@ function getFocusableElements(el) {
     if (!el) {
         throw new Error('Container element is required');
     }
-    
-    const focusableSelectors = [
-        "a[href]",
-        "area",
-        "button",
-        "select",
-        "textarea",
-        'input:not([type="hidden"])',
-        "[tabindex]",
-    ];
 
-    return Array.from(
-        el.querySelectorAll(focusableSelectors.join(", "))
-    ).filter((element) => {
-        const tabindex = element.getAttribute("tabindex");
+    return Array.from(el.querySelectorAll(FOCUSABLE_SELECTORS.join(', '))).filter(element => {
+        const tabindex = element.getAttribute('tabindex');
         const hasValidTabindex = tabindex === null || parseInt(tabindex, 10) >= 0;
-        
+
         // Check visibility - handle JSDOM environment where offsetParent might not work correctly
-        const isVisible = element.offsetParent !== null || 
-                          (typeof window !== 'undefined' && 
-                           window.navigator && 
-                           window.navigator.userAgent.includes('jsdom'));
-        
+        const isVisible =
+            element.offsetParent !== null ||
+            (typeof window !== 'undefined' &&
+                window.navigator &&
+                window.navigator.userAgent.includes('jsdom'));
+
         return hasValidTabindex && isVisible;
     });
 }
 
 module.exports = {
-    getFocusableElements
+    getFocusableElements,
 };

package/src/getGeneratedContent.js

@@ -1,19 +1,26 @@
+const { getCSSGeneratedContent } = require('./getCSSGeneratedContent.js');
+
 /**
- * Get the generated content for an element (`::before`, `::after`, and inner content).
+ * Get all visible text for an element, including CSS-generated ::before and ::after content
+ * combined with the element's own text content.
+ *
+ * Unlike getCSSGeneratedContent (which returns only pseudo-element content),
+ * this function returns the full visible text: ::before + textContent + ::after.
+ *
  * @param {Element} el - The DOM element.
- * @returns {string|boolean} The generated content or `false` if not available.
+ * @returns {string|false} The combined text or false if no content exists.
  */
 function getGeneratedContent(el) {
-    if (!el) return false;
-    const computedStyle = getComputedStyle(el);
-    const before = computedStyle.getPropertyValue("content", "::before") || "";
-    const inner = el.textContent || "";
-    const after = computedStyle.getPropertyValue("content", "::after") || "";
-    return before || inner || after
-        ? `${before} ${inner} ${after}`.trim()
-        : false;
+    if (!el) {
+        return false;
+    }
+    const before = getCSSGeneratedContent(el, 'before') || '';
+    const inner = el.textContent || '';
+    const after = getCSSGeneratedContent(el, 'after') || '';
+    const result = [before, inner, after].filter(Boolean).join(' ').trim();
+    return result || false;
 }
 
 module.exports = {
-    getGeneratedContent
+    getGeneratedContent,
 };

package/src/getImageText.js

@@ -1,17 +1,31 @@
 const Tesseract = require('tesseract.js');
 
+/**
+ * Internal reference to Tesseract.recognize, exposed for test mocking.
+ * @private
+ */
+const _internal = {
+    recognize: Tesseract.recognize,
+};
+
 /**
  * Extracts text from an image using OCR.
  * @param {string} imagePath - The path or URL of the image.
+ * @param {Object} [options={}] - OCR options.
+ * @param {string} [options.lang='eng'] - Tesseract language(s) for OCR (e.g. 'fra', 'eng+deu').
+ * @param {Function|null} [options.logger=console.log] - Logger callback for Tesseract progress. Pass null to disable.
+ * @param {string} [options.corePath] - Custom path to Tesseract core WASM files.
+ * @param {string} [options.langPath] - Custom path to language training data.
+ * @param {string} [options.cachePath] - Custom cache directory path.
  * @returns {Promise<string|false>} Extracted text if found, otherwise false.
  */
-async function getImageText(imagePath) {
+async function getImageText(imagePath, options = {}) {
+    const { lang = 'eng', logger = m => console.log(m), ...tesseractOptions } = options;
+
     try {
-        const { data: { text } } = await Tesseract.recognize(
-            imagePath,
-            'eng', // Language (English)
-            { logger: m => console.log(m) } // Optional logging
-        );
+        const {
+            data: { text },
+        } = await _internal.recognize(imagePath, lang, { logger, ...tesseractOptions });
 
         const extractedText = text.trim();
         return extractedText.length > 0 ? extractedText : false;
@@ -28,5 +42,6 @@ async function getImageText(imagePath) {
 // getImageText('path/to/image.jpg').then(result => console.log(result));
 
 module.exports = {
-    getImageText
+    getImageText,
+    _internal,
 };

package/src/hasValidAriaRole.js

@@ -4,30 +4,22 @@
  * @param {HTMLElement} element - The DOM element to check.
  * @returns {boolean} True if the element has a valid ARIA role, false otherwise.
  */
-function hasValidAriaRole(element) {
-    const validAriaRoles = new Set([
-      "alert", "alertdialog", "button", "checkbox", "dialog", "gridcell", "link",
-      "log", "marquee", "menuitem", "menuitemcheckbox", "menuitemradio", "option",
-      "progressbar", "radio", "scrollbar", "searchbox", "slider", "spinbutton",
-      "status", "switch", "tab", "tabpanel", "textbox", "tooltip", "treeitem",
-      "combobox", "grid", "listbox", "menu", "menubar", "radiogroup", "tablist",
-      "tree", "treegrid", "article", "cell", "columnheader", "definition",
-      "directory", "document", "feed", "figure", "group", "heading", "img",
-      "list", "listitem", "math", "none", "note", "presentation", "row",
-      "rowgroup", "rowheader", "separator", "table", "term", "toolbar",
-      "application", "banner", "complementary", "contentinfo", "form", "main",
-      "navigation", "region", "search", "timer"
-    ]);
+const { VALID_ARIA_ROLES } = require('./constants.js');
 
-    if (!element || typeof element.getAttribute !== 'function') return false;
+function hasValidAriaRole(element) {
+    if (!element || typeof element.getAttribute !== 'function') {
+        return false;
+    }
 
     const roleAttr = element.getAttribute('role');
-    if (!roleAttr) return false;
+    if (!roleAttr) {
+        return false;
+    }
 
     const roles = roleAttr.trim().split(/\s+/);
-    return validAriaRoles.has(roles[0]); // Only check the first role
-  }
+    return VALID_ARIA_ROLES.has(roles[0]); // Only check the first role
+}
 
 module.exports = {
-    hasValidAriaRole
+    hasValidAriaRole,
 };

package/src/index.js

@@ -35,7 +35,7 @@ const isDataTable = require('./isDataTable.js');
 // Visibility and positioning
 const isHidden = require('./isHidden.js');
 const isOffScreen = require('./isOffScreen.js');
-const isVisible = require('./isVisible.js');
+const isA11yVisible = require('./isA11yVisible.js');
 const hasHiddenParent = require('./hasHiddenParent.js');
 
 // Element relationships
@@ -50,7 +50,7 @@ const isFocusable = require('./isFocusable.js');
 const getComputedRole = require('./getComputedRole.js');
 
 // Image utilities
-const getImageText = require('./getImageText.js');
+const { getImageText } = require('./getImageText.js');
 
 // Testing utilities
 const testContrast = require('./testContrast.js');
@@ -101,14 +101,14 @@ module.exports = {
     ...isDataTable,
     ...isHidden,
     ...isOffScreen,
-    ...isVisible,
+    ...isA11yVisible,
     ...hasHiddenParent,
     ...hasParent,
     ...hasAttribute,
     ...getFocusableElements,
     ...isFocusable,
     ...getComputedRole,
-    ...getImageText,
+    getImageText,
     ...testContrast,
     ...testLang,
     ...testOrder,

package/src/interactiveRoles.js

@@ -1,20 +1,3 @@
-const interactiveRoles = [
-    "button",
-    "checkbox",
-    "combobox",
-    "link",
-    "menu",
-    "menuitemcheckbox",
-    "menuitemradio",
-    "radio",
-    "scrollbar",
-    "slider",
-    "spinbutton",
-    "tablist",
-    "textbox",
-    "toolbar",
-    "switch",
-    "tree",
-];
+const { INTERACTIVE_ROLES } = require('./constants.js');
 
-module.exports = interactiveRoles;
+module.exports = INTERACTIVE_ROLES;

package/src/isA11yVisible.js

@@ -0,0 +1,95 @@
+const { NON_VISIBLE_SELECTORS } = require('./constants.js');
+const isHidden = require('./isHidden.js');
+
+/**
+ * Checks if an element is visible to assistive technologies (AT).
+ *
+ * Unlike isHidden (which checks simple visual hiding), this function determines
+ * whether an element is meaningful to screen readers and other AT. Key differences:
+ *
+ * - Elements referenced by aria-labelledby or aria-describedby are considered
+ *   AT-visible even if visually hidden (display:none), because they provide
+ *   accessible names/descriptions to other elements.
+ * - Inherently non-visible elements (script, style, input[type="hidden"], etc.)
+ *   are treated as AT-visible since they carry semantic meaning.
+ * - Parent chain is walked to detect inherited hiding (CSS and aria-hidden in strict mode).
+ *
+ * @param {Element} element - The element to check.
+ * @param {boolean} [strict=false] - When true, also treats aria-hidden="true" (on the
+ *   element or any ancestor) as hidden.
+ * @returns {boolean} True if the element is visible to assistive technologies.
+ */
+function isA11yVisible(element, strict = false) {
+    // Add null check at the beginning
+    if (!element || !(element instanceof Element)) {
+        return false;
+    }
+
+    // Check if element is still connected to the DOM
+    if (!element.isConnected) {
+        return false;
+    }
+
+    const id = element.id;
+    let visible = true;
+
+    if (NON_VISIBLE_SELECTORS.some(selector => element.matches(selector))) {
+        return true;
+    }
+
+    const optionalAriaHidden = (el, strictCheck) =>
+        strictCheck && el.getAttribute('aria-hidden') === 'true';
+
+    // Use isHidden for the element-level check (covers display:none,
+    // visibility:hidden, opacity:0, and the hidden HTML attribute)
+    if (isHidden(element, { checkOpacity: true })) {
+        visible = false;
+    } else {
+        // Walk parent chain for inherited CSS hiding (display, visibility, opacity)
+        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;
+        }
+    }
+
+    // Check element-level aria-hidden in strict mode (when not already hidden by CSS)
+    if (visible && optionalAriaHidden(element, strict)) {
+        visible = false;
+    }
+
+    // Check if element is referenced by aria-labelledby or aria-describedby
+    document
+        .querySelectorAll(`*[aria-labelledby~="${id}"], *[aria-describedby~="${id}"]`)
+        .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) {
+        let parent = element.parentElement;
+        while (parent) {
+            if (optionalAriaHidden(parent, strict)) {
+                visible = false;
+                break;
+            }
+            parent = parent.parentElement;
+        }
+    }
+
+    return visible;
+}
+
+module.exports = {
+    isA11yVisible,
+};

package/src/isAriaAttributesValid.js

@@ -1,63 +1,4 @@
-/**
- * List of valid ARIA attributes based on WAI-ARIA specification.
- * @type {Set<string>}
- */
-const validAriaAttributes = new Set([
-    // ARIA States and Properties
-    'aria-activedescendant',
-    'aria-atomic',
-    'aria-autocomplete',
-    'aria-braillelabel',
-    'aria-brailleroledescription',
-    'aria-busy',
-    'aria-checked',
-    'aria-colcount',
-    'aria-colindex',
-    'aria-colindextext',
-    'aria-colspan',
-    'aria-controls',
-    'aria-current',
-    'aria-describedby',
-    'aria-description',
-    'aria-details',
-    'aria-disabled',
-    'aria-dropeffect',
-    'aria-errormessage',
-    'aria-expanded',
-    'aria-flowto',
-    'aria-grabbed',
-    'aria-haspopup',
-    'aria-hidden',
-    'aria-invalid',
-    'aria-keyshortcuts',
-    'aria-label',
-    'aria-labelledby',
-    'aria-level',
-    'aria-live',
-    'aria-modal',
-    'aria-multiline',
-    'aria-multiselectable',
-    'aria-orientation',
-    'aria-owns',
-    'aria-placeholder',
-    'aria-posinset',
-    'aria-pressed',
-    'aria-readonly',
-    'aria-relevant',
-    'aria-required',
-    'aria-roledescription',
-    'aria-rowcount',
-    'aria-rowindex',
-    'aria-rowindextext',
-    'aria-rowspan',
-    'aria-selected',
-    'aria-setsize',
-    'aria-sort',
-    'aria-valuemax',
-    'aria-valuemin',
-    'aria-valuenow',
-    'aria-valuetext'
-]);
+const { VALID_ARIA_ATTRIBUTES } = require('./constants.js');
 
 /**
  * Checks if a specific ARIA attribute is valid according to the WAI-ARIA specification.
@@ -69,10 +10,10 @@ function isAriaAttributeValid(attributeName) {
     if (!attributeName || typeof attributeName !== 'string') {
         return false;
     }
-    
-    return validAriaAttributes.has(attributeName.toLowerCase());
+
+    return VALID_ARIA_ATTRIBUTES.has(attributeName.toLowerCase());
 }
 
 module.exports = {
-    isAriaAttributeValid
-};
+    isAriaAttributeValid,
+};