Add formal test policy and reach 80% statement coverage

- Create CONTRIBUTING.md with formal test policy requiring tests for new functionality
- Add coverageThreshold (80% statements) to package.json Jest config
- Update CI workflow to run tests with --coverage
- Add/expand tests across 10 test files (1660 total tests, 80.75% coverage)

Author: bloo-berries

.github/workflows/ci.yml

@@ -31,4 +31,4 @@ jobs:
       run: npm run build
 
     - name: Run tests
-      run: npm test -- --passWithNoTests
+      run: npm test -- --passWithNoTests --coverage --watchAll=false

CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to Vision Condition Visualizer
+
+We welcome contributions! This document outlines the process for contributing to this project and the test requirements all contributions must meet.
+
+## Getting Started
+
+1. **Fork the repository**
+2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
+3. **Make your changes** (see guidelines below)
+4. **Ensure all tests pass**: `npm test -- --watchAll=false`
+5. **Commit your changes**: `git commit -m 'Add amazing feature'`
+6. **Push to the branch**: `git push origin feature/amazing-feature`
+7. **Open a Pull Request**
+
+## Test Policy
+
+**As major new functionality is added, tests for the new functionality MUST be added to an automated test suite.** This is a hard requirement for all pull requests that introduce or modify behavior.
+
+### What requires tests
+
+- **New features and components**: Any new React component, hook, or utility function must have corresponding unit tests.
+- **Bug fixes**: A regression test must accompany each bug fix to prevent recurrence.
+- **New visual effects or overlays**: Effect creation functions must be tested for element creation, cleanup, and edge cases (disabled/undefined input).
+- **New famous people utilities**: Any new mapping or parsing logic in `famousPeopleUtils` must be tested.
+- **Data transformations**: Functions that transform, filter, or aggregate data must have tests covering expected inputs and edge cases.
+
+### What does NOT require tests
+
+- **Documentation-only changes**: Updates to README, CONTRIBUTING, or other markdown files.
+- **CSS-only changes**: Pure styling changes with no logic.
+- **Translation files**: Adding or updating locale JSON files in `src/locales/`.
+- **Static data additions**: Adding entries to data arrays (e.g., a new person in `src/data/famousPeople/`) that use existing, already-tested code paths.
+- **Asset additions**: Adding images, fonts, or other static assets.
+
+### Test conventions
+
+- **Directory structure**: All tests live in `src/__tests__/`, mirroring the source directory structure:
+  - `src/__tests__/components/` for component tests
+  - `src/__tests__/hooks/` for hook tests
+  - `src/__tests__/utils/` for utility tests
+  - `src/__tests__/overlays/` for overlay/visual effect tests
+- **Test utilities**: Use `@testing-library/react` for component tests and `@testing-library/user-event` for user interaction simulation.
+- **Mocking**: CRA enables `resetMocks` by default, so all `jest.fn()` mocks are automatically reset between tests. Module mocks (`jest.mock(...)`) must be declared at the top of the file, before imports of the mocked module.
+- **Naming**: Test files should be named `<ModuleName>.test.ts` or `<ModuleName>.test.tsx`.
+- **Coverage threshold**: The project enforces a minimum of 80% statement coverage in CI. Run `npm test -- --watchAll=false --coverage` locally to verify before submitting.
+
+## Code Style
+
+This project follows the [Create React App ESLint configuration](https://www.npmjs.com/package/eslint-config-react-app) with additional rules defined in `package.json`. TypeScript strict mode provides further enforcement. CI treats all ESLint warnings as errors (`CI=true`), so contributions must pass linting to be merged. Suppress intentional console statements with `// eslint-disable-next-line no-console`.
+
+## Areas for Contribution
+
+- **New vision conditions**: Add more realistic simulations
+- **Additional famous people**: Expand the educational content
+- **Accessibility improvements**: Enhance screen reader support
+- **Performance optimization**: Improve rendering speed
+- **Mobile experience**: Enhance touch interactions
+- **New languages**: Add translation files for more locales

package.json

@@ -54,6 +54,13 @@
       "no-var": "error"
     }
   },
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "statements": 80
+      }
+    }
+  },
   "browserslist": {
     "production": [
       ">0.2%",

readme.md

@@ -247,28 +247,7 @@ Deployed to **Cloudflare Pages** at [theblind.spot](https://theblind.spot). The
 
 ## Contributing
 
-We welcome contributions! Here's how you can help:
-
-1. **Fork the repository**
-2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
-3. **Add tests** for new functionality or bug fixes in `src/__tests__/`
-4. **Ensure all tests pass**: `npm test -- --watchAll=false`
-5. **Commit your changes**: `git commit -m 'Add amazing feature'`
-6. **Push to the branch**: `git push origin feature/amazing-feature`
-7. **Open a Pull Request**
-
-### Code Style
-
-This project follows the [Create React App ESLint configuration](https://www.npmjs.com/package/eslint-config-react-app) with additional rules defined in `package.json`. TypeScript strict mode provides further enforcement. CI treats all ESLint warnings as errors, so contributions must pass linting to be merged.
-
-### Areas for Contribution
-
-- **New vision conditions**: Add more realistic simulations
-- **Additional famous people**: Expand the educational content
-- **Accessibility improvements**: Enhance screen reader support
-- **Performance optimization**: Improve rendering speed
-- **Mobile experience**: Enhance touch interactions
-- **New languages**: Add translation files for more locales
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, including our **test policy** requiring tests for all new functionality.
 
 ## License
 

src/__tests__/colorVisionFilters.test.ts

@@ -1,4 +1,4 @@
-import { getColorVisionFilter, getColorVisionMatrix, cleanupAllDOMFilters, isColorVisionCondition } from '../utils/colorVisionFilters';
+import { getColorVisionFilter, getColorVisionMatrix, cleanupAllDOMFilters, isColorVisionCondition, getColorVisionFilterData, _resetMobileDetection, isMobileBrowser, getColorVisionDescription, getColorVisionPrevalence } from '../utils/colorVisionFilters';
 import { ConditionType } from '../types/visualEffects';
 
 describe('getColorVisionFilter', () => {
@@ -125,6 +125,134 @@ describe('isColorVisionCondition', () => {
   });
 });
 
+describe('getColorVisionFilterData', () => {
+  test('returns filter data for protanopia', () => {
+    const data = getColorVisionFilterData('protanopia' as ConditionType, 1.0);
+    expect(data).not.toBeNull();
+    expect(data!.filterId).toBe('cvd-protanopia');
+    expect(data!.matrixValues).toBeTruthy();
+  });
+
+  test('returns null for monochromacy', () => {
+    const data = getColorVisionFilterData('monochromacy' as ConditionType, 1.0);
+    expect(data).toBeNull();
+  });
+
+  test('returns null for monochromatic', () => {
+    const data = getColorVisionFilterData('monochromatic' as ConditionType, 1.0);
+    expect(data).toBeNull();
+  });
+
+  test('returns null at zero intensity', () => {
+    const data = getColorVisionFilterData('protanopia' as ConditionType, 0);
+    expect(data).toBeNull();
+  });
+
+  test('matrix values contain 20 numbers for 5x4 matrix', () => {
+    const data = getColorVisionFilterData('deuteranopia' as ConditionType, 0.7);
+    expect(data).not.toBeNull();
+    const nums = data!.matrixValues.split(' ');
+    expect(nums).toHaveLength(20);
+  });
+
+  test('partial intensity produces blended matrix', () => {
+    const dataFull = getColorVisionFilterData('tritanopia' as ConditionType, 1.0);
+    const dataHalf = getColorVisionFilterData('tritanopia' as ConditionType, 0.5);
+    expect(dataFull).not.toBeNull();
+    expect(dataHalf).not.toBeNull();
+    expect(dataFull!.matrixValues).not.toBe(dataHalf!.matrixValues);
+  });
+});
+
+describe('_resetMobileDetection', () => {
+  test('can be called without error', () => {
+    expect(() => _resetMobileDetection()).not.toThrow();
+  });
+});
+
+describe('isMobileBrowser', () => {
+  afterEach(() => {
+    _resetMobileDetection();
+  });
+
+  test('returns false in JSDOM environment', () => {
+    _resetMobileDetection();
+    expect(isMobileBrowser()).toBe(false);
+  });
+
+  test('result is cached after first call', () => {
+    _resetMobileDetection();
+    const first = isMobileBrowser();
+    const second = isMobileBrowser();
+    expect(first).toBe(second);
+  });
+});
+
+describe('getColorVisionFilter mobile path', () => {
+  const originalMatchMedia = window.matchMedia;
+  const originalUserAgent = Object.getOwnPropertyDescriptor(navigator, 'userAgent');
+
+  afterEach(() => {
+    _resetMobileDetection();
+    cleanupAllDOMFilters();
+    window.matchMedia = originalMatchMedia;
+    if (originalUserAgent) {
+      Object.defineProperty(navigator, 'userAgent', originalUserAgent);
+    }
+  });
+
+  test('returns CSS filter string on mobile for protanopia', () => {
+    _resetMobileDetection();
+    // Simulate mobile UA
+    Object.defineProperty(navigator, 'userAgent', {
+      value: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)',
+      configurable: true,
+    });
+    window.matchMedia = jest.fn().mockReturnValue({ matches: false }) as any;
+
+    const filter = getColorVisionFilter('protanopia' as ConditionType, 1.0);
+    expect(filter).toContain('sepia');
+    expect(filter).toContain('hue-rotate');
+  });
+
+  test('returns scaled CSS filter at partial intensity on mobile', () => {
+    _resetMobileDetection();
+    Object.defineProperty(navigator, 'userAgent', {
+      value: 'Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)',
+      configurable: true,
+    });
+    window.matchMedia = jest.fn().mockReturnValue({ matches: false }) as any;
+
+    const filter = getColorVisionFilter('deuteranopia' as ConditionType, 0.5);
+    expect(filter).toContain('sepia');
+    expect(filter).toContain('saturate');
+  });
+});
+
+describe('cleanupAllDOMFilters', () => {
+  beforeEach(() => {
+    _resetMobileDetection();
+  });
+
+  test('removes all injected SVG filter elements', () => {
+    // Ensure we're not in mobile mode
+    _resetMobileDetection();
+    getColorVisionFilter('protanopia' as ConditionType, 1.0);
+    const container = document.getElementById('cvd-svg-filters');
+    // On desktop, SVG filters should be created
+    if (container) {
+      cleanupAllDOMFilters();
+      expect(document.getElementById('cvd-svg-filters')).toBeNull();
+      expect(document.getElementById('cvd-protanopia')).toBeNull();
+    }
+  });
+
+  test('is safe to call when no filters exist', () => {
+    cleanupAllDOMFilters();
+    expect(() => cleanupAllDOMFilters()).not.toThrow();
+  });
+});
+
 describe('getColorVisionMatrix', () => {
   test('returns identity matrix for unknown condition', () => {
     const matrix = getColorVisionMatrix('unknownCondition' as ConditionType);
@@ -150,6 +278,19 @@ describe('getColorVisionMatrix', () => {
     expect(matrix).toHaveLength(9);
   });
 
+  test('monochromatic returns achromatopsia matrix', () => {
+    const matrix = getColorVisionMatrix('monochromatic' as ConditionType, 1.0);
+    const identity = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+    expect(matrix).not.toEqual(identity);
+    expect(matrix).toHaveLength(9);
+  });
+
+  test('monochromacy returns same matrix as monochromatic', () => {
+    const monochromatic = getColorVisionMatrix('monochromatic' as ConditionType, 1.0);
+    const monochromacy = getColorVisionMatrix('monochromacy' as ConditionType, 1.0);
+    expect(monochromatic).toEqual(monochromacy);
+  });
+
   test('anomaly interpolation produces intermediate values', () => {
     const at0 = getColorVisionMatrix('protanomaly' as ConditionType, 0.0);
     const at05 = getColorVisionMatrix('protanomaly' as ConditionType, 0.5);
@@ -158,3 +299,60 @@ describe('getColorVisionMatrix', () => {
     expect(at05).not.toEqual(at1);
   });
 });
+
+describe('getColorVisionDescription', () => {
+  test('returns description for protanopia', () => {
+    const desc = getColorVisionDescription('protanopia' as ConditionType);
+    expect(desc).toContain('red-blindness');
+    expect(desc).toContain('L-cones');
+  });
+
+  test('returns description for deuteranopia', () => {
+    const desc = getColorVisionDescription('deuteranopia' as ConditionType);
+    expect(desc).toContain('green-blindness');
+  });
+
+  test('returns description for tritanopia', () => {
+    const desc = getColorVisionDescription('tritanopia' as ConditionType);
+    expect(desc).toContain('blue-blindness');
+  });
+
+  test('returns description for anomaly types', () => {
+    expect(getColorVisionDescription('protanomaly' as ConditionType)).toContain('red-weakness');
+    expect(getColorVisionDescription('deuteranomaly' as ConditionType)).toContain('green-weakness');
+    expect(getColorVisionDescription('tritanomaly' as ConditionType)).toContain('blue-weakness');
+  });
+
+  test('returns description for monochromacy', () => {
+    const desc = getColorVisionDescription('monochromacy' as ConditionType);
+    expect(desc).toContain('achromatopsia');
+  });
+
+  test('returns fallback for unknown type', () => {
+    const desc = getColorVisionDescription('unknownType' as ConditionType);
+    expect(desc).toBe('Color vision deficiency simulation');
+  });
+});
+
+describe('getColorVisionPrevalence', () => {
+  test('returns prevalence for protanopia', () => {
+    const prev = getColorVisionPrevalence('protanopia' as ConditionType);
+    expect(prev).toContain('males');
+    expect(prev).toContain('females');
+  });
+
+  test('returns prevalence for deuteranomaly as most common', () => {
+    const prev = getColorVisionPrevalence('deuteranomaly' as ConditionType);
+    expect(prev).toContain('6%');
+  });
+
+  test('returns prevalence for monochromacy', () => {
+    const prev = getColorVisionPrevalence('monochromacy' as ConditionType);
+    expect(prev).toContain('30,000');
+  });
+
+  test('returns unknown for unrecognized type', () => {
+    const prev = getColorVisionPrevalence('unknownType' as ConditionType);
+    expect(prev).toBe('Unknown prevalence');
+  });
+});