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)

# 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)

# 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:

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:

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

# 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