This document provides comprehensive information about the testing setup and strategies used in the Aantekeningen App.
The application uses a multi-layered testing approach with different types of tests for different purposes:
- Unit Tests: Test individual functions and components in isolation
- Integration Tests: Test the interaction between different modules and API endpoints
- End-to-End (E2E) Tests: Test complete user workflows in a real browser environment
- Smoke Tests: Basic tests to ensure critical functionalities are working
- Performance Tests: Measure API response times, database query efficiency, and memory usage
- Security Tests: Validate authentication, authorization, and input sanitization
¶ Test Commands
npm run test:ci
npm run test:unit # Unit tests
npm run test:integration # Integration tests
npm run test:e2e # E2E tests
npm run test:security # Security tests
npm run test:performance # Performance tests
npm run test:smoke # Smoke tests
npm run test:watch # Watch mode
npm run test:ui # Interactive UI
npm run test:coverage # Coverage report
npm run test:summary # Test summary
Install Playwright browsers:
npx playwright install
npm run test:e2e
Most E2E tests use mocked authentication for speed. For real authentication testing:
REAL_AUTH=true npm run test:e2e tests/e2e/admin-auth-real.spec.ts
- Tests the main student search functionality
- Validates UI responsiveness and user interactions
- Uses real API endpoints (no mocking)
- Includes data-testid attributes for reliable element selection
- Tests admin authentication and navigation
- Uses mocked Firebase authentication for speed
- Tests real UI interactions without API mocking
- Validates admin-specific functionality
- Tests actual Google OAuth flow
- Requires
REAL_AUTH=true environment variable
- Needs
REAL_AUTH_EMAIL and REAL_AUTH_PASSWORD for test credentials
- Validates complete authentication workflow
The application uses data-testid attributes for reliable element selection in E2E tests:
data-testid="student-results" - Search results containerdata-testid="no-results" - Empty state messagedata-testid="loading" - Loading state indicatordata-testid="error-message" - Error message displaydata-testid="files-list" - Files list containerdata-testid="file-link" - Individual file download links
data-testid="admin-nav" - Main navigation componentdata-testid="mobile-menu-button" - Mobile menu toggledata-testid="logout-button" - Logout button
- Unit tests: 80%+ coverage target
- Integration tests: 70%+ coverage target
- Overall: 75%+ coverage target
npm run test:coverage
- Uses Node.js environment for server-side tests
- Includes path aliases for
@/* imports
- Excludes E2E tests (handled by Playwright)
- Configured for TypeScript support
- Tests against local development server
- Includes multiple browsers (Chromium, Firefox, WebKit)
- Configured for CI/CD environments
- Includes retry logic for flaky tests
- Use
vi.mock() for external dependencies
- Mock Firebase Admin SDK, Google Drive API, and OpenAI API
- Isolated testing of individual functions
- Mock external APIs but test real internal logic
- Use
mockResolvedValueOnce for API responses
- Test actual database operations with test data
- Student Portal: No mocking - tests real API endpoints
- Admin Portal: Mock Firebase authentication, test real UI
- Real Auth Tests: No mocking - complete end-to-end testing
REAL_AUTH=true # Enable real auth tests
[email protected] # Test Google account email
REAL_AUTH_PASSWORD=password # Test Google account password
NODE_ENV=test
FIREBASE_PROJECT_ID=test-project
GOOGLE_APPLICATION_CREDENTIALS=path/to/test-credentials.json
Tests run automatically on every push and pull request via GitHub Actions. The CI pipeline:
- Installs dependencies
- Runs linting and type checking
- Executes unit and integration tests
- Runs E2E tests (with browser installation)
- Generates coverage reports
- Publishes test results
- Ensure browsers are installed:
npx playwright install
- Check that the development server is running
- Verify environment variables are set correctly
- Check that mocks are properly configured in test setup
- Ensure mock implementations match real API responses
- Verify mock cleanup between tests
- Check that all source files are included in coverage
- Verify test files are properly excluded
- Ensure coverage thresholds are realistic
# Run tests with debug output
DEBUG=* npm run test:e2e
# Run specific test with debug
npx playwright test --debug tests/e2e/student-portal.spec.ts
- Arrange-Act-Assert: Structure tests clearly
- Descriptive Names: Use clear, descriptive test names
- Single Responsibility: Each test should test one thing
- Independent Tests: Tests should not depend on each other
- Clean Setup: Use proper setup and teardown
- Use Data Test IDs: Prefer
data-testid over CSS selectors
- Wait for Elements: Use proper waiting strategies
- Test User Flows: Focus on complete user journeys
- Handle Async Operations: Account for loading states
- Clean State: Ensure tests start with clean state
- Realistic Data: Use production-like data volumes
- Multiple Scenarios: Test various load conditions
- Monitor Resources: Track memory and CPU usage
- Baseline Metrics: Establish performance baselines
- Regression Detection: Alert on performance degradation
When adding new features:
- Write Tests First: Follow TDD principles
- Update Documentation: Keep this file current
- Add Data Test IDs: Include test IDs for new UI elements
- Test Edge Cases: Cover error conditions and edge cases
- Performance Considerations: Add performance tests for critical paths