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

cd roa2web/reports-app/frontend/
npm install

Running Tests

# 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:

// 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:

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:

npm run test:e2e:debug

📝 Writing New Tests

Test File Structure

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:

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

📚 Resources

• Playwright Documentation
• Page Object Model Pattern
• API Mocking with Playwright
• Visual Testing

---

Tests implemented following the detailed plan in PLAYWRIGHT_TESTING_PLAN.md 🎭