@afixt/test-utils 2.0.0 → 2.1.0

package/test/suggestContrast.test.js

@@ -0,0 +1,394 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { suggestContrast, computeContrastRatio } from '../src/suggestContrast.js';
+
+describe('suggestContrast', () => {
+    // ---- Input validation ----
+    describe('input validation', () => {
+        it('should return empty array for null options', () => {
+            expect(suggestContrast(null)).toEqual([]);
+        });
+
+        it('should return empty array for undefined options', () => {
+            expect(suggestContrast(undefined)).toEqual([]);
+        });
+
+        it('should return empty array for non-object options', () => {
+            expect(suggestContrast('string')).toEqual([]);
+            expect(suggestContrast(42)).toEqual([]);
+        });
+
+        it('should return empty array for missing foreground', () => {
+            expect(suggestContrast({ background: '#FFFFFF' })).toEqual([]);
+        });
+
+        it('should return empty array for missing background', () => {
+            expect(suggestContrast({ foreground: '#000000' })).toEqual([]);
+        });
+
+        it('should return empty array for invalid foreground color', () => {
+            expect(suggestContrast({ foreground: 'not-a-color', background: '#FFFFFF' })).toEqual(
+                []
+            );
+        });
+
+        it('should return empty array for invalid background color', () => {
+            expect(suggestContrast({ foreground: '#000000', background: 'invalid' })).toEqual([]);
+        });
+
+        it('should return empty array for minRatio below 1', () => {
+            expect(
+                suggestContrast({ foreground: '#000000', background: '#FFFFFF', minRatio: 0.5 })
+            ).toEqual([]);
+        });
+
+        it('should return empty array for minRatio above 21', () => {
+            expect(
+                suggestContrast({ foreground: '#000000', background: '#FFFFFF', minRatio: 22 })
+            ).toEqual([]);
+        });
+    });
+
+    // ---- Basic functionality ----
+    describe('basic functionality', () => {
+        it('should return an array', () => {
+            const result = suggestContrast({
+                foreground: '#777777',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            expect(Array.isArray(result)).toBe(true);
+        });
+
+        it('should return at most 12 suggestions', () => {
+            const result = suggestContrast({
+                foreground: '#777777',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeLessThanOrEqual(12);
+        });
+
+        it('should return at least 1 suggestion for a low-contrast pair', () => {
+            const result = suggestContrast({
+                foreground: '#777777',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+        });
+    });
+
+    // ---- Result structure ----
+    describe('result structure', () => {
+        let result;
+
+        beforeAll(() => {
+            result = suggestContrast({
+                foreground: '#999999',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+        });
+
+        it('should have foreground with hex, rgb, and hsl properties', () => {
+            const suggestion = result[0];
+            expect(suggestion.foreground).toBeDefined();
+            expect(suggestion.foreground.hex).toBeDefined();
+            expect(suggestion.foreground.rgb).toBeDefined();
+            expect(suggestion.foreground.hsl).toBeDefined();
+        });
+
+        it('should have background with hex, rgb, and hsl properties', () => {
+            const suggestion = result[0];
+            expect(suggestion.background).toBeDefined();
+            expect(suggestion.background.hex).toBeDefined();
+            expect(suggestion.background.rgb).toBeDefined();
+            expect(suggestion.background.hsl).toBeDefined();
+        });
+
+        it('should have contrastRatio that meets the minimum', () => {
+            for (const suggestion of result) {
+                expect(suggestion.contrastRatio).toBeGreaterThanOrEqual(4.5);
+            }
+        });
+
+        it('should have a numeric distance property', () => {
+            for (const suggestion of result) {
+                expect(typeof suggestion.distance).toBe('number');
+                expect(suggestion.distance).toBeGreaterThanOrEqual(0);
+            }
+        });
+
+        it('should have valid hex values (7-character strings starting with #)', () => {
+            for (const suggestion of result) {
+                expect(suggestion.foreground.hex).toMatch(/^#[0-9a-f]{6}$/);
+                expect(suggestion.background.hex).toMatch(/^#[0-9a-f]{6}$/);
+            }
+        });
+
+        it('should have integer RGB values in 0-255 range', () => {
+            for (const suggestion of result) {
+                for (const color of [suggestion.foreground, suggestion.background]) {
+                    expect(Number.isInteger(color.rgb.r)).toBe(true);
+                    expect(Number.isInteger(color.rgb.g)).toBe(true);
+                    expect(Number.isInteger(color.rgb.b)).toBe(true);
+                    expect(color.rgb.r).toBeGreaterThanOrEqual(0);
+                    expect(color.rgb.r).toBeLessThanOrEqual(255);
+                    expect(color.rgb.g).toBeGreaterThanOrEqual(0);
+                    expect(color.rgb.g).toBeLessThanOrEqual(255);
+                    expect(color.rgb.b).toBeGreaterThanOrEqual(0);
+                    expect(color.rgb.b).toBeLessThanOrEqual(255);
+                }
+            }
+        });
+
+        it('should have HSL h in 0-360, s in 0-100, l in 0-100', () => {
+            for (const suggestion of result) {
+                for (const color of [suggestion.foreground, suggestion.background]) {
+                    expect(color.hsl.h).toBeGreaterThanOrEqual(0);
+                    expect(color.hsl.h).toBeLessThanOrEqual(360);
+                    expect(color.hsl.s).toBeGreaterThanOrEqual(0);
+                    expect(color.hsl.s).toBeLessThanOrEqual(100);
+                    expect(color.hsl.l).toBeGreaterThanOrEqual(0);
+                    expect(color.hsl.l).toBeLessThanOrEqual(100);
+                }
+            }
+        });
+    });
+
+    // ---- Contrast validity for specific pairs ----
+    describe('contrast validity', () => {
+        it('should produce valid suggestions for light gray on white', () => {
+            const result = suggestContrast({
+                foreground: '#CCCCCC',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(4.5);
+            }
+        });
+
+        it('should produce valid suggestions for dark gray on black', () => {
+            const result = suggestContrast({
+                foreground: '#333333',
+                background: '#000000',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(4.5);
+            }
+        });
+
+        it('should produce valid suggestions for red on green', () => {
+            const result = suggestContrast({
+                foreground: '#FF0000',
+                background: '#00FF00',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(4.5);
+            }
+        });
+
+        it('should produce suggestions even when pair already meets ratio', () => {
+            const result = suggestContrast({
+                foreground: '#000000',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(4.5);
+            }
+        });
+    });
+
+    // ---- Input format acceptance ----
+    describe('input format acceptance', () => {
+        it('should accept 6-digit hex colors', () => {
+            const result = suggestContrast({
+                foreground: '#FF0000',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+        });
+
+        it('should accept 3-digit hex colors', () => {
+            const result = suggestContrast({
+                foreground: '#F00',
+                background: '#FFF',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+        });
+
+        it('should accept rgb() strings', () => {
+            const result = suggestContrast({
+                foreground: 'rgb(255, 0, 0)',
+                background: 'rgb(255, 255, 255)',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+        });
+
+        it('should accept hsl() strings', () => {
+            const result = suggestContrast({
+                foreground: 'hsl(0, 100%, 50%)',
+                background: 'hsl(0, 0%, 100%)',
+                minRatio: 4.5,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+        });
+    });
+
+    // ---- Default minRatio behavior ----
+    describe('default minRatio', () => {
+        it('should default to 4.5 for normal text (fontSize < 18, not bold)', () => {
+            const result = suggestContrast({
+                foreground: '#999999',
+                background: '#FFFFFF',
+                fontSize: 14,
+            });
+            // All suggestions should meet 4.5 (the default for normal text)
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(4.5);
+            }
+        });
+
+        it('should default to 3.0 for large text (fontSize >= 18)', () => {
+            const result = suggestContrast({
+                foreground: '#999999',
+                background: '#FFFFFF',
+                fontSize: 18,
+            });
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(3.0);
+            }
+        });
+
+        it('should default to 3.0 for bold text >= 14px', () => {
+            const result = suggestContrast({
+                foreground: '#999999',
+                background: '#FFFFFF',
+                fontSize: 14,
+                isBold: true,
+            });
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(3.0);
+            }
+        });
+    });
+
+    // ---- Sorting and proximity ----
+    describe('sorting and proximity', () => {
+        it('should sort suggestions by distance (closest first)', () => {
+            const result = suggestContrast({
+                foreground: '#888888',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            if (result.length >= 2) {
+                for (let i = 1; i < result.length; i++) {
+                    expect(result[i].distance).toBeGreaterThanOrEqual(result[i - 1].distance);
+                }
+            }
+        });
+    });
+
+    // ---- Edge cases ----
+    describe('edge cases', () => {
+        it('should handle identical foreground and background colors', () => {
+            const result = suggestContrast({
+                foreground: '#808080',
+                background: '#808080',
+                minRatio: 4.5,
+            });
+            expect(Array.isArray(result)).toBe(true);
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(4.5);
+            }
+        });
+
+        it('should return limited results for very high ratio requirement', () => {
+            const result = suggestContrast({
+                foreground: '#808080',
+                background: '#808080',
+                minRatio: 20,
+            });
+            // Very high ratio is hard to achieve, expect few or no results
+            expect(Array.isArray(result)).toBe(true);
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(20);
+            }
+        });
+
+        it('should handle pure black on pure white', () => {
+            const result = suggestContrast({
+                foreground: '#000000',
+                background: '#FFFFFF',
+                minRatio: 7,
+            });
+            expect(result.length).toBeGreaterThanOrEqual(1);
+            for (const s of result) {
+                expect(s.contrastRatio).toBeGreaterThanOrEqual(7);
+            }
+        });
+    });
+
+    // ---- Diversity of results ----
+    describe('diversity of results', () => {
+        it('should produce diverse suggestions (not all identical)', () => {
+            const result = suggestContrast({
+                foreground: '#888888',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+            if (result.length >= 3) {
+                const uniquePairs = new Set(
+                    result.map(s => s.foreground.hex + '|' + s.background.hex)
+                );
+                expect(uniquePairs.size).toBeGreaterThanOrEqual(3);
+            }
+        });
+
+        it('should include both foreground-modified and background-modified suggestions', () => {
+            const result = suggestContrast({
+                foreground: '#888888',
+                background: '#FFFFFF',
+                minRatio: 4.5,
+            });
+
+            const hasFgModified = result.some(s => s.foreground.hex !== '#888888');
+            const hasBgModified = result.some(s => s.background.hex !== '#ffffff');
+            // At least one type of modification should be present
+            expect(hasFgModified || hasBgModified).toBe(true);
+        });
+    });
+
+    // ---- computeContrastRatio ----
+    describe('computeContrastRatio', () => {
+        it('should return 21 for black on white', () => {
+            expect(computeContrastRatio({ r: 0, g: 0, b: 0 }, { r: 255, g: 255, b: 255 })).toBe(21);
+        });
+
+        it('should return 1 for identical colors', () => {
+            expect(
+                computeContrastRatio({ r: 128, g: 128, b: 128 }, { r: 128, g: 128, b: 128 })
+            ).toBe(1);
+        });
+
+        it('should return a value between 1 and 21', () => {
+            const ratio = computeContrastRatio(
+                { r: 100, g: 50, b: 200 },
+                { r: 200, g: 200, b: 50 }
+            );
+            expect(ratio).toBeGreaterThanOrEqual(1);
+            expect(ratio).toBeLessThanOrEqual(21);
+        });
+    });
+});