maternal-app/maternal-web/tests/README.md

# Testing Guide

This document describes the testing setup and best practices for the Maternal Web application.

## Test Structure

```
maternal-web/
├── components/
│   └── **/__tests__/          # Component unit tests
├── lib/
│   └── **/__tests__/          # Library/utility unit tests
├── tests/
│   └── e2e/                   # End-to-end tests
├── jest.config.js             # Jest configuration
├── jest.setup.ts              # Jest setup file
└── playwright.config.ts       # Playwright configuration
```

## Running Tests

### Unit Tests (Jest + React Testing Library)

```bash
# Run all unit tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### E2E Tests (Playwright)

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

# Run E2E tests with UI
npm run test:e2e:ui

# Run E2E tests in headed mode (see browser)
npm run test:e2e:headed
```

## Writing Tests

### Unit Tests

Unit tests should be placed in `__tests__` directories next to the code they test.

Example component test:

```typescript
import { render, screen } from '@testing-library/react'
import { MyComponent } from '../MyComponent'

describe('MyComponent', () => {
  it('renders correctly', () => {
    render(<MyComponent title="Test" />)
    expect(screen.getByText('Test')).toBeInTheDocument()
  })
})
```

### E2E Tests

E2E tests should be placed in `tests/e2e/` directory.

Example E2E test:

```typescript
import { test, expect } from '@playwright/test';

test('should navigate to page', async ({ page }) => {
  await page.goto('/');
  await expect(page.locator('h1')).toContainText('Welcome');
});
```

## Coverage Thresholds

The project maintains the following coverage thresholds:

- Branches: 70%
- Functions: 70%
- Lines: 70%
- Statements: 70%

## CI/CD Integration

Tests run automatically on:
- Every push to `master` or `main` branches
- Every pull request

The CI pipeline:
1. Runs linting
2. Runs unit tests with coverage
3. Runs E2E tests (Chromium only in CI)
4. Builds the application
5. Uploads test artifacts

## Best Practices

1. **Write tests for new features** - All new features should include tests
2. **Test user interactions** - Focus on testing what users see and do
3. **Keep tests simple** - Each test should test one thing
4. **Use descriptive test names** - Test names should describe what they test
5. **Avoid implementation details** - Test behavior, not implementation
6. **Mock external dependencies** - Use mocks for API calls and external services

## Useful Commands

```bash
# Run specific test file
npm test -- MyComponent.test.tsx

# Run tests matching pattern
npm test -- --testNamePattern="should render"

# Update snapshots
npm test -- -u

# Debug tests
node --inspect-brk node_modules/.bin/jest --runInBand

# Generate Playwright test code
npx playwright codegen http://localhost:3030
```

## Troubleshooting

### Jest

- **Tests timing out**: Increase timeout with `jest.setTimeout(10000)` in test file
- **Module not found**: Check `moduleNameMapper` in `jest.config.js`
- **Async tests failing**: Make sure to `await` async operations and use `async/await` in tests

### Playwright

- **Browser not launching**: Run `npx playwright install` to install browsers
- **Tests flaky**: Add `await page.waitForLoadState('networkidle')` or explicit waits
- **Selectors not working**: Use Playwright Inspector with `npx playwright test --debug`