Testing Best Practices

---
applyTo: "**/*.test.ts, **/*.test.js, **/*.spec.ts, **/*.spec.js"
---

# Testing Development Instructions (2025)

_Last updated: October 2025_

- Always use the fetch tool to look up testing documentation: Jest (https://jestjs.io), Vitest (https://vitest.dev), Playwright (https://playwright.dev)
- Write tests that verify behavior, not implementation details
- Follow the Testing Trophy: focus on integration tests, with unit and E2E tests for edge cases
- Use descriptive test names that explain the expected behavior
- Implement the AAA pattern (Arrange, Act, Assert)
- Keep tests independent and isolated

**Core Principles:**

- Test user-facing behavior, not internal implementation
- Write tests that give confidence in your code
- Make tests easy to understand and maintain
- Use meaningful assertions with clear error messages
- Mock external dependencies appropriately
- Test edge cases and error conditions

**Unit Testing (Jest/Vitest):**

- Test individual functions and components in isolation
- Use describe blocks to group related tests
- Use beforeEach/afterEach for test setup and cleanup
- Mock external dependencies with vi.mock() or jest.mock()
- Test both happy path and error cases
- Use snapshots sparingly (prefer explicit assertions)

**Integration Testing:**

- Test multiple units working together
- Use realistic test data and scenarios
- Test API endpoints with proper request/response
- Test database operations with test database
- Verify error handling and edge cases
- Use test containers for external services

**E2E Testing (Playwright):**

- Test critical user flows end-to-end
- Use Page Object Model for maintainable tests
- Run tests in multiple browsers (Chromium, Firefox, WebKit)
- Implement proper wait strategies (avoid arbitrary timeouts)
- Test responsive design and accessibility
- Use test fixtures for reusable setup

**React Testing:**

- Use React Testing Library for component testing
- Query by accessible roles and labels (getByRole, getByLabelText)
- Use userEvent for user interactions (more realistic than fireEvent)
- Test component behavior, not implementation
- Wait for async updates with waitFor
- Test error boundaries and loading states

**Mocking:**

- Mock external APIs and services
- Use mock service workers (MSW) for API mocking
- Mock only what you need (prefer real implementations)
- Use spies to verify function calls
- Reset mocks between tests
- Document complex mocking scenarios

**Test Data:**

- Use factories or builders for test data creation
- Keep test data minimal and relevant
- Use meaningful variable names for test data
- Avoid magic numbers and strings
- Use fixtures for complex test scenarios
- Clean up test data after tests

**Assertions:**

- Use specific matchers (toEqual, toBe, toContain, etc.)
- Write custom matchers for complex assertions
- Group related assertions logically
- Use snapshot testing for large objects (sparingly)
- Verify error messages and types
- Test async operations with proper waiting

**Test Organization:**

- Organize tests near the code they test
- Use consistent file naming (*.test.ts, *.spec.ts)
- Group related tests with describe blocks
- Use it/test for individual test cases
- Keep tests focused on single behavior
- Use helper functions for common setup

**Performance:**

- Run tests in parallel when possible
- Use test.only and test.skip for debugging
- Optimize slow tests with better mocking
- Use watch mode for development
- Profile test execution time
- Run critical tests in CI first

**Coverage:**

- Aim for high coverage but focus on quality
- Cover edge cases and error paths
- Don't chase 100% coverage blindly
- Use coverage reports to find untested code
- Test critical business logic thoroughly
- Exclude generated files from coverage

**Best Practices:**

- Write tests before or alongside code (TDD/BDD)
- Keep tests simple and readable
- Avoid test interdependence
- Use descriptive test names (it should...)
- Test one thing per test case
- Review tests in code review

**Summary:**

> For all testing work, always use the fetch tool to look up the latest documentation. Write meaningful tests that give confidence, not just coverage percentages.