roa2web-service-auto/reports-app/frontend/tests/README.md

# ROA2WEB Frontend E2E Testing with Playwright

This directory contains end-to-end tests for the ROA2WEB frontend application using Playwright.

## 🚀 Quick Start

### Prerequisites
- Node.js 16+ and npm 8+
- Frontend development server running on `http://localhost:3001`

### Installation
```bash
cd roa2web/reports-app/frontend/
npm install
```

### Running Tests
```bash
# Run all tests headlessly
npm run test:e2e

# Run tests with browser UI visible
npm run test:e2e:headed

# Run tests in debug mode
npm run test:e2e:debug

# Run tests with Playwright UI mode
npm run test:e2e:ui

# Show test report
npm run test:e2e:report
```

## 📁 Test Structure

```
tests/
├── e2e/                    # End-to-end test files
│   ├── auth/              # Authentication flow tests
│   │   └── login.spec.js
│   ├── dashboard/         # Dashboard view tests
│   │   └── dashboard.spec.js
│   ├── invoices/          # Invoice management tests
│   ├── payments/          # Payment tracking tests
│   └── responsive/        # Responsive design tests
│       └── breakpoints.spec.js
├── fixtures/              # Test data and mock responses
│   └── auth.js
├── page-objects/          # Page Object Models
│   ├── BasePage.js
│   ├── LoginPage.js
│   └── DashboardPage.js
├── utils/                 # Test utilities
└── README.md             # This file
```

## 🎭 Test Categories

### 1. Authentication Tests (`auth/login.spec.js`)
- ✅ Login page display and validation
- ✅ Form validation for empty fields
- ✅ Successful login flow with API mocking
- ✅ Invalid credentials handling
- ✅ Loading states and error handling
- ✅ Focus management and UX

### 2. Dashboard Tests (`dashboard/dashboard.spec.js`)
- ✅ Dashboard page rendering
- ✅ Company selection workflow
- ✅ Statistics display and data fetching
- ✅ Navigation to invoices/payments views
- ✅ API error handling
- ✅ Company switching functionality

### 3. Invoice Management Tests (`invoices/invoices.spec.js`)
- ✅ Invoice list display and table functionality
- ✅ Search and filtering by invoice number/status
- ✅ Sorting by different columns
- ✅ Invoice details view
- ✅ Data export functionality
- ✅ Pagination handling
- ✅ API error scenarios

### 4. Payment Tracking Tests (`payments/payments.spec.js`)
- ✅ Payment list display and management
- ✅ Filtering by payment method and date range
- ✅ Payment totals and summary views
- ✅ Export functionality
- ✅ Payment details modal/panel
- ✅ Method-based grouping and statistics

### 5. Responsive Design Tests (`responsive/breakpoints.spec.js`)
- ✅ Mobile layout (320px) - form stacking, touch targets
- ✅ Tablet layout (768px) - grid adjustments
- ✅ Desktop layout (1024px+) - full feature layout
- ✅ Wide screen (1920px) - content max-width
- ✅ Orientation changes (portrait ↔ landscape)
- ✅ Touch interaction testing

## 🏗️ Page Object Pattern

Tests use the Page Object Model pattern for maintainability:

### BasePage
Base class with common functionality:
- API response waiting
- Loading state management
- Error/success message checking
- Navigation helpers

### LoginPage
Encapsulates login page interactions:
- Form filling and validation
- Error message extraction
- Loading state checking
- Navigation to login page

### DashboardPage
Handles dashboard-specific operations:
- Company selection
- Statistics reading
- Action button clicks
- Content visibility checks

### InvoicesPage
Manages invoice-related interactions:
- Invoice table navigation and filtering
- Search functionality
- Sorting and pagination
- Export operations

### PaymentsPage
Handles payment view operations:
- Payment filtering and search
- Method and date range filters
- Summary view switching
- Export and totals display

## 🎯 API Mocking Strategy

Tests use Playwright's route interception to mock API calls:

```javascript
// Mock successful login
await page.route('**/api/auth/login', async route => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify({ /* mock response */ })
  });
});
```

### Mocked Endpoints
- `POST /api/auth/login` - Authentication
- `GET /api/companies` - Company list
- `GET /api/invoices/{company}/summary` - Invoice statistics
- `GET /api/payments/{company}/summary` - Payment statistics
- `GET /api/invoices/{company}` - Invoice list with pagination
- `GET /api/payments/{company}` - Payment list with filtering

## 📱 Responsive Testing

Tests verify application behavior across different viewport sizes:

| Breakpoint | Width | Focus Areas |
|------------|-------|-------------|
| Mobile | 320px | Touch targets, vertical stacking |
| Tablet | 768px | Grid layouts, navigation |
| Desktop | 1024px+ | Full feature set, horizontal layouts |
| Wide | 1920px | Content max-width, spacing |

## 🔧 Configuration

### Playwright Config (`playwright.config.js`)
- **Base URL**: `http://localhost:3001`
- **Browsers**: Chromium, Firefox, WebKit, Mobile Chrome, Mobile Safari
- **Screenshots**: On failure only
- **Videos**: Retained on failure
- **Traces**: On first retry

### Test Environment
Tests run against the local development server with mocked backend API calls to ensure consistent, fast, and reliable testing.

## 📊 Test Reports

After running tests, view the HTML report:
```bash
npm run test:e2e:report
```

The report includes:
- Test results with pass/fail status
- Screenshots of failures
- Video recordings of failed tests
- Execution timing and performance metrics

## 🚨 Troubleshooting

### Common Issues

1. **Tests timing out**
   - Ensure frontend server is running on port 3001
   - Check network connectivity
   - Increase timeout in test configuration

2. **Element not found errors**
   - Verify page object selectors match current DOM
   - Check for dynamic content loading
   - Add appropriate wait conditions

3. **API mock not working**
   - Verify route patterns match actual API calls
   - Check mock response format
   - Ensure mocks are set up before navigation

### Debug Mode
Run tests in debug mode to step through execution:
```bash
npm run test:e2e:debug
```

## 📝 Writing New Tests

### Test File Structure
```javascript
import { test, expect } from '@playwright/test';
import { YourPageObject } from '../../page-objects/YourPageObject.js';

test.describe('Feature Name', () => {
  let pageObject;

  test.beforeEach(async ({ page }) => {
    pageObject = new YourPageObject(page);
    // Setup mocks, navigation, etc.
  });

  test('should do something', async ({ page }) => {
    // Test implementation
  });
});
```

### Best Practices
1. **Use Page Objects** - Encapsulate page interactions
2. **Mock API calls** - Avoid dependencies on backend state
3. **Wait for elements** - Use proper wait strategies
4. **Descriptive test names** - Clear test intent
5. **Setup and teardown** - Clean test environment
6. **Group related tests** - Use describe blocks effectively

## 🔄 CI/CD Integration

Tests are designed to run in continuous integration environments:

```yaml
# Example GitHub Actions workflow
- name: Run E2E Tests
  run: |
    npm ci
    npm run build
    npm run test:e2e
```

## 📚 Resources

- [Playwright Documentation](https://playwright.dev/)
- [Page Object Model Pattern](https://playwright.dev/docs/test-pom)
- [API Mocking with Playwright](https://playwright.dev/docs/mock)
- [Visual Testing](https://playwright.dev/docs/test-screenshots)

---

*Tests implemented following the detailed plan in `PLAYWRIGHT_TESTING_PLAN.md`* 🎭