@afixt/test-utils 1.3.0 → 2.0.1

package/BROWSER_TESTING.md

@@ -6,19 +6,19 @@ This project uses **JSDOM** for the main test suite with **Playwright** for CSS
 
 ## Current Status
 
-- **656 tests passing** in JSDOM environment
-- **10 tests passing** in Playwright for CSS pseudo-element support
-- **Total: 666 tests passing** with full coverage
+- **943 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
 
 ### Implementation Complete
 
-✅ JSDOM tests for all standard functionality (656 tests)
-✅ Standalone Playwright tests for CSS pseudo-elements (10 tests)
-✅ All tests now passing with no skipped tests
+✅ JSDOM tests for all standard functionality (943 tests)
+✅ Standalone Playwright tests for CSS pseudo-elements (20 tests)
+✅ 8 CSS pseudo-element tests conditionally skipped in JSDOM, covered by Playwright
 
 ## Solution: Hybrid Testing Approach
 
-The 10 CSS pseudo-element tests now run with standalone Playwright tests that inject browser-compatible code directly into the page. This approach:
+The 20 CSS pseudo-element tests run with standalone Playwright tests that inject browser-compatible code directly into the page. This approach:
 
 - ✅ Works with existing CommonJS source code
 - ✅ Tests real browser CSS pseudo-element behavior
@@ -28,29 +28,33 @@ The 10 CSS pseudo-element tests now run with standalone Playwright tests that in
 ## Running Tests
 
 ### JSDOM Tests (Main Test Suite)
+
 ```bash
-npm test                    # Run all 656 JSDOM tests
+npm test                    # Run all 943 JSDOM tests
 npm run test:coverage       # Run with coverage
 npm run test:watch          # Watch mode
 ```
 
-**Status:** 656 tests passing
+**Status:** 943 tests passing (8 conditionally skipped)
 
 **Pros:**
+
 - ⚡ Very fast execution (~3-4 seconds)
 - 🔧 No browser dependencies needed
 - ✅ Perfect for CI/CD and development
 - ✅ Works with existing CommonJS code
 
 ### Playwright CSS Pseudo-element Tests
+
 ```bash
-npm run test:playwright:css # Run 10 CSS pseudo-element tests
+npm run test:playwright:css # Run 20 CSS pseudo-element tests
 npm run test:all            # Run both JSDOM + Playwright tests
 ```
 
-**Status:** 10 tests passing
+**Status:** 20 tests passing
 
 **Pros:**
+
 - ✅ Real browser CSS pseudo-element support
 - ✅ Tests `::before` and `::after` content properly
 - ✅ Validates `getComputedStyle()` behavior
@@ -59,7 +63,8 @@ npm run test:all            # Run both JSDOM + Playwright tests
 
 The Playwright tests validate the following functionality:
 
-#### getGeneratedContent.js (8 tests)
+#### getGeneratedContent (8 tests)
+
 - ✅ `should return ::before content when present`
 - ✅ `should return ::after content when present`
 - ✅ `should combine ::before, text content, and ::after`
@@ -69,7 +74,21 @@ The Playwright tests validate the following functionality:
 - ✅ `should handle nested elements with generated content`
 - ✅ `should handle content with HTML entities in CSS`
 
-#### hasCSSGeneratedContent.js (2 tests)
+#### getCSSGeneratedContent (10 tests)
+
+- ✅ `should get ::before content`
+- ✅ `should get ::after content`
+- ✅ `should get both ::before and ::after content`
+- ✅ `should handle quoted content`
+- ✅ `should handle URL content`
+- ✅ `should default pseudoElement to both`
+- ✅ `should return false for empty content`
+- ✅ `should return false for content: none`
+- ✅ `should return false for null element`
+- ✅ `should return false for elements with no pseudo-element styles`
+
+#### hasCSSGeneratedContent (2 tests)
+
 - ✅ `should correctly identify elements with ::before content`
 - ✅ `should correctly identify elements with ::after content`
 
@@ -83,7 +102,7 @@ The Playwright tests validate the following functionality:
 
 ### How It Works
 
-The Playwright tests inject browser-compatible versions of `getGeneratedContent` and `hasCSSGeneratedContent` directly into the page using `page.addScriptTag()`. This approach:
+The Playwright tests inject browser-compatible versions of `getGeneratedContent`, `getCSSGeneratedContent`, and `hasCSSGeneratedContent` directly into the page using `page.addScriptTag()`. This approach:
 
 1. Loads an HTML fixture with CSS pseudo-element styles
 2. Injects browser-compatible JavaScript functions
@@ -94,16 +113,17 @@ The Playwright tests inject browser-compatible versions of `getGeneratedContent`
 
 ```json
 {
-  "test": "vitest run",                           // JSDOM tests (656 tests)
-  "test:coverage": "vitest run --coverage",       // JSDOM with coverage
-  "test:playwright:css": "playwright test ...",   // Playwright CSS tests (10 tests)
-  "test:all": "npm run test && npm run test:playwright:css"  // All tests (666 tests)
+    "test": "vitest run", // JSDOM tests (943 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 Coverage
 
-- **76.4% line coverage**
-- **87.53% branch coverage**
-- **666 total tests passing**
-- **100% test completion** (no skipped tests)
+- **87.75% statement coverage**
+- **82.11% branch coverage**
+- **95.58% function coverage**
+- **87.69% line coverage**
+- **963 total tests passing** (943 JSDOM + 20 Playwright)

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.0] - 2026-02-22
+
+### Breaking Changes
+
+- **`isVisible` renamed to `isA11yVisible`** (#26): The exported function `isVisible` has been renamed to `isA11yVisible` to clarify its AT-aware purpose. Update all imports from `isVisible` to `isA11yVisible`.
+
+### Features
+
+- **isHidden**: Expand hidden detection with computed styles and configurable options (`checkAriaHidden`, `checkOpacity`, `checkDimensions`) (#31)
+- **isFocusable**: Expand checks for visibility, `contenteditable`, and generic `tabindex` elements (#35)
+- **listEventListeners**: Detect inline and property-based event handlers (#27)
+- **domUtils**: Expand `hasInteractiveHandler` with additional event attributes (#32)
+- **domUtils**: Expand `getSemanticContainer` tags and validate ARIA roles (#33)
+- **stringUtils**: Expand `isGenericTitle` to detect more generic title patterns (#37)
+- **getImageText**: Add language and options support for OCR (#30)
+- **testContrast**: Skip contrast testing for elements with background images
+
+### Refactoring
+
+- **isA11yVisible**: Delegate element-level hidden check to `isHidden` to reduce code duplication (#26)
+- **formUtils**: Remove redundant `hasAssociatedLabel` function (#25)
+- **stringUtils**: Replace `getAllText` with `getAccessibleText` in `hasText` (#36)
+- **constants**: Consolidate hardcoded constants into `constants.js` (#28)
+
+### Fixes
+
+- **getGeneratedContent**: Delegate pseudo-element retrieval to `getCSSGeneratedContent` (#29)
+
+### Documentation
+
+- **formUtils**: Clarify purpose of `hasExplicitAccessibleName` (#24)
+- Update test counts and coverage stats to match actual values
+
+## [1.2.0] - Previous release
+
+See git history for earlier changes.

package/CLAUDE.md

@@ -25,11 +25,11 @@
 ## Git Workflow
 
 - **Branching Strategy**: Git Flow must be used for all development
-  - **main/master**: Production-ready code only
-  - **develop**: Integration branch for features
-  - **feature/***: New features (branch from develop, merge back to develop)
-  - **release/***: Release preparation (branch from develop, merge to main and develop)
-  - **hotfix/***: Emergency fixes (branch from main, merge to main and develop)
+    - **main/master**: Production-ready code only
+    - **develop**: Integration branch for features
+    - **feature/\***: New features (branch from develop, merge back to develop)
+    - **release/\***: Release preparation (branch from develop, merge to main and develop)
+    - **hotfix/\***: Emergency fixes (branch from main, merge to main and develop)
 - **Branch Naming**: Use descriptive names (e.g., `feature/add-aria-validation`, `hotfix/fix-focus-trap`)
 - **Commits**: Write clear, concise commit messages following conventional commits when possible
 - **Pull Requests**: All features must go through PR review before merging to develop
@@ -44,12 +44,13 @@
 
 ### Test Status
 
-- **554 tests passing** - All functional tests work in JSDOM
-- **10 tests skipped** - Require real browser CSS pseudo-element support
-- See `BROWSER_TESTING.md` for details on JSDOM limitations and skipped tests
+- **943 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
 
 ### Browser Testing Limitations
 
-JSDOM does not fully support CSS pseudo-elements (`::before`, `::after`). Tests requiring these features are intentionally skipped with proper documentation. For details, see `BROWSER_TESTING.md`.
+JSDOM does not fully support CSS pseudo-elements (`::before`, `::after`). Tests requiring these features are conditionally skipped in JSDOM and covered by standalone Playwright tests instead. For details, see `BROWSER_TESTING.md`.
 
 This codebase provides DOM and accessibility testing utilities

package/package.json

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

package/src/constants.js

@@ -96,7 +96,52 @@ const RTL_LANGUAGES = [
  * Generic, non-descriptive, or meaningless frame/iframe titles.
  * @type {string[]}
  */
-const GENERIC_TITLES = ['iframe', 'frame', 'untitled', 'title', 'content', 'main', 'page'];
+const GENERIC_TITLES = [
+    'iframe',
+    'frame',
+    'untitled',
+    'title',
+    'content',
+    'main',
+    'page',
+    // Browser/authoring tool defaults
+    'untitled document',
+    'new page',
+    'blank',
+    'document',
+    'home',
+    'index',
+    'new document',
+    'no title',
+    'default',
+    'webpage',
+    'web page',
+    // CMS and editor defaults
+    'new tab',
+    'about blank',
+    'placeholder',
+    'sample page',
+    'test',
+    'example page',
+    'my page',
+    'welcome',
+    'landing page',
+    'site',
+    'header',
+    'footer',
+    'sidebar',
+    'banner',
+    'navigation',
+    'advertisement',
+    'ad',
+    'widget',
+    'module',
+    'section',
+    'region',
+    'form',
+    'search',
+    'menu',
+];
 
 /**
  * Generic or useless table summaries commonly found in the wild.
@@ -214,6 +259,385 @@ const NEW_WINDOW_WARNINGS = [
     'external site',
 ];
 
+/**
+ * ARIA roles that represent interactive widgets.
+ * @type {string[]}
+ */
+const INTERACTIVE_ROLES = [
+    'button',
+    'checkbox',
+    'combobox',
+    'link',
+    'menu',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'radio',
+    'scrollbar',
+    'slider',
+    'spinbutton',
+    'tablist',
+    'textbox',
+    'toolbar',
+    'switch',
+    'tree',
+];
+
+/**
+ * HTML tag names that are landmark elements.
+ * @type {string[]}
+ */
+const LANDMARK_TAGS = ['NAV', 'MAIN', 'HEADER', 'FOOTER', 'ASIDE', 'SECTION'];
+
+/**
+ * ARIA landmark roles.
+ * @type {string[]}
+ */
+const LANDMARK_ROLES = [
+    'navigation',
+    'main',
+    'banner',
+    'contentinfo',
+    'complementary',
+    'region',
+    'search',
+    'form',
+];
+
+/**
+ * Mapping of HTML tag names to their implicit landmark roles.
+ * @type {Object.<string, string>}
+ */
+const LANDMARK_ELEMENT_MAP = {
+    nav: 'navigation',
+    main: 'main',
+    aside: 'complementary',
+    header: 'banner',
+    footer: 'contentinfo',
+    section: 'region',
+    form: 'form',
+    search: 'search',
+};
+
+/**
+ * Set of valid ARIA attributes per WAI-ARIA specification.
+ * @type {Set<string>}
+ */
+const VALID_ARIA_ATTRIBUTES = new Set([
+    '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',
+]);
+
+/**
+ * CSS selectors for elements that are inherently not visible in the accessibility tree.
+ * @type {string[]}
+ */
+const NON_VISIBLE_SELECTORS = [
+    'base',
+    'head',
+    'meta',
+    'title',
+    'link',
+    'style',
+    'script',
+    'br',
+    'nobr',
+    'col',
+    'embed',
+    'input[type="hidden"]',
+    'keygen',
+    'source',
+    'track',
+    'wbr',
+    'datalist',
+    'area',
+    'param',
+    'noframes',
+    'ruby > rp',
+];
+
+/**
+ * ARIA roles that derive their accessible name from text content.
+ * @type {string[]}
+ */
+const TEXT_ROLES = [
+    'button',
+    'checkbox',
+    'columnheader',
+    'gridcell',
+    'heading',
+    'link',
+    'listitem',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'radio',
+    'row',
+    'rowgroup',
+    'rowheader',
+    'tab',
+    'tooltip',
+    'treeitem',
+];
+
+/**
+ * Raw array of CSS selectors for focusable elements (without :not([disabled]) filters).
+ * @type {string[]}
+ */
+const FOCUSABLE_SELECTORS = [
+    'a[href]',
+    'area',
+    'button',
+    'select',
+    'textarea',
+    'input:not([type="hidden"])',
+    '[tabindex]',
+];
+
+/**
+ * Set of all valid WAI-ARIA roles.
+ * @type {Set<string>}
+ */
+const VALID_ARIA_ROLES = 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',
+]);
+
+/**
+ * Generic/meaningless link text strings.
+ * @type {string[]}
+ */
+const GENERIC_LINK_TEXT = [
+    'click here',
+    'here',
+    'more',
+    'read more',
+    'learn more',
+    'click',
+    'link',
+    'this',
+    'page',
+    'article',
+    'continue',
+    'go',
+    'see more',
+    'view',
+    'download',
+    'pdf',
+    'document',
+    'form',
+    'submit',
+    'button',
+    'press',
+    'select',
+    'choose',
+];
+
+/**
+ * HTML tag names that act as semantic containers.
+ * @type {string[]}
+ */
+const SEMANTIC_CONTAINER_TAGS = [
+    'ARTICLE',
+    'ASIDE',
+    'BLOCKQUOTE',
+    'DETAILS',
+    'DIALOG',
+    'FIELDSET',
+    'FIGURE',
+    'FOOTER',
+    'FORM',
+    'HEADER',
+    'LI',
+    'MAIN',
+    'NAV',
+    'SECTION',
+    'TD',
+    'TH',
+];
+
+/**
+ * ARIA roles that represent semantic containers.
+ * @type {string[]}
+ */
+const SEMANTIC_CONTAINER_ROLES = [
+    'alert',
+    'alertdialog',
+    'application',
+    'banner',
+    'cell',
+    'complementary',
+    'contentinfo',
+    'dialog',
+    'document',
+    'feed',
+    'figure',
+    'form',
+    'grid',
+    'group',
+    'list',
+    'listbox',
+    'log',
+    'main',
+    'menu',
+    'menubar',
+    'navigation',
+    'note',
+    'region',
+    'row',
+    'rowgroup',
+    'search',
+    'status',
+    'table',
+    'tablist',
+    'tabpanel',
+    'toolbar',
+    'tree',
+    'treegrid',
+];
+
+/**
+ * Inline event handler attributes that indicate user interactivity.
+ * @type {string[]}
+ */
+const INTERACTIVE_HANDLER_ATTRIBUTES = [
+    'onclick',
+    'ondblclick',
+    'oncontextmenu',
+    'onmousedown',
+    'onmouseup',
+    'onkeydown',
+    'onkeyup',
+    'onkeypress',
+    'onfocus',
+    'onblur',
+    'oninput',
+    'onchange',
+    'onsubmit',
+    'ontouchstart',
+    'ontouchend',
+    'onpointerdown',
+    'onpointerup',
+];
+
 module.exports = {
     INTERACTIVE_SELECTOR,
     FOCUSABLE_SELECTOR,
@@ -228,4 +652,17 @@ module.exports = {
     COMPLEXITY_THRESHOLDS,
     MIN_TARGET_SIZE,
     NEW_WINDOW_WARNINGS,
+    INTERACTIVE_ROLES,
+    LANDMARK_TAGS,
+    LANDMARK_ROLES,
+    LANDMARK_ELEMENT_MAP,
+    VALID_ARIA_ATTRIBUTES,
+    NON_VISIBLE_SELECTORS,
+    TEXT_ROLES,
+    FOCUSABLE_SELECTORS,
+    VALID_ARIA_ROLES,
+    GENERIC_LINK_TEXT,
+    SEMANTIC_CONTAINER_TAGS,
+    SEMANTIC_CONTAINER_ROLES,
+    INTERACTIVE_HANDLER_ATTRIBUTES,
 };