Cleanuparr/docs/contributing/e2e-testing.md

End-to-End Testing with Keycloak and Playwright

E2E tests use a real Keycloak instance and Playwright browser automation to validate full OIDC round-trips that mocked tests cannot catch.

Test Coverage Layers

Layer	What it catches
Unit tests (OidcAuthServiceTests)	PKCE, URL encoding, token validation logic, expiry handling
Integration tests (OidcAuthControllerTests, AccountControllerOidcTests)	HTTP routing, middleware, cookie/token handling (mocked IdP)
E2E tests	Real browser redirects, actual Keycloak protocol, full OIDC round-trip

Prerequisites

• Docker + Docker Compose
• Node.js 18+
• GitHub Packages credentials (for building the app image)

Running Locally

cd e2e

# Start Keycloak + Cleanuparr
docker compose -f docker-compose.e2e.yml up -d --build

# Install dependencies and browser
npm install
npx playwright install chromium

# Run tests (global setup waits for services and provisions the app automatically)
npx playwright test

# Tear down
docker compose -f docker-compose.e2e.yml down

How It Works

1. Docker Compose starts Keycloak (with a pre-configured realm) and the Cleanuparr app
2. Playwright globalSetup (tests/global-setup.ts) automatically waits for both services and creates the admin account. OIDC is left disabled by default — each OIDC spec configures the state it needs in its own beforeAll and restores it in afterAll
3. oidc-link.spec.ts logs in with local credentials, navigates to settings, and verifies the UI link flow against Keycloak
4. oidc-login.spec.ts verifies the full OIDC login flow — clicking "Sign in with Keycloak" on the login page, authenticating at Keycloak, and landing on the dashboard. It establishes its own linked subject via the shared linkOidcViaBrowser helper in beforeAll

OIDC specs are independent of each other; the previous numeric-prefix ordering was removed once each spec became self-contained.

CI

E2E tests run automatically on PRs that touch code/** or e2e/** via .github/workflows/e2e.yml.