Initial commit: Complete NodeJS-native setup
- Migrated from Python pre-commit to NodeJS-native solution - Reorganized documentation structure - Set up Husky + lint-staged for efficient pre-commit hooks - Fixed Dockerfile healthcheck issue - Added comprehensive documentation index
This commit is contained in:
William Valentin
319
tests/e2e/README.md
Normal file
319
tests/e2e/README.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 🎭 End-to-End Testing with Playwright
|
||||
|
||||
## Overview
|
||||
|
||||
This directory contains comprehensive end-to-end tests for the Medication Reminder App using Playwright. These tests simulate real user interactions across different browsers and devices.
|
||||
|
||||
## Test Structure
|
||||
|
||||
```
|
||||
tests/e2e/
|
||||
├── README.md # This documentation
|
||||
├── fixtures.ts # Custom test fixtures and utilities
|
||||
├── helpers.ts # Test helper functions and data
|
||||
├── auth.spec.ts # Authentication flow tests
|
||||
├── medication.spec.ts # Medication management tests
|
||||
├── admin.spec.ts # Admin interface tests
|
||||
├── ui-navigation.spec.ts # UI and navigation tests
|
||||
└── reminders.spec.ts # Reminder system tests
|
||||
```
|
||||
|
||||
## Test Categories
|
||||
|
||||
### 🔐 **Authentication Tests** (`auth.spec.ts`)
|
||||
|
||||
- User registration and login
|
||||
- Admin authentication
|
||||
- OAuth button visibility
|
||||
- Invalid credential handling
|
||||
- Session management
|
||||
|
||||
### 💊 **Medication Management** (`medication.spec.ts`)
|
||||
|
||||
- Adding new medications
|
||||
- Editing existing medications
|
||||
- Deleting medications
|
||||
- Marking doses as taken
|
||||
- Viewing medication history
|
||||
|
||||
### 👑 **Admin Interface** (`admin.spec.ts`)
|
||||
|
||||
- User management operations
|
||||
- Password changes
|
||||
- User status toggles
|
||||
- Admin permissions
|
||||
|
||||
### 🎨 **UI & Navigation** (`ui-navigation.spec.ts`)
|
||||
|
||||
- Theme switching
|
||||
- Modal interactions
|
||||
- Responsive design
|
||||
- Search functionality
|
||||
- Account management
|
||||
|
||||
### ⏰ **Reminder System** (`reminders.spec.ts`)
|
||||
|
||||
- Custom reminder creation
|
||||
- Reminder editing and deletion
|
||||
- Scheduled dose display
|
||||
- Missed dose handling
|
||||
|
||||
## Setup and Installation
|
||||
|
||||
### 1. Install Playwright
|
||||
|
||||
```bash
|
||||
# Install Playwright and browsers
|
||||
npm install -D @playwright/test
|
||||
npx playwright install
|
||||
```
|
||||
|
||||
### 2. Update Package.json
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test:e2e": "playwright test",
|
||||
"test:e2e:ui": "playwright test --ui",
|
||||
"test:e2e:debug": "playwright test --debug",
|
||||
"test:e2e:report": "playwright show-report"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Basic Test Execution
|
||||
|
||||
```bash
|
||||
# Run all E2E tests
|
||||
npm run test:e2e
|
||||
|
||||
# Run tests in UI mode (interactive)
|
||||
npm run test:e2e:ui
|
||||
|
||||
# Run specific test file
|
||||
npx playwright test auth.spec.ts
|
||||
|
||||
# Run tests in debug mode
|
||||
npm run test:e2e:debug
|
||||
```
|
||||
|
||||
### Browser-Specific Testing
|
||||
|
||||
```bash
|
||||
# Run on specific browser
|
||||
npx playwright test --project=chromium
|
||||
npx playwright test --project=firefox
|
||||
npx playwright test --project=webkit
|
||||
|
||||
# Run on mobile browsers
|
||||
npx playwright test --project="Mobile Chrome"
|
||||
npx playwright test --project="Mobile Safari"
|
||||
```
|
||||
|
||||
### Test Reporting
|
||||
|
||||
```bash
|
||||
# Generate and view HTML report
|
||||
npm run test:e2e:report
|
||||
|
||||
# Run with specific reporter
|
||||
npx playwright test --reporter=line
|
||||
npx playwright test --reporter=json
|
||||
```
|
||||
|
||||
## Test Configuration
|
||||
|
||||
The tests are configured via `playwright.config.ts`:
|
||||
|
||||
- **Base URL**: `http://localhost:8080`
|
||||
- **Auto-start**: Docker Compose before tests
|
||||
- **Browsers**: Chrome, Firefox, Safari, Mobile Chrome, Mobile Safari
|
||||
- **Retries**: 2 on CI, 0 locally
|
||||
- **Screenshots**: On failure
|
||||
- **Videos**: On failure
|
||||
- **Traces**: On retry
|
||||
|
||||
## Test Data and Fixtures
|
||||
|
||||
### Custom Fixtures (`fixtures.ts`)
|
||||
|
||||
- `adminPage`: Auto-login as admin user
|
||||
- `userPage`: Auto-login as regular user
|
||||
|
||||
### Helper Functions (`helpers.ts`)
|
||||
|
||||
- `MedicationHelpers`: Medication CRUD operations
|
||||
- `AuthHelpers`: Authentication actions
|
||||
- `ModalHelpers`: Modal interactions
|
||||
- `WaitHelpers`: Wait utilities
|
||||
- `TestData`: Pre-defined test data
|
||||
|
||||
### Example Usage
|
||||
|
||||
```typescript
|
||||
import { test } from './fixtures';
|
||||
import { MedicationHelpers, TestData } from './helpers';
|
||||
|
||||
test('should add medication', async ({ adminPage }) => {
|
||||
const medicationHelper = new MedicationHelpers(adminPage);
|
||||
const testMed = TestData.medications[0];
|
||||
|
||||
await medicationHelper.addMedication(testMed.name, testMed.dosage, testMed.frequency);
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Test Organization
|
||||
|
||||
- Group related tests in describe blocks
|
||||
- Use descriptive test names
|
||||
- Keep tests independent and isolated
|
||||
|
||||
### ✅ Selectors
|
||||
|
||||
- Use data-testid attributes for reliable targeting
|
||||
- Prefer semantic selectors (role, text content)
|
||||
- Avoid CSS selectors that may change
|
||||
|
||||
### ✅ Waiting Strategies
|
||||
|
||||
- Use `waitForSelector()` for dynamic content
|
||||
- Leverage auto-waiting for most actions
|
||||
- Add explicit waits for complex interactions
|
||||
|
||||
### ✅ Test Data
|
||||
|
||||
- Use helper functions for common operations
|
||||
- Keep test data in centralized location
|
||||
- Clean up test data after tests
|
||||
|
||||
## Debugging Tests
|
||||
|
||||
### Local Debugging
|
||||
|
||||
```bash
|
||||
# Debug specific test
|
||||
npx playwright test auth.spec.ts --debug
|
||||
|
||||
# Run with headed browser
|
||||
npx playwright test --headed
|
||||
|
||||
# Slow down execution
|
||||
npx playwright test --slow-mo=1000
|
||||
```
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```bash
|
||||
# Run in CI mode
|
||||
CI=true npx playwright test
|
||||
|
||||
# Generate artifacts for CI
|
||||
npx playwright test --reporter=github
|
||||
```
|
||||
|
||||
## Adding New Tests
|
||||
|
||||
### 1. Create Test File
|
||||
|
||||
```typescript
|
||||
import { test, expect } from './fixtures';
|
||||
|
||||
test.describe('New Feature', () => {
|
||||
test('should do something', async ({ adminPage }) => {
|
||||
// Test implementation
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### 2. Add Helper Functions
|
||||
|
||||
```typescript
|
||||
// In helpers.ts
|
||||
export class NewFeatureHelpers {
|
||||
constructor(private page: any) {}
|
||||
|
||||
async performAction() {
|
||||
// Helper implementation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Update Documentation
|
||||
|
||||
- Add test description to this README
|
||||
- Update test count in project documentation
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Tests timeout:**
|
||||
|
||||
- Increase timeout in config
|
||||
- Add explicit waits
|
||||
- Check application startup time
|
||||
|
||||
**Flaky tests:**
|
||||
|
||||
- Add proper wait conditions
|
||||
- Use retry logic
|
||||
- Check for race conditions
|
||||
|
||||
**Browser compatibility:**
|
||||
|
||||
- Test across all configured browsers
|
||||
- Check for browser-specific issues
|
||||
- Use cross-browser compatible selectors
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Show browser developer tools
|
||||
npx playwright test --debug
|
||||
|
||||
# Record test execution
|
||||
npx playwright codegen localhost:8080
|
||||
|
||||
# Trace viewer
|
||||
npx playwright show-trace trace.zip
|
||||
```
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
Example GitHub Actions workflow:
|
||||
|
||||
```yaml
|
||||
name: E2E Tests
|
||||
on: [push, pull_request]
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- uses: actions/setup-node@v3
|
||||
- run: npm ci
|
||||
- run: npx playwright install --with-deps
|
||||
- run: npm run test:e2e
|
||||
- uses: actions/upload-artifact@v3
|
||||
if: always()
|
||||
with:
|
||||
name: playwright-report
|
||||
path: playwright-report/
|
||||
```
|
||||
|
||||
## Coverage and Metrics
|
||||
|
||||
The E2E tests provide coverage for:
|
||||
|
||||
- ✅ User authentication flows
|
||||
- ✅ Core medication management
|
||||
- ✅ Admin functionality
|
||||
- ✅ UI interactions and navigation
|
||||
- ✅ Responsive design
|
||||
- ✅ Cross-browser compatibility
|
||||
|
||||
For optimal coverage, run tests regularly and add new tests for new features.
|
||||
Reference in New Issue
Block a user