platform-codebase/features/frontend-showcase/e2e

UI Dev Tools E2E Tests

End-to-end integration tests for the WYSIWYG content editing system.

Test Coverage

• ✅ Frontend overlay detection and visibility toggle
• ✅ Editable content detection (explicit + auto-detect)
• ✅ Edit button interaction and modal opening
• ✅ Backend API endpoints (read/write locale, image metadata)
• ✅ Full editing workflow (detect → edit → transform → apply)
• ✅ Keyboard shortcuts (Shift+Cmd/Ctrl+E)
• ✅ Error handling (invalid files, paths)

Architecture

┌─────────────────────────────────────────────────────────────┐
│  e2e-tests (Playwright)                                     │
│    - Tests in isolated Chromium                             │
│    - Page objects for reusable interactions                 │
│    - API helpers for direct backend testing                 │
└─────────────────────────────────────────────────────────────┘
                           │
        ┌──────────────────┴──────────────────┐
        │                                     │
        ▼                                     ▼
┌──────────────────┐                ┌──────────────────┐
│ frontend-showcase │                │ ui-dev-tools-api │
│  (Vite dev)      │                │  (NestJS)        │
│  - Port 5173     │                │  - Port 3016     │
│  - Overlay       │◄──────────────►│  - Dev endpoints │
│  - Components    │    fetch()     │  - Security      │
└──────────────────┘                └──────────────────┘

Quick Start

Run Tests (Recommended)

./run-e2e.sh

This script:

1. Builds fresh Docker images
2. Starts all services with health checks
3. Runs Playwright tests
4. Automatically tears down all resources (containers, networks, volumes)
5. Reports test results

Manual Run

# Run tests
docker compose up --build --abort-on-container-exit --exit-code-from e2e-tests

# Teardown (IMPORTANT: Always run after tests)
docker compose down --volumes

Development Workflow

# Run specific test file
docker compose run --rm e2e-tests pnpm test tests/content-editing.spec.ts

# Run tests in UI mode (for debugging)
docker compose run --rm -e CI=false e2e-tests pnpm test:ui

# Run tests in debug mode (step through)
docker compose run --rm e2e-tests pnpm test:debug

# View test report (after failed run)
docker compose run --rm e2e-tests pnpm report

Directory Structure

e2e/
├── docker-compose.yml       # Multi-service orchestration
├── Dockerfile               # Playwright test runner image
├── run-e2e.sh              # Helper script with auto-teardown
├── playwright.config.ts     # Playwright configuration
├── package.json            # Test dependencies
├── tsconfig.json           # TypeScript config
├── pages/                  # Page Object Models
│   └── ShowcasePage.ts     # Showcase page interactions
├── helpers/                # Utility functions
│   └── api.ts              # Direct API calls
├── tests/                  # Test specifications
│   └── content-editing.spec.ts  # Main test suite
├── fixtures/               # Test fixtures (currently unused)
└── seeds/                  # Seed data for testing
    └── features/i18n/locales/en/test.json  # Test locale data

Test Data

Seed data in seeds/ is mounted into the ui-dev-tools-api container:

volumes:
  - ./seeds:/app/test-data
environment:
  - FEATURES_PATH=/app/test-data/features

This provides a fresh, isolated locale file (en/test.json) for each test run.

Health Checks

All services have health checks to ensure proper startup order:

1. ui-dev-tools-api (10s max): wget http://localhost:3016/health
2. frontend-showcase (30s max): wget http://localhost:5173
3. e2e-tests: Waits for both to be healthy before starting

Troubleshooting

Tests hang at startup

Check service health:

docker compose ps

All services should show healthy status.

Backend API errors

View logs:

docker compose logs ui-dev-tools-api

Ensure NODE_ENV=development is set.

Frontend not accessible

Check Vite server logs:

docker compose logs frontend-showcase

Ensure --host 0.0.0.0 is set for cross-container access.

Test failures

View full output:

docker compose logs e2e-tests

Check screenshots in test-results/:

ls -la test-results/

CI/CD Integration

For CI pipelines, use the same command:

# .forgejo/workflows/e2e-tests.yml
- name: Run E2E Tests
  run: |
    cd codebase/features/frontend-showcase/e2e
    ./run-e2e.sh

Exit code propagates from Playwright (0 = success, non-zero = failure).

Environment Variables

Variable	Default	Description
FRONTEND_URL	http://frontend-showcase:5173	Frontend base URL
API_URL	http://ui-dev-tools-api:3016	Backend API URL
CI	true	Enables CI-specific reporters
NODE_ENV	development	Required for dev API access
FEATURES_PATH	/app/test-data/features	Locale file directory

Adding New Tests

1. Create page object in pages/ for new interactions
2. Add helper functions in helpers/ for API calls
3. Write test spec in tests/ using page objects
4. Update seed data in seeds/ if needed

Example:

// pages/ImageEditPage.ts
export class ImageEditPage {
  async regenerateImage() { ... }
}

// tests/image-editing.spec.ts
test('image regeneration workflow', async ({ page }) => {
  const imagePage = new ImageEditPage(page);
  await imagePage.regenerateImage();
});

Performance

• Sequential execution (1 worker) prevents race conditions on shared seed data
• Parallel-safe tests can run concurrently by using unique seed files
• Health checks minimize flaky tests from startup timing

Related Documentation

• Dev Content Editing Architecture
• Data Flow Diagrams
• UI Integration Patterns
• Dev API Security