@birhaus/test-utils/README.md

BIRHAUS v3.0 Radical Minimalist Testing Framework - Glass morphism validators, generous spacing tests, and v3 component validation utilities

# @birhaus/test-utils

BIRHAUS-specific testing utilities for validating design system compliance and accessibility.

## Installation

```bash
npm install --save-dev @birhaus/test-utils
```

## Testing Utilities

### BIRHAUS Compliance Validation

```tsx
import { expectBirhausCompliance } from '@birhaus/test-utils'

test('button follows BIRHAUS principles', async () => {
  render(<BirhausButton labelEs="Guardar" labelEn="Save" />)
  await expectBirhausCompliance(screen.getByRole('button'))
})
```

### Miller's Law Validation

Ensure components don't exceed cognitive load limits (7±2 items).

```tsx
import { expectMillersLawCompliance } from '@birhaus/test-utils'

test('navigation respects Miller\'s Law', async () => {
  render(<Navigation items={navigationItems} />)
  await expectMillersLawCompliance(container, { maxItems: 7 })
})
```

### Spanish-first Testing

Validate bilingual labeling patterns.

```tsx
import { expectSpanishFirstLabeling } from '@birhaus/test-utils'

test('component has Spanish-first labels', async () => {
  render(<BirhausCard titleEs="Título" titleEn="Title" />)
  await expectSpanishFirstLabeling(container)
})
```

### Accessibility Validation

```tsx
import { expectAccessibilityCompliance } from '@birhaus/test-utils'

test('component meets WCAG AA+ standards', async () => {
  render(<BirhausInput labelEs="Nombre" />)
  await expectAccessibilityCompliance(container, { level: 'AA' })
})
```

### Undo Pattern Testing

```tsx
import { expectUndoPatternCompliance } from '@birhaus/test-utils'

test('destructive action supports undo', async () => {
  render(<DeleteButton undoConfig={{...}} />)
  await expectUndoPatternCompliance(container)
})
```

## Performance Testing

### Cognitive Load Metrics

```tsx
import { measureCognitiveLoad } from '@birhaus/test-utils'

test('interface has acceptable cognitive load', () => {
  const metrics = measureCognitiveLoad(container)
  expect(metrics.totalElements).toBeLessThan(9) // Miller's Law
  expect(metrics.primaryActions).toBeLessThan(4) // 4-3-1 rule
})
```

### Performance Benchmarks

```tsx
import { expectPerformanceCompliance } from '@birhaus/test-utils'

test('component meets performance thresholds', async () => {
  const { container } = render(<BirhausDataTable data={largeDataset} />)
  await expectPerformanceCompliance(container, {
    renderTime: 100, // ms
    memoryUsage: 50  // MB
  })
})
```

## Mock Data Generators

Generate BIRHAUS-compliant test data:

```tsx
import { 
  generateMockFinancialData,
  generateMockUserData,
  generateMockTransactionHistory 
} from '@birhaus/test-utils'

const mockDonations = generateMockFinancialData(50)
const mockMembers = generateMockUserData(25)
```

## Testing Presets

Common testing configurations:

```tsx
import { birhausTestingPresets } from '@birhaus/test-utils'

// Financial application testing
const financialTests = birhausTestingPresets.financial({
  currency: 'PYG',
  locale: 'es-PY'
})

// Educational platform testing  
const educationTests = birhausTestingPresets.education({
  studentRoles: ['student', 'teacher', 'admin']
})
```

## Integration

Works with popular testing frameworks:

- **Vitest** (recommended)
- **Jest**
- **React Testing Library**
- **Playwright** (for E2E testing)

### Setup Example

```tsx
// vitest.config.ts
import { defineConfig } from 'vitest/config'
import { birhausTestConfig } from '@birhaus/test-utils'

export default defineConfig({
  ...birhausTestConfig,
  test: {
    setupFiles: ['@birhaus/test-utils/setup']
  }
})
```

## Custom Matchers

Additional Jest/Vitest matchers:

```tsx
expect(element).toHaveSpanishFirstLabel()
expect(component).toRespectMillersLaw()
expect(action).toHaveUndoPattern()
expect(interface).toBeBirhausCompliant()
```

## CI/CD Integration

Use in GitHub Actions:

```yaml
- name: BIRHAUS Compliance Tests
  run: |
    npm run test:birhaus
    npm run test:accessibility
    npm run test:performance
```

## License

MIT - see [LICENSE](../../LICENSE) for details.