E2E Testing Guide

Complete guide for running end-to-end tests for XTranslator application.

Overview

XTranslator uses two complementary E2E testing approaches:

1. Backend API Tests - Using Vitest + Supertest
2. Frontend Integration Tests - Using Playwright

---

Backend E2E Tests (Vitest)

Location

xtranslator_backend/apps/orchestrator/test/
├── app.e2e-spec.ts                    # Basic app tests
├── translation.e2e-spec.ts            # Translation API tests
└── speech-email.e2e-spec.ts           # Speech & Email API tests (NEW)

Running Backend E2E Tests

cd xtranslator_backend

# Run all E2E tests
npm run test:e2e

# Run in watch mode
npm run test:e2e:watch

# Run with Doppler environment variables
npm run doppler:test

Backend Test Coverage

Translation API (translation.e2e-spec.ts)

• ✅ Anonymous user translation
• ✅ Authenticated user translation
• ✅ Field validation
• ✅ Domain validation
• ✅ Character limit enforcement
• ✅ SSE streaming verification

Speech & Email API (speech-email.e2e-spec.ts)

• ✅ Text-to-Speech (TTS)

  • Convert text to audio
  • Voice parameter validation
  • Speed parameter validation
  • Default parameter handling
  • Audio format verification

• ✅ Speech-to-Text (STT)

  • Audio file transcription
  • Language parameter support
  • Prompt parameter support
  • Missing file validation

• ✅ Email Sending

  • Email send success
  • Required field validation
  • Email format validation
  • Optional data parameter

• ✅ Authentication & Rate Limiting

  • Anonymous user access
  • Rate limiting behavior

---

Frontend E2E Tests (Playwright)

Location

xtranslator3/e2e/
├── text-translator.spec.ts                    # Text translation UI tests
├── document-translation-cancellation.spec.ts  # Document translation tests
├── simple-cancellation-test.spec.ts           # Cancellation flow tests
└── speech-email.spec.ts                       # Speech & Email UI tests (NEW)

Running Frontend E2E Tests

cd xtranslator3

# Run all Playwright tests
npx playwright test

# Run with UI mode (interactive)
npx playwright test --ui

# Run specific test file
npx playwright test e2e/speech-email.spec.ts

# Run in headed mode (see browser)
npx playwright test --headed

# Debug mode
npx playwright test --debug

# Generate test report
npx playwright show-report

Frontend Test Coverage

Text Translation (text-translator.spec.ts)

• ✅ UI element visibility
• ✅ Language selectors
• ✅ Text areas
• ✅ Translate button
• ✅ Page title verification

Document Translation (document-translation-cancellation.spec.ts)

• ✅ File upload flow
• ✅ Translation cancellation
• ✅ Error handling

Speech & Email Integration (speech-email.spec.ts)

• ✅ Text-to-Speech

  • UI elements availability
  • API endpoint calls
  • Error handling
  • Loading states

• ✅ Speech-to-Text

  • Audio upload UI
  • Transcription flow
  • Invalid file handling

• ✅ Email Sending

  • Contact form submission
  • Email validation
  • API error handling

• ✅ Authentication Integration

  • Anonymous user access
  • Authenticated user features

• ✅ Network Handling

  • Slow API responses
  • Network errors
  • Loading indicators

---

Running Complete E2E Test Suite

Prerequisites

Backend:

# Ensure you have all dependencies
cd xtranslator_backend
npm install

# Set up environment variables
# Use Doppler or create .env file with:
# - OPENAI_API_KEY
# - FIREBASE_PROJECT_ID
# - etc.

Frontend:

# Install dependencies
cd xtranslator3
npm install

# Install Playwright browsers
npx playwright install

Full Test Run

Option 1: Run Backend and Frontend Separately

Terminal 1 (Backend):

cd xtranslator_backend
npm run test:e2e

Terminal 2 (Frontend):

cd xtranslator3
npx playwright test

Option 2: Run Backend with Frontend Integration

Terminal 1 (Start Backend):

cd xtranslator_backend
npm run doppler:orchestrator
# Or: npm run start:dev

Terminal 2 (Start Frontend):

cd xtranslator3
npm start

Terminal 3 (Run Playwright Tests):

cd xtranslator3
npx playwright test

---

Test Configuration

Backend (Vitest)

Configuration: xtranslator_backend/vitest.config.e2e.ts

{
  testDir: './apps/orchestrator/test',
  testMatch: ['**/*.e2e-spec.ts'],
  setupFiles: ['./apps/orchestrator/test/setup.ts']
}

Frontend (Playwright)

Configuration: xtranslator3/playwright.config.ts

{
  testDir: './e2e',
  baseURL: 'http://localhost:4200',
  webServer: {
    command: 'npm start',
    url: 'http://localhost:4200',
    reuseExistingServer: !process.env.CI
  }
}

---

CI/CD Integration

GitHub Actions

Both test suites can be integrated into CI/CD pipelines:

# Example .github/workflows/e2e-tests.yml
name: E2E Tests

on: [push, pull_request]

jobs:
  backend-e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - name: Install dependencies
        working-directory: ./xtranslator_backend
        run: npm ci
      - name: Run E2E tests
        working-directory: ./xtranslator_backend
        run: npm run test:e2e
        
  frontend-e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - name: Install dependencies
        working-directory: ./xtranslator3
        run: npm ci
      - name: Install Playwright
        working-directory: ./xtranslator3
        run: npx playwright install --with-deps
      - name: Run Playwright tests
        working-directory: ./xtranslator3
        run: npx playwright test
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report
          path: xtranslator3/playwright-report/

---

Adding New E2E Tests

Backend Tests

1. Create test file in apps/orchestrator/test/
2. Follow existing patterns:

   import { describe, it, expect, beforeAll, afterAll } from "vitest";
   import { Test, TestingModule } from "@nestjs/testing";
   import { OrchestratorModule } from "../src/orchestrator.module";
   
   describe("New Feature E2E", () => {
     let app: INestApplication;
     // ... setup
   });

Frontend Tests

1. Create test file in e2e/
2. Follow Playwright patterns:

   import { test, expect } from '@playwright/test';
   
   test.describe('New Feature', () => {
     test('should do something', async ({ page }) => {
       await page.goto('/');
       // ... test logic
     });
   });

---

Troubleshooting

Common Issues

Backend E2E Tests Failing:

• ✅ Check environment variables are set
• ✅ Ensure Firebase/Redis/OpenAI credentials are valid
• ✅ Verify all services are accessible

Frontend E2E Tests Failing:

• ✅ Ensure backend is running (if not mocked)
• ✅ Check Playwright browsers are installed
• ✅ Verify baseURL matches your dev server
• ✅ Clear browser cache/storage

Timeouts:

• Increase timeout in playwright.config.ts
• Check network connectivity
• Verify API is responding

---

Best Practices

1. Mock External Services - Mock OpenAI, email providers in tests
2. Use Test Data - Don't use production credentials
3. Clean Up - Reset state between tests
4. Descriptive Names - Use clear test descriptions
5. Assertions - Test both success and failure scenarios
6. CI-Friendly - Ensure tests run headless in CI
7. Parallel Execution - Configure for speed without flakiness

---

Current Test Statistics

Backend E2E Coverage

• Total Test Files: 3
• Total Tests: ~20+
• Coverage Areas: Translation, Speech, Email, Jobs

Frontend E2E Coverage

• Total Test Files: 4
• Total Tests: ~15+
• Coverage Areas: UI, Translation, Speech, Email, Auth

---

Next Steps

• Add integration tests for Job endpoints
• Add tests for Payment webhooks
• Increase test coverage for error scenarios
• Add performance/load testing
• Add visual regression testing (Playwright screenshots)
• Add accessibility testing (Playwright a11y)