@jmruthers/pace-core 0.2.6 → 0.4.1

package/src/theming/__tests__/README.md

@@ -1,335 +0,0 @@
-# Theming Runtime Tests
-
-This directory contains comprehensive tests for the PACE Core theming runtime system. The tests ensure the dynamic theming functionality works correctly across various scenarios, environments, and edge cases.
-
-## Test Structure
-
-### Test Files Overview
-
-| File | Purpose | Coverage |
-|------|---------|----------|
-| `runtime.unit.test.ts` | Core unit tests for all runtime functions | Function behavior, interfaces, basic error handling |
-| `runtime.integration.test.ts` | Real DOM integration tests | DOM manipulation, CSS injection, style element management |
-| `runtime.performance.test.ts` | Performance and scalability tests | Large palettes, rapid operations, memory usage |
-| `runtime.accessibility.test.ts` | Accessibility compliance tests | WCAG compliance, color contrast, screen reader support |
-| `runtime.error.test.ts` | Error handling and edge cases | Invalid inputs, DOM failures, SSR compatibility |
-
-## Test Coverage
-
-### Core Functionality (runtime.unit.test.ts)
-
-#### ✅ Interface Validation
-- **ColorShade Interface**: Validates OKLCH color value structure
-- **ColorPalette Interface**: Tests shade mapping and incomplete palettes
-- **PaletteData Interface**: Validates complete palette structure with main/sec/acc
-
-#### ✅ Function Testing
-- **applyPalette()**: CSS generation, DOM injection, style element creation
-- **clearPalette()**: Style element removal, cleanup
-- **generateSSRThemeCSS()**: Server-side CSS generation
-- **isDynamicThemingActive()**: Theme state detection
-- **getCurrentThemeData()**: Theme data extraction (simplified implementation)
-
-#### ✅ Edge Cases
-- Malformed color values (NaN, Infinity, negative values)
-- Missing palette properties
-- SSR environment handling
-- DOM manipulation errors
-
-### DOM Integration (runtime.integration.test.ts)
-
-#### ✅ Real DOM Testing
-- Style element creation and injection
-- CSS content validation
-- Theme replacement behavior
-- Multiple apply/clear cycles
-
-#### ✅ CSS Variable Generation
-- Custom property injection
-- Palette section organization (main, sec, acc)
-- Shade progression (50-950)
-- Raw color handling
-
-#### ✅ Performance with Real DOM
-- Memory leak prevention
-- Large palette handling
-- CSS formatting and structure
-
-### Performance Testing (runtime.performance.test.ts)
-
-#### ✅ Execution Speed
-- Standard palette application (< 5ms)
-- Large palettes (< 20ms for 50 shades)
-- Extreme palettes (< 100ms for 200 shades)
-
-#### ✅ Memory Management
-- No memory leaks with repeated applications
-- Efficient cleanup
-- Concurrent operation handling
-
-#### ✅ Real-world Scenarios
-- Organisation theme switching
-- Event theme loading simulation
-- Rapid theme changes
-
-#### ✅ String Operations
-- OKLCH formatting efficiency
-- CSS concatenation performance
-- Large-scale color processing
-
-### Accessibility Testing (runtime.accessibility.test.ts)
-
-#### ✅ WCAG Compliance
-- **Level AA**: 4.5:1 contrast ratio minimum
-- **Level AAA**: 7:1 contrast ratio for high contrast
-- Color contrast validation across all palette types
-
-#### ✅ Color Blindness Support
-- Lightness difference validation
-- Consistent chroma progression
-- Semantic color naming (main/sec/acc vs red/blue/green)
-
-#### ✅ Assistive Technology Support
-- Screen reader compatibility
-- Programmatic theme detection
-- High contrast mode support
-- Achromatic (grayscale) palette handling
-
-#### ✅ Reduced Motion Support
-- Instant theme application (no animations)
-- Immediate cleanup
-- Performance considerations
-
-### Error Handling (runtime.error.test.ts)
-
-#### ✅ Invalid Color Values
-- NaN, Infinity, negative values
-- Extremely large numbers
-- Type coercion edge cases
-
-#### ✅ Malformed Data Structures
-- Missing palette properties
-- Null/undefined values
-- Empty objects
-- Circular references
-
-#### ✅ DOM Manipulation Failures
-- createElement failures
-- appendChild failures
-- getElementById failures
-- Style element method failures
-
-#### ✅ Environment Compatibility
-- SSR environment handling
-- Missing browser APIs
-- Console method availability
-- Performance API availability
-
-## Running the Tests
-
-### Individual Test Suites
-
-```bash
-# Run all theming tests
-npm test -- src/theming
-
-# Run specific test files
-npm test -- runtime.unit.test.ts
-npm test -- runtime.integration.test.ts
-npm test -- runtime.performance.test.ts
-npm test -- runtime.accessibility.test.ts
-npm test -- runtime.error.test.ts
-```
-
-### Test Categories
-
-```bash
-# Unit tests only
-npm test -- --testNamePattern="unit"
-
-# Integration tests only
-npm test -- --testNamePattern="integration"
-
-# Performance tests only
-npm test -- --testNamePattern="performance"
-
-# Accessibility tests only
-npm test -- --testNamePattern="accessibility"
-
-# Error handling tests only
-npm test -- --testNamePattern="error"
-```
-
-### Coverage Reports
-
-```bash
-# Generate coverage report for theming module
-npm test -- --coverage src/theming
-```
-
-## Test Dependencies
-
-### Required Packages
-
-- **vitest**: Test runner and assertion library
-- **jsdom**: DOM environment simulation for browser APIs
-- **@testing-library/react**: React component testing utilities (for integration tests)
-
-### Mock Requirements
-
-The tests use various mocking strategies:
-
-1. **DOM Mocking**: JSDOM for real DOM testing, manual mocks for unit tests
-2. **Console Mocking**: Spy on console methods to test warning/error handling
-3. **Performance Mocking**: Handle environments without performance.now()
-4. **Browser API Mocking**: Mock missing APIs for compatibility testing
-
-## Test Data Patterns
-
-### Standard Test Palette
-
-```typescript
-const createTestPalette = (): PaletteData => ({
-  main: {
-    '50': { L: 0.98, C: 0.007, H: 29.203 },
-    '500': { L: 0.7, C: 0.15, H: 29.203 },
-    '900': { L: 0.325, C: 0.133, H: 29.203 },
-    'raw': { L: 0.587, C: 0.24, H: 29.203 }
-  },
-  sec: { /* secondary colors */ },
-  acc: { /* accent colors */ }
-});
-```
-
-### Accessibility-Compliant Palette
-
-```typescript
-const createAccessiblePalette = (): PaletteData => ({
-  main: {
-    '50': { L: 0.98, C: 0.005, H: 220 },   // Very light
-    '900': { L: 0.2, C: 0.12, H: 220 },    // Very dark
-    // Ensures > 7:1 contrast ratio
-  },
-  // ...
-});
-```
-
-### Performance Test Palette
-
-```typescript
-const generateLargePalette = (shadeCount: number): PaletteData => {
-  // Generates palettes with many shades for performance testing
-};
-```
-
-## Assertion Patterns
-
-### DOM Assertions
-
-```typescript
-// Style element creation
-expect(document.getElementById('pace-theme-dynamic')).toBeTruthy();
-
-// CSS content validation
-expect(styleElement.textContent).toContain('--color-main-500:');
-expect(styleElement.textContent).toContain('oklch(0.5 0.2 220)');
-```
-
-### Performance Assertions
-
-```typescript
-// Execution time limits
-expect(executionTime).toBeLessThan(5); // milliseconds
-
-// Memory usage validation
-expect(document.head.children.length).toBe(1); // No leaks
-```
-
-### Accessibility Assertions
-
-```typescript
-// Contrast ratio validation
-expect(contrastRatio).toBeGreaterThan(4.5); // WCAG AA
-expect(contrastRatio).toBeGreaterThan(7);   // WCAG AAA
-```
-
-### Error Handling Assertions
-
-```typescript
-// Graceful error handling
-expect(() => applyPalette(invalidPalette)).not.toThrow();
-
-// SSR compatibility
-expect(consoleWarnSpy).toHaveBeenCalledWith('applyPalette: Document not available (SSR)');
-```
-
-## Test Quality Metrics
-
-### Coverage Goals
-- **Line Coverage**: > 95%
-- **Branch Coverage**: > 90%
-- **Function Coverage**: 100%
-- **Statement Coverage**: > 95%
-
-### Performance Benchmarks
-- Standard palette application: < 5ms
-- Large palette (50 shades): < 20ms
-- Extreme palette (200 shades): < 100ms
-- Memory leaks: 0 (verified through repeated operations)
-
-### Accessibility Standards
-- WCAG 2.1 Level AA compliance: 100% of test palettes
-- Color contrast validation: All critical combinations tested
-- Screen reader compatibility: Verified through semantic naming
-
-## Continuous Integration
-
-### Test Pipeline
-1. **Lint Tests**: ESLint validation of test code
-2. **Unit Tests**: Core functionality validation
-3. **Integration Tests**: DOM-based testing with JSDOM
-4. **Performance Tests**: Benchmark validation
-5. **Accessibility Tests**: WCAG compliance verification
-6. **Error Handling Tests**: Edge case coverage
-
-### Quality Gates
-- All tests must pass
-- Coverage thresholds must be met
-- Performance benchmarks must be satisfied
-- No accessibility violations in test palettes
-
-## Contributing to Tests
-
-### Adding New Tests
-
-1. **Choose Appropriate File**: Select the most relevant test file based on test type
-2. **Follow Patterns**: Use existing test patterns and naming conventions
-3. **Include Edge Cases**: Consider error conditions and boundary cases
-4. **Document Purpose**: Add clear descriptions for complex test scenarios
-5. **Update README**: Update this documentation if adding new test categories
-
-### Test Writing Guidelines
-
-1. **Descriptive Names**: Use clear, descriptive test names
-2. **Single Responsibility**: Each test should verify one specific behavior
-3. **Setup/Teardown**: Use beforeEach/afterEach for consistent test environments
-4. **Mock Appropriately**: Mock external dependencies, test real behavior
-5. **Assert Meaningfully**: Use specific assertions that verify expected behavior
-
-### Performance Test Considerations
-
-- Set realistic performance thresholds
-- Test on various data sizes
-- Consider memory usage patterns
-- Validate cleanup behavior
-- Test concurrent operations
-
-### Accessibility Test Requirements
-
-- Test color contrast ratios
-- Verify semantic naming
-- Check screen reader compatibility
-- Validate high contrast support
-- Test with various color vision deficiencies
-
-This comprehensive test suite ensures the PACE Core theming system is robust, performant, accessible, and reliable across all supported environments and use cases.