@afixt/test-utils 2.0.0 → 2.1.0

package/src/suggestContrast.js

@@ -0,0 +1,386 @@
+/**
+ * @file Suggest color pairs that meet a minimum WCAG contrast ratio.
+ * @module suggestContrast
+ * @description Inspired by Tanaguru Contrast-Finder's HSL-space "Psycho" search strategy.
+ * Given a foreground/background pair, this utility finds nearby colors that meet
+ * the specified contrast ratio while staying perceptually close to the originals.
+ */
+
+const { luminance } = require('./testContrast.js');
+const { rgbToHex, rgbToHsl, hslToRgb, parseAnyColor } = require('./colorConversions.js');
+
+/**
+ * Maximum per-channel RGB drift from the original color.
+ * Adapted from Tanaguru's DEFAULT_COLOR_COMPONENT_BOUNDER.
+ * @type {number}
+ */
+const MAX_COMPONENT_DRIFT = 40;
+
+/**
+ * Number of suggestions to return.
+ * @type {number}
+ */
+const SUGGESTION_COUNT = 12;
+
+/**
+ * Compute the WCAG contrast ratio between two RGB color objects.
+ * @param {{ r: number, g: number, b: number }} rgb1
+ * @param {{ r: number, g: number, b: number }} rgb2
+ * @returns {number} Contrast ratio rounded to 2 decimal places (1 to 21)
+ */
+function computeContrastRatio(rgb1, rgb2) {
+    const lum1 = luminance(rgb1.r, rgb1.g, rgb1.b);
+    const lum2 = luminance(rgb2.r, rgb2.g, rgb2.b);
+    const lighter = Math.max(lum1, lum2);
+    const darker = Math.min(lum1, lum2);
+    return Math.round(((lighter + 0.05) / (darker + 0.05)) * 100) / 100;
+}
+
+/**
+ * Calculate the RGB Manhattan distance between two color objects.
+ * @param {{ r: number, g: number, b: number }} a
+ * @param {{ r: number, g: number, b: number }} b
+ * @returns {number} Sum of absolute differences across R, G, B channels
+ */
+function rgbDistance(a, b) {
+    return Math.abs(a.r - b.r) + Math.abs(a.g - b.g) + Math.abs(a.b - b.b);
+}
+
+/**
+ * Check if a candidate color is within the allowed RGB drift from the original.
+ * @param {{ r: number, g: number, b: number }} candidate
+ * @param {{ r: number, g: number, b: number }} original
+ * @returns {boolean}
+ */
+function withinDrift(candidate, original) {
+    return (
+        Math.abs(candidate.r - original.r) <= MAX_COMPONENT_DRIFT &&
+        Math.abs(candidate.g - original.g) <= MAX_COMPONENT_DRIFT &&
+        Math.abs(candidate.b - original.b) <= MAX_COMPONENT_DRIFT
+    );
+}
+
+/**
+ * Clamp a number between min and max.
+ * @param {number} val
+ * @param {number} min
+ * @param {number} max
+ * @returns {number}
+ */
+function clamp(val, min, max) {
+    return Math.max(min, Math.min(max, val));
+}
+
+/**
+ * Wrap a hue value to stay within 0-360.
+ * @param {number} h
+ * @returns {number}
+ */
+function wrapHue(h) {
+    return ((h % 360) + 360) % 360;
+}
+
+/**
+ * Format an RGB object into a full suggestion color object with hex, rgb, and hsl representations.
+ * @param {{ r: number, g: number, b: number }} rgb
+ * @returns {{ hex: string, rgb: { r: number, g: number, b: number }, hsl: { h: number, s: number, l: number } }}
+ */
+function formatColor(rgb) {
+    return {
+        hex: rgbToHex(rgb),
+        rgb: { r: rgb.r, g: rgb.g, b: rgb.b },
+        hsl: rgbToHsl(rgb),
+    };
+}
+
+/**
+ * Derive the default minimum contrast ratio based on font size and weight per WCAG 2.x.
+ * @param {number} fontSize - Font size in pixels
+ * @param {boolean} isBold - Whether the text is bold
+ * @returns {number} Minimum contrast ratio (3.0 for large text, 4.5 for normal text)
+ */
+function deriveMinRatio(fontSize, isBold) {
+    if (fontSize >= 18) {
+        return 3.0;
+    }
+    if (fontSize >= 14 && isBold) {
+        return 3.0;
+    }
+    return 4.5;
+}
+
+/**
+ * Search for valid colors by adjusting lightness in one direction.
+ * @param {{ h: number, s: number, l: number }} baseHsl - Starting HSL color
+ * @param {{ r: number, g: number, b: number }} originalRgb - Original RGB for drift checking
+ * @param {{ r: number, g: number, b: number }} fixedRgb - The fixed color to check contrast against
+ * @param {number} targetRatio - Required contrast ratio
+ * @param {number} direction - +1 for lighter, -1 for darker
+ * @param {number} maxResults - Maximum results to collect
+ * @returns {Array<{ r: number, g: number, b: number }>} Array of valid RGB colors found
+ */
+function searchLightness(baseHsl, originalRgb, fixedRgb, targetRatio, direction, maxResults) {
+    const results = [];
+
+    for (let step = 1; step <= 100; step++) {
+        const newL = baseHsl.l + direction * step;
+        if (newL < 0 || newL > 100) {
+            break;
+        }
+
+        const candidateHsl = { h: baseHsl.h, s: baseHsl.s, l: Math.round(newL) };
+        const candidateRgb = hslToRgb(candidateHsl);
+        const ratio = computeContrastRatio(candidateRgb, fixedRgb);
+
+        if (ratio >= targetRatio && withinDrift(candidateRgb, originalRgb)) {
+            results.push(candidateRgb);
+            if (results.length >= maxResults) {
+                break;
+            }
+        }
+    }
+
+    return results;
+}
+
+/**
+ * Search for valid colors by adjusting lightness, without the drift constraint.
+ * Used as a fallback when drift-constrained search yields too few results.
+ * @param {{ h: number, s: number, l: number }} baseHsl
+ * @param {{ r: number, g: number, b: number }} fixedRgb
+ * @param {number} targetRatio
+ * @param {number} direction
+ * @param {number} maxResults
+ * @returns {Array<{ r: number, g: number, b: number }>}
+ */
+function searchLightnessUnconstrained(baseHsl, fixedRgb, targetRatio, direction, maxResults) {
+    const results = [];
+
+    for (let step = 1; step <= 100; step++) {
+        const newL = baseHsl.l + direction * step;
+        if (newL < 0 || newL > 100) {
+            break;
+        }
+
+        const candidateHsl = { h: baseHsl.h, s: baseHsl.s, l: Math.round(newL) };
+        const candidateRgb = hslToRgb(candidateHsl);
+        const ratio = computeContrastRatio(candidateRgb, fixedRgb);
+
+        if (ratio >= targetRatio) {
+            results.push(candidateRgb);
+            if (results.length >= maxResults) {
+                break;
+            }
+        }
+    }
+
+    return results;
+}
+
+/**
+ * Generate hue/saturation variations from a base color that meet the contrast requirement.
+ * @param {{ r: number, g: number, b: number }} baseRgb - Base color found from lightness search
+ * @param {{ r: number, g: number, b: number }} fixedRgb - The color held constant
+ * @param {number} targetRatio - Required contrast ratio
+ * @param {Set<string>} seen - Set of already-seen hex pair keys for dedup
+ * @param {string} fixedHex - Hex of the fixed color for building dedup keys
+ * @param {boolean} isForeground - Whether baseRgb is the foreground in the pair
+ * @returns {Array<{ candidate: { r: number, g: number, b: number }, key: string }>}
+ */
+function generateVariations(baseRgb, fixedRgb, targetRatio, seen, fixedHex, isForeground) {
+    const results = [];
+    const baseHsl = rgbToHsl(baseRgb);
+    const hueOffsets = [-10, -5, 5, 10];
+    const satOffsets = [-6, -3, 3, 6];
+
+    for (const hOff of hueOffsets) {
+        for (const sOff of satOffsets) {
+            const candidateHsl = {
+                h: wrapHue(baseHsl.h + hOff),
+                s: clamp(baseHsl.s + sOff, 0, 100),
+                l: baseHsl.l,
+            };
+            const candidateRgb = hslToRgb(candidateHsl);
+            const ratio = computeContrastRatio(candidateRgb, fixedRgb);
+
+            if (ratio >= targetRatio) {
+                const candHex = rgbToHex(candidateRgb);
+                const key = isForeground ? candHex + '|' + fixedHex : fixedHex + '|' + candHex;
+                if (!seen.has(key)) {
+                    results.push({ candidate: candidateRgb, key });
+                }
+            }
+        }
+    }
+
+    return results;
+}
+
+/**
+ * Suggest color pairs that meet a minimum contrast ratio.
+ *
+ * Takes a foreground/background color pair and returns up to 12 alternative color pair
+ * suggestions that meet the specified (or WCAG-derived) minimum contrast ratio.
+ * Each suggestion stays perceptually close to the original colors.
+ *
+ * @param {Object} options
+ * @param {string} options.foreground - Foreground color (hex, rgb(), rgba(), or hsl() string)
+ * @param {string} options.background - Background color (hex, rgb(), rgba(), or hsl() string)
+ * @param {number} [options.fontSize=16] - Text size in pixels
+ * @param {number} [options.minRatio] - Minimum desired contrast ratio (1-21).
+ *   Defaults based on fontSize: 4.5 for normal text, 3.0 for large text (>=18px or >=14px bold).
+ * @param {boolean} [options.isBold=false] - Whether text is bold (affects default ratio for 14-17px text)
+ * @returns {Array<Object>} Array of up to 12 suggestion objects sorted by proximity to originals.
+ *   Each object has: foreground ({hex, rgb, hsl}), background ({hex, rgb, hsl}), contrastRatio, distance.
+ *   Returns empty array on invalid input.
+ */
+function suggestContrast(options) {
+    if (!options || typeof options !== 'object') {
+        return [];
+    }
+
+    const fgRgb = parseAnyColor(options.foreground);
+    const bgRgb = parseAnyColor(options.background);
+
+    if (!fgRgb || !bgRgb) {
+        return [];
+    }
+
+    const fontSize =
+        typeof options.fontSize === 'number' && options.fontSize > 0 ? options.fontSize : 16;
+    const isBold = options.isBold === true;
+
+    let targetRatio;
+    if (typeof options.minRatio === 'number') {
+        if (options.minRatio < 1 || options.minRatio > 21) {
+            return [];
+        }
+        targetRatio = options.minRatio;
+    } else {
+        targetRatio = deriveMinRatio(fontSize, isBold);
+    }
+
+    const fgHsl = rgbToHsl(fgRgb);
+    const bgHsl = rgbToHsl(bgRgb);
+    const fgHex = rgbToHex(fgRgb);
+    const bgHex = rgbToHex(bgRgb);
+
+    const candidates = [];
+    const seen = new Set();
+
+    // --- Phase 1: Lightness adjustments ---
+
+    // 1a. Adjust foreground lightness (hold background fixed)
+    const fgDarker = searchLightness(fgHsl, fgRgb, bgRgb, targetRatio, -1, 3);
+    const fgLighter = searchLightness(fgHsl, fgRgb, bgRgb, targetRatio, 1, 3);
+    const fgResults = [...fgDarker, ...fgLighter];
+
+    // Fallback: if drift constraint was too tight, search without it
+    if (fgResults.length < 3) {
+        const needed = 3 - fgResults.length;
+        const fallbackDarker = searchLightnessUnconstrained(fgHsl, bgRgb, targetRatio, -1, needed);
+        const fallbackLighter = searchLightnessUnconstrained(fgHsl, bgRgb, targetRatio, 1, needed);
+        const fallback = [...fallbackDarker, ...fallbackLighter];
+        // Deduplicate against what we already have
+        const existingHexes = new Set(fgResults.map(c => rgbToHex(c)));
+        for (const c of fallback) {
+            if (!existingHexes.has(rgbToHex(c)) && fgResults.length < 6) {
+                fgResults.push(c);
+            }
+        }
+    }
+
+    for (const fg of fgResults) {
+        const hex = rgbToHex(fg);
+        const key = hex + '|' + bgHex;
+        if (!seen.has(key)) {
+            seen.add(key);
+            candidates.push({
+                fg,
+                bg: bgRgb,
+                ratio: computeContrastRatio(fg, bgRgb),
+                dist: rgbDistance(fg, fgRgb),
+            });
+        }
+    }
+
+    // 1b. Adjust background lightness (hold foreground fixed)
+    const bgDarker = searchLightness(bgHsl, bgRgb, fgRgb, targetRatio, -1, 3);
+    const bgLighter = searchLightness(bgHsl, bgRgb, fgRgb, targetRatio, 1, 3);
+    const bgResults = [...bgDarker, ...bgLighter];
+
+    if (bgResults.length < 3) {
+        const needed = 3 - bgResults.length;
+        const fallbackDarker = searchLightnessUnconstrained(bgHsl, fgRgb, targetRatio, -1, needed);
+        const fallbackLighter = searchLightnessUnconstrained(bgHsl, fgRgb, targetRatio, 1, needed);
+        const fallback = [...fallbackDarker, ...fallbackLighter];
+        const existingHexes = new Set(bgResults.map(c => rgbToHex(c)));
+        for (const c of fallback) {
+            if (!existingHexes.has(rgbToHex(c)) && bgResults.length < 6) {
+                bgResults.push(c);
+            }
+        }
+    }
+
+    for (const bg of bgResults) {
+        const hex = rgbToHex(bg);
+        const key = fgHex + '|' + hex;
+        if (!seen.has(key)) {
+            seen.add(key);
+            candidates.push({
+                fg: fgRgb,
+                bg,
+                ratio: computeContrastRatio(fgRgb, bg),
+                dist: rgbDistance(bg, bgRgb),
+            });
+        }
+    }
+
+    // --- Phase 2: Hue/Saturation diversity ---
+
+    // Use the first few Phase 1 results as bases for variation
+    const fgBases = fgResults.slice(0, 2);
+    const bgBases = bgResults.slice(0, 2);
+
+    for (const base of fgBases) {
+        const variations = generateVariations(base, bgRgb, targetRatio, seen, bgHex, true);
+        for (const v of variations) {
+            seen.add(v.key);
+            candidates.push({
+                fg: v.candidate,
+                bg: bgRgb,
+                ratio: computeContrastRatio(v.candidate, bgRgb),
+                dist: rgbDistance(v.candidate, fgRgb),
+            });
+        }
+    }
+
+    for (const base of bgBases) {
+        const variations = generateVariations(base, fgRgb, targetRatio, seen, fgHex, false);
+        for (const v of variations) {
+            seen.add(v.key);
+            candidates.push({
+                fg: fgRgb,
+                bg: v.candidate,
+                ratio: computeContrastRatio(fgRgb, v.candidate),
+                dist: rgbDistance(v.candidate, bgRgb),
+            });
+        }
+    }
+
+    // --- Sort by distance and return top SUGGESTION_COUNT ---
+
+    candidates.sort((a, b) => a.dist - b.dist);
+
+    return candidates.slice(0, SUGGESTION_COUNT).map(c => ({
+        foreground: formatColor(c.fg),
+        background: formatColor(c.bg),
+        contrastRatio: c.ratio,
+        distance: c.dist,
+    }));
+}
+
+module.exports = {
+    suggestContrast,
+    computeContrastRatio,
+};

package/test/colorConversions.test.js

@@ -0,0 +1,223 @@
+import { describe, it, expect } from 'vitest';
+import {
+    hexToRgb,
+    rgbToHex,
+    rgbToHsl,
+    hslToRgb,
+    parseAnyColor,
+    hslToString,
+    rgbToString,
+} from '../src/colorConversions.js';
+
+describe('colorConversions', () => {
+    // ---- hexToRgb ----
+    describe('hexToRgb', () => {
+        it('should parse 6-digit hex with # prefix', () => {
+            expect(hexToRgb('#FF8800')).toEqual({ r: 255, g: 136, b: 0 });
+        });
+
+        it('should parse 3-digit hex with # prefix', () => {
+            expect(hexToRgb('#F80')).toEqual({ r: 255, g: 136, b: 0 });
+        });
+
+        it('should return null for invalid input', () => {
+            expect(hexToRgb('not-a-color')).toBeNull();
+            expect(hexToRgb('')).toBeNull();
+            expect(hexToRgb(null)).toBeNull();
+            expect(hexToRgb(undefined)).toBeNull();
+        });
+
+        it('should parse hex without # prefix', () => {
+            expect(hexToRgb('FF8800')).toEqual({ r: 255, g: 136, b: 0 });
+        });
+
+        it('should handle lowercase hex', () => {
+            expect(hexToRgb('#ff8800')).toEqual({ r: 255, g: 136, b: 0 });
+        });
+
+        it('should handle black and white', () => {
+            expect(hexToRgb('#000000')).toEqual({ r: 0, g: 0, b: 0 });
+            expect(hexToRgb('#FFFFFF')).toEqual({ r: 255, g: 255, b: 255 });
+        });
+
+        it('should return null for non-string input', () => {
+            expect(hexToRgb(123)).toBeNull();
+            expect(hexToRgb({})).toBeNull();
+        });
+    });
+
+    // ---- rgbToHex ----
+    describe('rgbToHex', () => {
+        it('should convert a color to hex', () => {
+            expect(rgbToHex({ r: 255, g: 136, b: 0 })).toBe('#ff8800');
+        });
+
+        it('should convert black', () => {
+            expect(rgbToHex({ r: 0, g: 0, b: 0 })).toBe('#000000');
+        });
+
+        it('should convert white', () => {
+            expect(rgbToHex({ r: 255, g: 255, b: 255 })).toBe('#ffffff');
+        });
+
+        it('should return null for invalid input', () => {
+            expect(rgbToHex(null)).toBeNull();
+            expect(rgbToHex({})).toBeNull();
+            expect(rgbToHex({ r: 'a', g: 0, b: 0 })).toBeNull();
+        });
+
+        it('should clamp values to 0-255 range', () => {
+            expect(rgbToHex({ r: 300, g: -10, b: 128 })).toBe('#ff0080');
+        });
+    });
+
+    // ---- rgbToHsl ----
+    describe('rgbToHsl', () => {
+        it('should convert pure red', () => {
+            expect(rgbToHsl({ r: 255, g: 0, b: 0 })).toEqual({ h: 0, s: 100, l: 50 });
+        });
+
+        it('should convert pure white', () => {
+            expect(rgbToHsl({ r: 255, g: 255, b: 255 })).toEqual({ h: 0, s: 0, l: 100 });
+        });
+
+        it('should convert pure black', () => {
+            expect(rgbToHsl({ r: 0, g: 0, b: 0 })).toEqual({ h: 0, s: 0, l: 0 });
+        });
+
+        it('should convert mid-gray', () => {
+            const hsl = rgbToHsl({ r: 128, g: 128, b: 128 });
+            expect(hsl.h).toBe(0);
+            expect(hsl.s).toBe(0);
+            expect(hsl.l).toBeCloseTo(50, 0);
+        });
+
+        it('should convert pure green', () => {
+            expect(rgbToHsl({ r: 0, g: 255, b: 0 })).toEqual({ h: 120, s: 100, l: 50 });
+        });
+
+        it('should convert pure blue', () => {
+            expect(rgbToHsl({ r: 0, g: 0, b: 255 })).toEqual({ h: 240, s: 100, l: 50 });
+        });
+
+        it('should return null for invalid input', () => {
+            expect(rgbToHsl(null)).toBeNull();
+            expect(rgbToHsl({ r: 'a', g: 0, b: 0 })).toBeNull();
+        });
+    });
+
+    // ---- hslToRgb ----
+    describe('hslToRgb', () => {
+        it('should convert pure red hsl', () => {
+            expect(hslToRgb({ h: 0, s: 100, l: 50 })).toEqual({ r: 255, g: 0, b: 0 });
+        });
+
+        it('should convert pure white hsl', () => {
+            expect(hslToRgb({ h: 0, s: 0, l: 100 })).toEqual({ r: 255, g: 255, b: 255 });
+        });
+
+        it('should convert pure green hsl', () => {
+            expect(hslToRgb({ h: 120, s: 100, l: 50 })).toEqual({ r: 0, g: 255, b: 0 });
+        });
+
+        it('should convert pure black hsl', () => {
+            expect(hslToRgb({ h: 0, s: 0, l: 0 })).toEqual({ r: 0, g: 0, b: 0 });
+        });
+
+        it('should handle achromatic gray', () => {
+            const rgb = hslToRgb({ h: 0, s: 0, l: 50 });
+            expect(rgb.r).toBe(128);
+            expect(rgb.g).toBe(128);
+            expect(rgb.b).toBe(128);
+        });
+
+        it('should return null for invalid input', () => {
+            expect(hslToRgb(null)).toBeNull();
+            expect(hslToRgb({ h: 'a', s: 0, l: 0 })).toBeNull();
+        });
+    });
+
+    // ---- round-trip ----
+    describe('RGB <-> HSL round-trip', () => {
+        const testColors = [
+            { r: 255, g: 0, b: 0 },
+            { r: 0, g: 255, b: 0 },
+            { r: 0, g: 0, b: 255 },
+            { r: 255, g: 255, b: 0 },
+            { r: 128, g: 64, b: 32 },
+        ];
+
+        testColors.forEach(rgb => {
+            it(`should round-trip rgb(${rgb.r}, ${rgb.g}, ${rgb.b})`, () => {
+                const hsl = rgbToHsl(rgb);
+                const backToRgb = hslToRgb(hsl);
+                // Allow ±2 rounding tolerance (double rounding through integer HSL)
+                expect(Math.abs(backToRgb.r - rgb.r)).toBeLessThanOrEqual(2);
+                expect(Math.abs(backToRgb.g - rgb.g)).toBeLessThanOrEqual(2);
+                expect(Math.abs(backToRgb.b - rgb.b)).toBeLessThanOrEqual(2);
+            });
+        });
+    });
+
+    // ---- parseAnyColor ----
+    describe('parseAnyColor', () => {
+        it('should parse hex color', () => {
+            expect(parseAnyColor('#FF0000')).toEqual({ r: 255, g: 0, b: 0 });
+        });
+
+        it('should parse rgb() string', () => {
+            expect(parseAnyColor('rgb(128, 64, 32)')).toEqual({ r: 128, g: 64, b: 32 });
+        });
+
+        it('should parse hsl() string', () => {
+            const rgb = parseAnyColor('hsl(120, 100%, 50%)');
+            expect(rgb).toEqual({ r: 0, g: 255, b: 0 });
+        });
+
+        it('should return null for null/undefined/empty', () => {
+            expect(parseAnyColor(null)).toBeNull();
+            expect(parseAnyColor(undefined)).toBeNull();
+            expect(parseAnyColor('')).toBeNull();
+        });
+
+        it('should return null for non-string input', () => {
+            expect(parseAnyColor(123)).toBeNull();
+            expect(parseAnyColor({})).toBeNull();
+        });
+
+        it('should parse 3-digit hex', () => {
+            expect(parseAnyColor('#F00')).toEqual({ r: 255, g: 0, b: 0 });
+        });
+
+        it('should parse rgba() string', () => {
+            const result = parseAnyColor('rgba(100, 200, 50, 0.5)');
+            expect(result.r).toBe(100);
+            expect(result.g).toBe(200);
+            expect(result.b).toBe(50);
+        });
+    });
+
+    // ---- hslToString ----
+    describe('hslToString', () => {
+        it('should format HSL object as CSS string', () => {
+            expect(hslToString({ h: 200, s: 50, l: 30 })).toBe('hsl(200, 50%, 30%)');
+        });
+
+        it('should return null for invalid input', () => {
+            expect(hslToString(null)).toBeNull();
+            expect(hslToString({})).toBeNull();
+        });
+    });
+
+    // ---- rgbToString ----
+    describe('rgbToString', () => {
+        it('should format RGB object as CSS string', () => {
+            expect(rgbToString({ r: 128, g: 64, b: 32 })).toBe('rgb(128, 64, 32)');
+        });
+
+        it('should return null for invalid input', () => {
+            expect(rgbToString(null)).toBeNull();
+            expect(rgbToString({})).toBeNull();
+        });
+    });
+});

package/test/stringUtils.test.js

@@ -436,6 +436,66 @@ describe('stringUtils', () => {
         });
     });
 
+    describe('containsVisibleText', () => {
+        it('should return true when accessible name exactly matches visible text', () => {
+            expect(stringUtils.containsVisibleText('Home', 'Home')).toBe(true);
+        });
+
+        it('should return true when accessible name is a superset of visible text', () => {
+            expect(
+                stringUtils.containsVisibleText(
+                    'Report a Concern Opens in new window',
+                    'Report a Concern'
+                )
+            ).toBe(true);
+        });
+
+        it('should be case-insensitive', () => {
+            expect(stringUtils.containsVisibleText('REPORT A CONCERN', 'Report a Concern')).toBe(
+                true
+            );
+        });
+
+        it('should return false when visible text is a partial word match', () => {
+            expect(stringUtils.containsVisibleText('Homepage', 'Home')).toBe(false);
+        });
+
+        it('should return false when accessible name does not contain visible text', () => {
+            expect(
+                stringUtils.containsVisibleText('Click here for more information', 'Learn more')
+            ).toBe(false);
+        });
+
+        it('should return false for null/undefined inputs', () => {
+            expect(stringUtils.containsVisibleText(null, 'text')).toBe(false);
+            expect(stringUtils.containsVisibleText('text', null)).toBe(false);
+            expect(stringUtils.containsVisibleText(undefined, undefined)).toBe(false);
+        });
+
+        it('should return false for empty visible text', () => {
+            expect(stringUtils.containsVisibleText('some name', '')).toBe(false);
+            expect(stringUtils.containsVisibleText('some name', '   ')).toBe(false);
+        });
+
+        it('should normalize whitespace before matching', () => {
+            expect(stringUtils.containsVisibleText('Report  a   Concern', 'Report a Concern')).toBe(
+                true
+            );
+        });
+
+        it('should match visible text at the end of accessible name', () => {
+            expect(stringUtils.containsVisibleText('Click here to Search', 'Search')).toBe(true);
+        });
+
+        it('should not match across word boundaries at end', () => {
+            expect(stringUtils.containsVisibleText('Searching', 'Search')).toBe(false);
+        });
+
+        it('should handle visible text that is the entire accessible name', () => {
+            expect(stringUtils.containsVisibleText('Buy now', 'Buy now')).toBe(true);
+        });
+    });
+
     describe('hasNewWindowWarning', () => {
         it('should return true for text containing "new window"', () => {
             expect(stringUtils.hasNewWindowWarning('Opens in a new window')).toBe(true);