familienarchiv/frontend/e2e/CLAUDE.md

E2E Tests — Familienarchiv

Overview

End-to-end tests for the Familienarchiv frontend using Playwright. These tests verify complete user flows across the full stack (SvelteKit frontend + Spring Boot backend + PostgreSQL + MinIO).

Tech Stack

• Test Runner: Playwright (@playwright/test)
• Browser: Chromium (desktop)
• Locale: de-DE (ensures German language detection)
• Auth: Shared session cookie stored after setup

Project Structure

frontend/e2e/
├── auth.setup.ts              # Authentication setup — logs in and saves session
├── auth.spec.ts               # Authentication flows (login, logout, register)
├── admin.spec.ts              # Admin panel CRUD operations
├── annotations.spec.ts        # Document annotation features
├── bottom-panel.spec.ts       # Bottom panel / transcription panel
├── dashboard-*.spec.ts        # Dashboard variants and screenshots
├── documents.spec.ts          # Document upload, edit, search
├── focus-rings.spec.ts        # Accessibility focus ring tests
├── header.spec.ts             # Navigation header
├── history.spec.ts            # Chronik / activity feed
├── briefwechsel-removed.spec.ts # Guards that the removed /briefwechsel route 404s
├── lang.spec.ts               # Language switching
├── password-reset.spec.ts     # Password reset flow
├── permissions.spec.ts        # Role-based access control
├── persons.spec.ts            # Person directory CRUD
├── profile.spec.ts            # User profile
├── theme.spec.ts              # Dark/light mode
├── transcription.spec.ts      # Transcription workflows
├── accessibility.spec.ts      # Axe accessibility scans
├── fixtures/                  # Test data fixtures
└── helpers/                   # Test helper utilities

Authentication Strategy

Tests share auth state via a stored session cookie:

1. Setup (auth.setup.ts): Logs in with test credentials and saves storageState to e2e/.auth/user.json
2. Tests: All test projects depend on setup and reuse the stored session

This avoids re-logging in for every test, but means tests must run sequentially (fullyParallel: false, workers: 1).

Configuration

Config lives in frontend/playwright.config.ts:

Setting	Value	Notes
testDir	./e2e	Test file location
fullyParallel	false	Shared auth state
workers	1	Sequential execution
screenshot	'on'	Always capture
video	'retain-on-failure'	Keep on failure
trace	'retain-on-failure'	Keep on failure
baseURL	http://localhost:3000	Overridable via E2E_BASE_URL

The webServer config auto-starts npm run dev -- --port 3000 if no server is detected at the base URL.

How to Run

Prerequisites

The full stack must be running (or the webServer config will start the frontend dev server):

# Start infrastructure
docker-compose up -d

# Ensure backend is healthy
curl http://localhost:8080/actuator/health

Run E2E Tests

cd frontend

# Headless (CI mode)
npm run test:e2e

# With visible browser
npm run test:e2e:headed

# Interactive UI mode
npm run test:e2e:ui

# Run a specific test file
npx playwright test documents.spec.ts

# Run with a different base URL (e.g., docker frontend on 5173)
E2E_BASE_URL=http://localhost:5173 npx playwright test

Writing New E2E Tests

1. Create a new .spec.ts file in frontend/e2e/
2. Use the shared auth state (no manual login needed)
3. Use page object patterns or helper functions from helpers/
4. Add test-data-id attributes to components for stable selectors
5. Run with --debug or --ui to troubleshoot

Example Test Pattern

import { test, expect } from '@playwright/test';

test('user can create a document', async ({ page }) => {
	await page.goto('/documents/new');
	await page.getByTestId('document-title').fill('Test Document');
	await page.getByTestId('save-button').click();
	await expect(page).toHaveURL(/\/documents\/[^/]+$/);
});

Accessibility Testing

accessibility.spec.ts runs Axe scans on key pages. Violations fail the test.

npx playwright test accessibility.spec.ts

Troubleshooting

Issue	Solution
Auth failures	Delete e2e/.auth/user.json and re-run
Backend not reachable	Ensure docker-compose up -d is running
Flaky tests	Increase timeout or add explicit waits
Screenshots missing	Check test-results/e2e/

CI Integration

E2E tests are not currently run in CI (the pipeline stops at unit/component tests). To add them, extend infra/gitea/workflows/ci.yml with a Playwright job that starts the full Docker Compose stack first.