rxminder/tests/e2e/README.md

# 🎭 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
bun add -D @playwright/test
bunx 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
bun run test:e2e

# Run tests in UI mode (interactive)
bun run test:e2e:ui

# Run specific test file
bunx playwright test auth.spec.ts

# Run tests in debug mode
bun run test:e2e:debug
```

### Browser-Specific Testing

```bash
# Run on specific browser
bunx playwright test --project=chromium
bunx playwright test --project=firefox
bunx playwright test --project=webkit

# Run on mobile browsers
bunx playwright test --project="Mobile Chrome"
bunx playwright test --project="Mobile Safari"
```

### Test Reporting

```bash
# Generate and view HTML report
bun run test:e2e:report

# Run with specific reporter
bunx playwright test --reporter=line
bunx 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
bunx playwright test auth.spec.ts --debug

# Run with headed browser
bunx playwright test --headed

# Slow down execution
bunx playwright test --slow-mo=1000
```

### CI/CD Integration

```bash
# Run in CI mode
CI=true bunx playwright test

# Generate artifacts for CI
bunx 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
bunx playwright test --debug

# Record test execution
bunx playwright codegen localhost:8080

# Trace viewer
bunx 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: bun install
      - run: bunx playwright install --with-deps
      - run: bun 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.