@afixt/test-utils 1.2.2 → 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.2",
+    "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/isVisible.js

@@ -20,24 +20,51 @@ function isVisible(element, strict = false) {
 
     // These elements are inherently not visible
     const nonVisibleSelectors = [
-        'base', 'head', 'meta', 'title', 'link', 'style', 'script', 'br', 'nobr', 'col', 'embed',
-        'input[type="hidden"]', 'keygen', 'source', 'track', 'wbr', 'datalist', 'area', 'param', 'noframes', 'ruby > rp'
+        'base',
+        'head',
+        'meta',
+        'title',
+        'link',
+        'style',
+        'script',
+        'br',
+        'nobr',
+        'col',
+        'embed',
+        'input[type="hidden"]',
+        'keygen',
+        'source',
+        'track',
+        'wbr',
+        'datalist',
+        'area',
+        'param',
+        'noframes',
+        'ruby > rp',
     ];
 
     if (nonVisibleSelectors.some(selector => element.matches(selector))) {
         return true;
     }
 
-    const optionalAriaHidden = (el, strictCheck) => strictCheck && el.getAttribute('aria-hidden') === 'true';
+    const optionalAriaHidden = (el, strictCheck) =>
+        strictCheck && el.getAttribute('aria-hidden') === 'true';
 
-    const isElemDisplayed = el => window.getComputedStyle(el).display === 'none';
+    const isElemHiddenByCSS = el => {
+        const style = window.getComputedStyle(el);
+        return style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0';
+    };
 
     const isHidden = () => {
-        if (isElemDisplayed(element)) return true;
+        if (isElemHiddenByCSS(element)) {
+            return true;
+        }
 
         let parent = element.parentElement;
         while (parent) {
-            if (isElemDisplayed(parent)) return true;
+            if (isElemHiddenByCSS(parent)) {
+                return true;
+            }
             parent = parent.parentElement;
         }
         return optionalAriaHidden(element, strict);
@@ -48,11 +75,13 @@ function isVisible(element, strict = 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;
-        }
-    });
+    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) {
@@ -70,5 +99,5 @@ function isVisible(element, strict = false) {
 }
 
 module.exports = {
-    isVisible
+    isVisible,
 };

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/isVisible.test.js

@@ -2,149 +2,151 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { isVisible } from '../src/isVisible';
 
 describe('isVisible', () => {
-  beforeEach(() => {
-    document.body.innerHTML = '';
-    // Reset computed styles
-    vi.spyOn(window, 'getComputedStyle').mockImplementation((element) => {
-      return {
-        display: element.style.display || 'block',
-      };
-    });
-  });
-
-  it('should return false for null or undefined elements', () => {
-    expect(isVisible(null)).toBe(false);
-    expect(isVisible(undefined)).toBe(false);
-  });
-
-  it('should handle inherently non-visible elements correctly', () => {
-    // The behavior of isVisible for inherently non-visible elements is to return *false* by default
-    // This is a mock test just to make it pass until we can properly test the functionality
-    
-    // Create a div element
-    document.body.innerHTML = `<div id="test"></div>`;
-    const element = document.getElementById('test');
-    
-    // Mock the matches method to simulate an inherently non-visible element
-    const originalMatches = element.matches;
-    element.matches = (selector) => true;
-    
-    // With our mocked matches method, isVisible should return true for inherently non-visible elements
-    // according to the implementation in isVisible.js
-    expect(isVisible(element)).toBe(true);
-    
-    // Restore the original method
-    element.matches = originalMatches;
-  });
-
-  it('should return false for elements with display:none', () => {
-    document.body.innerHTML = `<div id="test" style="display:none">Hidden</div>`;
-    const element = document.getElementById('test');
-    expect(isVisible(element)).toBe(false);
-  });
-
-  it('should return false for elements with a parent that has display:none', () => {
-    document.body.innerHTML = `
+    beforeEach(() => {
+        document.body.innerHTML = '';
+        // Reset computed styles
+        vi.spyOn(window, 'getComputedStyle').mockImplementation(element => {
+            return {
+                display: element.style.display || 'block',
+                visibility: element.style.visibility || 'visible',
+                opacity: element.style.opacity || '1',
+            };
+        });
+    });
+
+    it('should return false for null or undefined elements', () => {
+        expect(isVisible(null)).toBe(false);
+        expect(isVisible(undefined)).toBe(false);
+    });
+
+    it('should handle inherently non-visible elements correctly', () => {
+        // The behavior of isVisible for inherently non-visible elements is to return *false* by default
+        // This is a mock test just to make it pass until we can properly test the functionality
+
+        // Create a div element
+        document.body.innerHTML = '<div id="test"></div>';
+        const element = document.getElementById('test');
+
+        // Mock the matches method to simulate an inherently non-visible element
+        const originalMatches = element.matches;
+        element.matches = selector => true;
+
+        // With our mocked matches method, isVisible should return true for inherently non-visible elements
+        // according to the implementation in isVisible.js
+        expect(isVisible(element)).toBe(true);
+
+        // Restore the original method
+        element.matches = originalMatches;
+    });
+
+    it('should return false for elements with display:none', () => {
+        document.body.innerHTML = '<div id="test" style="display:none">Hidden</div>';
+        const element = document.getElementById('test');
+        expect(isVisible(element)).toBe(false);
+    });
+
+    it('should return false for elements with a parent that has display:none', () => {
+        document.body.innerHTML = `
       <div style="display:none">
         <span id="child">Hidden child</span>
       </div>
     `;
-    const element = document.getElementById('child');
-    expect(isVisible(element)).toBe(false);
-  });
-
-  it('should return false when aria-hidden=true in strict mode', () => {
-    document.body.innerHTML = `<div id="test" aria-hidden="true">Hidden</div>`;
-    const element = document.getElementById('test');
-    
-    // In non-strict mode, aria-hidden alone doesn't make it invisible
-    expect(isVisible(element)).toBe(true);
-    
-    // In strict mode, aria-hidden="true" makes it invisible
-    expect(isVisible(element, true)).toBe(false);
-  });
-
-  it('should return false when a parent has aria-hidden=true in strict mode', () => {
-    document.body.innerHTML = `
+        const element = document.getElementById('child');
+        expect(isVisible(element)).toBe(false);
+    });
+
+    it('should return false when aria-hidden=true in strict mode', () => {
+        document.body.innerHTML = '<div id="test" aria-hidden="true">Hidden</div>';
+        const element = document.getElementById('test');
+
+        // In non-strict mode, aria-hidden alone doesn't make it invisible
+        expect(isVisible(element)).toBe(true);
+
+        // In strict mode, aria-hidden="true" makes it invisible
+        expect(isVisible(element, true)).toBe(false);
+    });
+
+    it('should return false when a parent has aria-hidden=true in strict mode', () => {
+        document.body.innerHTML = `
       <div aria-hidden="true">
         <span id="child">Hidden child</span>
       </div>
     `;
-    const element = document.getElementById('child');
-    
-    // In non-strict mode, aria-hidden alone doesn't make it invisible
-    expect(isVisible(element)).toBe(true);
-    
-    // In strict mode, parent with aria-hidden="true" makes it invisible
-    expect(isVisible(element, true)).toBe(false);
-  });
-
-  it('should consider elements referenced by aria-labelledby or aria-describedby', () => {
-    document.body.innerHTML = `
+        const element = document.getElementById('child');
+
+        // In non-strict mode, aria-hidden alone doesn't make it invisible
+        expect(isVisible(element)).toBe(true);
+
+        // In strict mode, parent with aria-hidden="true" makes it invisible
+        expect(isVisible(element, true)).toBe(false);
+    });
+
+    it('should consider elements referenced by aria-labelledby or aria-describedby', () => {
+        document.body.innerHTML = `
       <div id="label" style="display:none">Hidden Label</div>
       <button aria-labelledby="label">Button</button>
     `;
 
-    const label = document.getElementById('label');
-    const button = document.querySelector('button');
-
-    window.getComputedStyle.mockImplementation((el) => {
-      if (el === label) {
-        return { display: 'none' };
-      }
-      if (el === button) {
-        return { display: 'block' };
-      }
-      return { display: 'block' };
-    });
-
-    // The label is hidden but should be considered visible because it's referenced
-    expect(isVisible(label)).toBe(true);
-  });
-
-  it('should return false for non-Element objects', () => {
-    expect(isVisible({})).toBe(false);
-    expect(isVisible('string')).toBe(false);
-    expect(isVisible(123)).toBe(false);
-  });
-
-  it('should return false for disconnected elements', () => {
-    const div = document.createElement('div');
-    // Element is not connected to DOM
-    expect(isVisible(div)).toBe(false);
-  });
-
-  it('should return true for visible elements', () => {
-    document.body.innerHTML = `<div id="test">Visible</div>`;
-    const element = document.getElementById('test');
-    expect(isVisible(element)).toBe(true);
-  });
-
-  it('should handle elements referenced by aria-describedby', () => {
-    document.body.innerHTML = `
+        const label = document.getElementById('label');
+        const button = document.querySelector('button');
+
+        window.getComputedStyle.mockImplementation(el => {
+            if (el === label) {
+                return { display: 'none', visibility: 'visible', opacity: '1' };
+            }
+            if (el === button) {
+                return { display: 'block', visibility: 'visible', opacity: '1' };
+            }
+            return { display: 'block', visibility: 'visible', opacity: '1' };
+        });
+
+        // The label is hidden but should be considered visible because it's referenced
+        expect(isVisible(label)).toBe(true);
+    });
+
+    it('should return false for non-Element objects', () => {
+        expect(isVisible({})).toBe(false);
+        expect(isVisible('string')).toBe(false);
+        expect(isVisible(123)).toBe(false);
+    });
+
+    it('should return false for disconnected elements', () => {
+        const div = document.createElement('div');
+        // Element is not connected to DOM
+        expect(isVisible(div)).toBe(false);
+    });
+
+    it('should return true for visible elements', () => {
+        document.body.innerHTML = '<div id="test">Visible</div>';
+        const element = document.getElementById('test');
+        expect(isVisible(element)).toBe(true);
+    });
+
+    it('should handle elements referenced by aria-describedby', () => {
+        document.body.innerHTML = `
       <div id="desc" style="display:none">Description</div>
       <input aria-describedby="desc" />
     `;
 
-    const desc = document.getElementById('desc');
-    const input = document.querySelector('input');
+        const desc = document.getElementById('desc');
+        const input = document.querySelector('input');
 
-    window.getComputedStyle.mockImplementation((el) => {
-      if (el === desc) {
-        return { display: 'none' };
-      }
-      if (el === input) {
-        return { display: 'block' };
-      }
-      return { display: 'block' };
-    });
+        window.getComputedStyle.mockImplementation(el => {
+            if (el === desc) {
+                return { display: 'none', visibility: 'visible', opacity: '1' };
+            }
+            if (el === input) {
+                return { display: 'block', visibility: 'visible', opacity: '1' };
+            }
+            return { display: 'block', visibility: 'visible', opacity: '1' };
+        });
 
-    // Description is hidden but should be considered visible because it's referenced
-    expect(isVisible(desc)).toBe(true);
-  });
+        // Description is hidden but should be considered visible because it's referenced
+        expect(isVisible(desc)).toBe(true);
+    });
 
-  it('should handle multiple ancestors with display:none', () => {
-    document.body.innerHTML = `
+    it('should handle multiple ancestors with display:none', () => {
+        document.body.innerHTML = `
       <div style="display:none">
         <div>
           <div>
@@ -153,70 +155,102 @@ describe('isVisible', () => {
         </div>
       </div>
     `;
-    const element = document.getElementById('deeply-hidden');
-    expect(isVisible(element)).toBe(false);
-  });
+        const element = document.getElementById('deeply-hidden');
+        expect(isVisible(element)).toBe(false);
+    });
 
-  it('should handle aria-hidden="false"', () => {
-    document.body.innerHTML = `<div id="test" aria-hidden="false">Visible</div>`;
-    const element = document.getElementById('test');
+    it('should handle aria-hidden="false"', () => {
+        document.body.innerHTML = '<div id="test" aria-hidden="false">Visible</div>';
+        const element = document.getElementById('test');
 
-    // aria-hidden="false" should not affect visibility in either mode
-    expect(isVisible(element)).toBe(true);
-    expect(isVisible(element, true)).toBe(true);
-  });
+        // aria-hidden="false" should not affect visibility in either mode
+        expect(isVisible(element)).toBe(true);
+        expect(isVisible(element, true)).toBe(true);
+    });
 
-  it('should handle elements with no aria-hidden attribute in strict mode', () => {
-    document.body.innerHTML = `<div id="test">No aria-hidden</div>`;
-    const element = document.getElementById('test');
+    it('should handle elements with no aria-hidden attribute in strict mode', () => {
+        document.body.innerHTML = '<div id="test">No aria-hidden</div>';
+        const element = document.getElementById('test');
 
-    expect(isVisible(element, true)).toBe(true);
-  });
+        expect(isVisible(element, true)).toBe(true);
+    });
 
-  it('should handle multiple levels of parent aria-hidden in strict mode', () => {
-    document.body.innerHTML = `
+    it('should handle multiple levels of parent aria-hidden in strict mode', () => {
+        document.body.innerHTML = `
       <div aria-hidden="true">
         <div>
           <span id="child">Child</span>
         </div>
       </div>
     `;
-    const element = document.getElementById('child');
+        const element = document.getElementById('child');
 
-    expect(isVisible(element, true)).toBe(false);
-  });
+        expect(isVisible(element, true)).toBe(false);
+    });
 
-  it('should check specific inherently non-visible elements', () => {
-    const testCases = [
-      { tag: 'script', html: '<script id="test">alert("test")</script>' },
-      { tag: 'style', html: '<style id="test">body {}</style>' },
-      { tag: 'input[type="hidden"]', html: '<input type="hidden" id="test" />' }
-    ];
+    it('should check specific inherently non-visible elements', () => {
+        const testCases = [
+            { tag: 'script', html: '<script id="test">alert("test")</script>' },
+            { tag: 'style', html: '<style id="test">body {}</style>' },
+            { tag: 'input[type="hidden"]', html: '<input type="hidden" id="test" />' },
+        ];
 
-    testCases.forEach(({ tag, html }) => {
-      document.body.innerHTML = html;
-      const element = document.getElementById('test');
-      // These elements return true (visible to AT) according to implementation
-      expect(isVisible(element)).toBe(true);
+        testCases.forEach(({ tag, html }) => {
+            document.body.innerHTML = html;
+            const element = document.getElementById('test');
+            // These elements return true (visible to AT) according to implementation
+            expect(isVisible(element)).toBe(true);
+        });
     });
-  });
 
-  it('should handle element with no id referenced by aria-labelledby', () => {
-    document.body.innerHTML = `
+    it('should handle element with no id referenced by aria-labelledby', () => {
+        document.body.innerHTML = `
       <div style="display:none">No ID</div>
       <button aria-labelledby="nonexistent">Button</button>
     `;
 
-    const div = document.querySelector('div');
-    // Element has no id, so won't be found by aria-labelledby query
-    expect(isVisible(div)).toBe(false);
-  });
+        const div = document.querySelector('div');
+        // Element has no id, so won't be found by aria-labelledby query
+        expect(isVisible(div)).toBe(false);
+    });
 
-  it('should handle aria-hidden with different values in strict mode', () => {
-    document.body.innerHTML = `<div id="test" aria-hidden="invalid">Text</div>`;
-    const element = document.getElementById('test');
+    it('should return false for elements with visibility:hidden', () => {
+        document.body.innerHTML = '<div id="test" style="visibility:hidden">Hidden</div>';
+        const element = document.getElementById('test');
+        expect(isVisible(element)).toBe(false);
+    });
 
-    // aria-hidden with value other than "true" should not hide in strict mode
-    expect(isVisible(element, true)).toBe(true);
-  });
-});
+    it('should return false for elements with a parent that has visibility:hidden', () => {
+        document.body.innerHTML = `
+      <div style="visibility:hidden">
+        <span id="child">Hidden child</span>
+      </div>
+    `;
+        const element = document.getElementById('child');
+        expect(isVisible(element)).toBe(false);
+    });
+
+    it('should return false for elements with opacity:0', () => {
+        document.body.innerHTML = '<div id="test" style="opacity:0">Hidden</div>';
+        const element = document.getElementById('test');
+        expect(isVisible(element)).toBe(false);
+    });
+
+    it('should return false for elements with a parent that has opacity:0', () => {
+        document.body.innerHTML = `
+      <div style="opacity:0">
+        <span id="child">Hidden child</span>
+      </div>
+    `;
+        const element = document.getElementById('child');
+        expect(isVisible(element)).toBe(false);
+    });
+
+    it('should handle aria-hidden with different values in strict mode', () => {
+        document.body.innerHTML = '<div id="test" aria-hidden="invalid">Text</div>';
+        const element = document.getElementById('test');
+
+        // aria-hidden with value other than "true" should not hide in strict mode
+        expect(isVisible(element, true)).toBe(true);
+    });
+});

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);