Sankofa/docs/infrastructure/TESTING.md

# Testing Documentation

## Overview

The Infrastructure Dashboard has comprehensive test coverage including unit tests, integration tests, and end-to-end (E2E) tests.

## Test Structure

```
src/
├── components/
│   └── infrastructure/
│       └── __tests__/          # Component tests
├── lib/
│   ├── hooks/
│   │   └── __tests__/          # Hook tests
│   ├── services/
│   │   └── __tests__/          # Service tests
│   └── validation/
│       └── __tests__/          # Validation tests
└── test-utils.tsx               # Test utilities

e2e/                              # E2E tests
├── infrastructure-dashboard.spec.ts
└── ...
```

## Running Tests

### Unit and Integration Tests

```bash
# Run all tests
npm run test

# Run with UI
npm run test:ui

# Run with coverage
npm run test:coverage

# Watch mode
npm run test -- --watch
```

### E2E Tests

```bash
# Run E2E tests
npm run test:e2e

# Run with UI
npm run test:e2e:ui

# Run specific browser
npx playwright test --project=chromium
```

### All Tests

```bash
# Run all tests (unit + E2E)
npm run test:all
```

## Test Coverage

### Current Coverage Targets

- **Lines**: 90%
- **Functions**: 90%
- **Branches**: 85%
- **Statements**: 90%

### Viewing Coverage

After running `npm run test:coverage`, open `coverage/index.html` in your browser to view detailed coverage reports.

## Test Types

### Unit Tests

Test individual components, hooks, and services in isolation.

**Example:**
```typescript
import { describe, it, expect } from 'vitest'
import { render, screen } from '@testing-library/react'
import { EmptyState } from '../EmptyState'

describe('EmptyState', () => {
  it('should render with title', () => {
    render(<EmptyState title="Test" description="Description" />)
    expect(screen.getByText('Test')).toBeInTheDocument()
  })
})
```

### Integration Tests

Test component interactions and data flow.

**Example:**
```typescript
import { renderWithProviders } from '@/lib/test-utils'
import { ComplianceMapping } from '../ComplianceMapping'

it('should render and display data', async () => {
  renderWithProviders(<ComplianceMapping />)
  await waitFor(() => {
    expect(screen.getByText('Italy')).toBeInTheDocument()
  })
})
```

### E2E Tests

Test complete user workflows in a real browser.

**Example:**
```typescript
import { test, expect } from '@playwright/test'

test('should navigate to topology page', async ({ page }) => {
  await page.goto('/infrastructure/docs')
  await page.getByRole('link', { name: /network topology/i }).click()
  await expect(page).toHaveURL(/.*\/topology/)
})
```

## Test Utilities

### renderWithProviders

Custom render function that includes all necessary providers:

```typescript
import { renderWithProviders } from '@/lib/test-utils'

renderWithProviders(<MyComponent />)
```

### Mocking

#### Mock API Calls

```typescript
global.fetch = vi.fn().mockResolvedValue({
  ok: true,
  json: async () => mockData,
})
```

#### Mock Next.js Router

Already set up in `vitest.setup.ts`:

```typescript
vi.mock('next/navigation', () => ({
  useRouter: () => ({
    push: vi.fn(),
    replace: vi.fn(),
  }),
}))
```

## Writing Tests

### Component Tests

1. Test rendering
2. Test user interactions
3. Test state changes
4. Test edge cases

### Hook Tests

1. Test return values
2. Test side effects
3. Test error handling
4. Test loading states

### Service Tests

1. Test core functionality
2. Test edge cases
3. Test error handling
4. Test data transformations

### E2E Tests

1. Test critical user flows
2. Test navigation
3. Test form submissions
4. Test error scenarios

## Best Practices

1. **Arrange-Act-Assert**: Structure tests clearly
2. **Test Behavior**: Test what users see/do, not implementation
3. **Isolation**: Each test should be independent
4. **Descriptive Names**: Test names should describe what they test
5. **Coverage**: Aim for high coverage but focus on critical paths
6. **Maintainability**: Keep tests simple and readable

## Continuous Integration

Tests run automatically on:
- Pull requests
- Commits to main branch
- Scheduled runs

## Debugging Tests

### Unit Tests

```bash
# Run specific test file
npm run test -- src/components/infrastructure/__tests__/EmptyState.test.tsx

# Run with debug output
npm run test -- --reporter=verbose
```

### E2E Tests

```bash
# Run in headed mode
npx playwright test --headed

# Debug mode
npx playwright test --debug

# Show browser
npx playwright test --ui
```

## Troubleshooting

### Common Issues

1. **Tests timing out**: Increase timeout or check async operations
2. **Mock not working**: Ensure mocks are set up before imports
3. **Coverage not updating**: Clear cache and rerun
4. **E2E tests failing**: Check if dev server is running

## Resources

- [Vitest Documentation](https://vitest.dev/)
- [React Testing Library](https://testing-library.com/react)
- [Playwright Documentation](https://playwright.dev/)