@afixt/test-utils 1.2.3 → 1.3.0

package/.claude/settings.local.json

@@ -18,12 +18,7 @@
       "Bash(node:*)",
       "Bash(npx vitest run:*)",
       "Bash(1)",
-      "Bash(npm run test:playwright:css:*)",
-      "Bash(gh run list:*)",
-      "Bash(gh pr create:*)",
-      "Bash(git checkout:*)",
-      "Bash(git pull:*)",
-      "Bash(git merge:*)"
+      "Bash(npm run test:playwright:css:*)"
     ]
   },
   "enableAllProjectMcpServers": false

package/package.json

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

package/src/getAccessibleName.js

@@ -456,23 +456,45 @@ 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 landmarkRoles = [
+        'banner',
+        'complementary',
+        'contentinfo',
+        'form',
+        'main',
+        'navigation',
+        'region',
+        'search',
+    ];
 
-    if (isNavigation) {
-        // Title attribute is valid for navigation landmarks
+    const landmarkElementMap = {
+        nav: 'navigation',
+        main: 'main',
+        aside: 'complementary',
+        header: 'banner',
+        footer: 'contentinfo',
+        section: 'region',
+        form: 'form',
+        search: 'search',
+    };
+
+    const tagName = element.tagName.toLowerCase();
+    const role = element.getAttribute('role');
+    const isLandmark = landmarkRoles.includes(role) || tagName in landmarkElementMap;
+
+    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;
     }
 

package/src/testContrast.js

@@ -1,3 +1,50 @@
+/**
+ * Check if an element or any of its ancestors has a background image set.
+ * Walks up the DOM tree until it finds a background image or an opaque background color.
+ * @param {Element} el - The element to check
+ * @returns {boolean} True if the element or a visible ancestor has a background image
+ */
+function hasBackgroundImage(el) {
+    if (!el || el.nodeType === 9 || !window.getComputedStyle) {
+        return false;
+    }
+
+    let current = el;
+    while (current && current.nodeType !== 9) {
+        const styles = window.getComputedStyle(current);
+        if (!styles) {
+            return false;
+        }
+
+        const bgImage = styles.getPropertyValue('background-image');
+        if (bgImage && bgImage !== 'none') {
+            return true;
+        }
+
+        // If this element has an opaque background color, stop traversal
+        // since no ancestor background image would be visible through it
+        const bgColor = styles.getPropertyValue('background-color');
+        const parsed = parseRGB(bgColor);
+        if (parsed) {
+            const isTransparent =
+                bgColor === 'rgba(0, 0, 0, 0)' ||
+                bgColor === 'transparent' ||
+                (parsed[4] !== undefined && parseFloat(parsed[4]) === 0);
+            const isSemiTransparent =
+                parsed[4] !== undefined && parseFloat(parsed[4]) > 0 && parseFloat(parsed[4]) < 1;
+
+            if (!isTransparent && !isSemiTransparent) {
+                // Opaque background color, no ancestor background image visible
+                return false;
+            }
+        }
+
+        current = current.parentElement;
+    }
+
+    return false;
+}
+
 /**
  * Get the computed background color for an element.
  * @param  {Element} el - the element to be tested
@@ -240,6 +287,12 @@ function testContrast(el, options = { level: 'AA' }) {
         return false;
     }
 
+    // Skip elements with a background image on the element itself or a visible ancestor.
+    // Contrast cannot be reliably tested against background images.
+    if (hasBackgroundImage(el)) {
+        return true;
+    }
+
     const styles = window.getComputedStyle(el);
     const selfFG = styles.getPropertyValue('color');
     const selfBG = getComputedBackgroundColor(el);
@@ -346,6 +399,7 @@ function testContrast(el, options = { level: 'AA' }) {
 
 module.exports = {
     testContrast,
+    hasBackgroundImage,
     getComputedBackgroundColor,
     luminance,
     parseRGB,

package/test/getAccessibleName.test.js

@@ -428,4 +428,43 @@ describe('getAccessibleName', () => {
         const meter = document.querySelector('[role="meter"]');
         expect(getAccessibleName(meter)).toBe('Signal strength');
     });
+
+    describe('landmark elements should not get name from contents', () => {
+        const landmarkElements = [
+            { tag: 'nav', role: 'navigation' },
+            { tag: 'main', role: 'main' },
+            { tag: 'aside', role: 'complementary' },
+            { tag: 'header', role: 'banner' },
+            { tag: 'footer', role: 'contentinfo' },
+            { tag: 'section', role: 'region' },
+            { tag: 'form', role: 'form' },
+            { tag: 'search', role: 'search' },
+        ];
+
+        landmarkElements.forEach(({ tag, role }) => {
+            it(`should return false for <${tag}> without naming attributes`, () => {
+                document.body.innerHTML = `<${tag}><p>Some inner text content</p></${tag}>`;
+                const el = document.querySelector(tag);
+                expect(getAccessibleName(el)).toBe(false);
+            });
+
+            it(`should return title for <${tag}> with title attribute`, () => {
+                document.body.innerHTML = `<${tag} title="My ${tag} landmark"><p>Some inner text</p></${tag}>`;
+                const el = document.querySelector(tag);
+                expect(getAccessibleName(el)).toBe(`My ${tag} landmark`);
+            });
+
+            it(`should return false for div with role="${role}" without naming attributes`, () => {
+                document.body.innerHTML = `<div role="${role}"><p>Some inner text content</p></div>`;
+                const el = document.querySelector(`[role="${role}"]`);
+                expect(getAccessibleName(el)).toBe(false);
+            });
+
+            it(`should return title for div with role="${role}" and title attribute`, () => {
+                document.body.innerHTML = `<div role="${role}" title="My ${role} landmark"><p>Some inner text</p></div>`;
+                const el = document.querySelector(`[role="${role}"]`);
+                expect(getAccessibleName(el)).toBe(`My ${role} landmark`);
+            });
+        });
+    });
 });

package/test/testContrast.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import {
     testContrast,
+    hasBackgroundImage,
     getComputedBackgroundColor,
     luminance,
     parseRGB,
@@ -94,17 +95,49 @@ describe('testContrast', () => {
         expect(testContrast(div)).toBe(true);
     });
 
-    it('should handle elements with background images', () => {
+    it('should skip elements with a background image', () => {
         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 return true because background color can't be determined
+        // Should skip because contrast can't be reliably tested against background images
         expect(testContrast(div)).toBe(true);
     });
 
+    it('should skip elements whose ancestor has a background image', () => {
+        const parent = document.createElement('div');
+        parent.style.backgroundImage = 'url(bg.jpg)';
+
+        const child = document.createElement('div');
+        child.textContent = 'Text over parent background image';
+        child.style.color = 'rgb(0, 0, 0)';
+        child.style.backgroundColor = 'rgba(0, 0, 0, 0)';
+
+        parent.appendChild(child);
+        document.body.appendChild(parent);
+
+        expect(testContrast(child)).toBe(true);
+    });
+
+    it('should not skip elements with opaque background over ancestor background image', () => {
+        const parent = document.createElement('div');
+        parent.style.backgroundImage = 'url(bg.jpg)';
+
+        const child = document.createElement('div');
+        child.textContent = 'Text with opaque background';
+        child.style.color = 'rgb(0, 0, 0)';
+        child.style.backgroundColor = 'rgb(255, 255, 255)';
+
+        parent.appendChild(child);
+        document.body.appendChild(parent);
+
+        // The child has an opaque background, so the parent's background image
+        // is not visible through it. Contrast should be tested normally.
+        expect(testContrast(child)).toBe(true);
+    });
+
     it('should handle invisible elements', () => {
         const div = document.createElement('div');
         div.textContent = 'Hidden text';
@@ -499,6 +532,75 @@ describe('getComputedBackgroundColor', () => {
     });
 });
 
+describe('hasBackgroundImage', () => {
+    beforeEach(() => {
+        document.body.innerHTML = '';
+    });
+
+    it('should return false for null element', () => {
+        expect(hasBackgroundImage(null)).toBe(false);
+    });
+
+    it('should return false for document node', () => {
+        expect(hasBackgroundImage(document)).toBe(false);
+    });
+
+    it('should return true for element with background-image', () => {
+        const div = document.createElement('div');
+        div.style.backgroundImage = 'url(test.jpg)';
+        document.body.appendChild(div);
+
+        expect(hasBackgroundImage(div)).toBe(true);
+    });
+
+    it('should return false for element without background-image', () => {
+        const div = document.createElement('div');
+        div.style.backgroundColor = 'rgb(255, 255, 255)';
+        document.body.appendChild(div);
+
+        expect(hasBackgroundImage(div)).toBe(false);
+    });
+
+    it('should return true when ancestor has a background image and element is transparent', () => {
+        const parent = document.createElement('div');
+        parent.style.backgroundImage = 'url(bg.jpg)';
+
+        const child = document.createElement('div');
+        child.style.backgroundColor = 'rgba(0, 0, 0, 0)';
+
+        parent.appendChild(child);
+        document.body.appendChild(parent);
+
+        expect(hasBackgroundImage(child)).toBe(true);
+    });
+
+    it('should return false when ancestor has background image but element has opaque background', () => {
+        const parent = document.createElement('div');
+        parent.style.backgroundImage = 'url(bg.jpg)';
+
+        const child = document.createElement('div');
+        child.style.backgroundColor = 'rgb(255, 255, 255)';
+
+        parent.appendChild(child);
+        document.body.appendChild(parent);
+
+        expect(hasBackgroundImage(child)).toBe(false);
+    });
+
+    it('should return false if getComputedStyle is not available', () => {
+        const div = document.createElement('div');
+        div.style.backgroundImage = 'url(test.jpg)';
+        document.body.appendChild(div);
+
+        const originalGetComputedStyle = window.getComputedStyle;
+        window.getComputedStyle = null;
+
+        expect(hasBackgroundImage(div)).toBe(false);
+
+        window.getComputedStyle = originalGetComputedStyle;
+    });
+});
+
 describe('luminance', () => {
     it('should calculate luminance for pure black (0, 0, 0)', () => {
         const result = luminance(0, 0, 0);