feat(e2e): add Playwright coverage, onboarding seed bridge, and CI (#68)

Adds Playwright e2e infrastructure over HTTPS with Phase 1 happy-path
coverage for onboarding, payments, activity, and settings. Most specs
skip onboarding via a dev/test-build-only window.__e2eSeedOnboarding
bridge that calls the same production Task actions the UI does, since
Playwright's storageState can't snapshot Evolu's OPFS-backed SQLite.
Adds test:e2e:preview to run the suite against a one-off production
build, and a labeled-PR GitHub Actions workflow to run it in CI.


Claude-Session: https://claude.ai/code/session_01WgU1jAJx3RvxuwWUpbQwmp

Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>

Author: pepakriz

.github/workflows/e2e.yml

@@ -0,0 +1,52 @@
+name: E2E
+
+on:
+  pull_request:
+    types: [labeled, synchronize]
+  workflow_dispatch:
+
+concurrency:
+  group: e2e-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    name: Playwright E2E (production build)
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      contains(github.event.pull_request.labels.*.name, 'run-e2e')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install Playwright browser
+        run: bunx playwright install --with-deps chromium
+
+      # test:e2e:preview builds once (PAYKY_E2E_BUILD=1 vite build) and runs
+      # the full Playwright suite against that build via `vite preview`,
+      # instead of the dev server test:e2e uses.
+      - name: Run e2e tests against a production build
+        run: bun run test:e2e:preview
+
+      - name: Upload Playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

.gitignore

@@ -33,6 +33,11 @@ coverage
 .data
 .claude
 
+# Playwright
+playwright-report
+test-results
+blob-report
+
 # Local environment (may contain secrets)
 .env
 .env.*

.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "bunx",
+      "args": ["@playwright/mcp@latest"]
+    },
+    "chrome-devtools": {
+      "command": "bunx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    }
+  }
+}

AGENTS.md

@@ -37,6 +37,7 @@
 - `src/assets` contains static frontend assets.
 - `src/index.css` contains global Tailwind and theme styles.
 - `src/zod-utils.ts` contains app-level Zod helpers that are not specific to one domain module.
+- `e2e` contains Playwright end-to-end tests (`playwright.config.ts` at the repo root). See "E2E Testing" below for conventions.
 
 ## Domain Module Structure
 
@@ -127,3 +128,17 @@
 - For aggregate extension/detail tables sharing the root id, soft delete only the root row unless the detail has its own lifecycle.
 - For CRDT actions, write tombstones and updates directly without preloading rows, unless current data is required for a domain invariant.
 - Pass Evolu mutation payloads through `removeUndefinedValues` to avoid extra or undefined fields.
+
+## E2E Testing
+
+- Run tests with `bun run test:e2e` (headless, dev server) or `test:e2e:ui` (interactive). `bun run test:e2e:preview` runs the same suite against a one-off production build instead: `PAYKY_E2E_BUILD=1 vite build` once, then Playwright's `webServer` runs `vite preview` (set via `PAYKY_E2E_SERVER=preview`, read in `playwright.config.ts`) rather than `bun run dev`. Tests live in `e2e/*.spec.ts`; `playwright.config.ts` at the repo root configures a single `chromium` project.
+- The Playwright `webServer` boots the real Vite dev server (or, for `test:e2e:preview`, `vite preview` serving a real build) with basic-SSL left enabled (never set `PAYKY_DISABLE_BASIC_SSL` for e2e) so tests run over HTTPS with a self-signed cert (`ignoreHTTPSErrors` in the config), the same way production TLS behaves — `@vitejs/plugin-basic-ssl` applies to both `server.https` and `preview.https`. Some browser features (for example `navigator.clipboard`) are unavailable under plain HTTP, so testing over HTTP would hide regressions in those code paths.
+- Evolu/SQLite persists through OPFS (Origin Private File System) in Chromium, not IndexedDB — Playwright's `storageState({ indexedDB: true })` snapshot/restore does **not** capture it, so pre-seeding an onboarded account via storageState does not work here. Don't reintroduce that approach.
+- `src/components/e2e-test-bridge.tsx` (mounted in `App.tsx`) exposes `window.__e2eSeedOnboarding`, which calls the same production Task actions the onboarding UI does (`saveCashRegisterAccount`, `saveSparkAccount`, `saveFiatBankAccount`, `completeOnboarding`) directly, skipping the onboarding UI. It's gated on `import.meta.env.DEV || __E2E_TEST_BUILD__`, **not** `import.meta.env.DEV` alone — that define is `false` in every `vite build` output regardless of how it's later served, so DEV alone would make the bridge dead code in the `test:e2e:preview` build too. `__E2E_TEST_BUILD__` is a `vite.config.ts` `define` wired to `PAYKY_E2E_BUILD=1`, set only by `test:e2e:preview`'s build step — a real production build never sets it, so the bridge stays dead code (removed) there. `e2e/fixtures.ts`'s `seedOnboarding`/`seedCurrentAccountOnboarding` call the bridge via `page.evaluate` and wait for the app's own reactive redirect off `/onboarding`. Use this in specs that don't test onboarding itself; `completeOnboarding()` (real UI clicks) remains for specs that do (`e2e/onboarding.spec.ts`, `e2e/smoke.spec.ts`) and for a second device account created mid-test (see below).
+- Switching the active device account recreates the app's Evolu client, and `E2eTestBridge`'s effect doesn't reliably reattach `window.__e2eSeedOnboarding` to the new client in time — use `completeOnboardingDefaults()` (real UI clicks) for a second account instead of the seed bridge, as `e2e/settings-accounts.spec.ts` does.
+- `e2e/fixtures.ts` holds reusable flow helpers (`completeOnboarding`, `completeOnboardingDefaults`, `seedOnboarding`, `seedCurrentAccountOnboarding`, `enterAmount`, `createPayment`, `markCashPaid`, `translate`, `translateValue`, `gotoPage`, `reloadPage`, `pageWidth`/`pageHeight`) plus a `test`/`expect` re-export extended with a `seededPage` fixture. It is imported both by `*.spec.ts` files and by `bin/generate-doc-screenshots.ts`, which drives a manually launched `chromium.launch()` browser outside the Playwright test runner. Because of that second consumer, functions in `e2e/fixtures.ts` must never call `test.step(...)` (or other APIs that require an active test) — they throw `test.step() can only be called from a test` outside a real test run. Extend `e2e/fixtures.ts` instead of duplicating flow steps in a spec file or in the screenshot script, but keep it runner-agnostic.
+- Import `test`/`expect` from `./fixtures.ts`, not `@playwright/test`, in every spec except `e2e/onboarding.spec.ts` and `e2e/smoke.spec.ts` (which test onboarding itself and must not auto-seed). Destructure the `seededPage` fixture instead of `page` — it seeds onboarding before the test body runs, so specs don't repeat a manual "seed onboarding" step. `settings-accounts.spec.ts` still seeds the *first* account this way but falls back to `completeOnboardingDefaults()` for the second (see the account-switch caveat above).
+- Use `gotoPage(page, path, language, headingKey)`/`reloadPage(page, language, headingKey)` instead of hand-rolling `page.goto(path, { waitUntil: "domcontentloaded" }) + getByRole("heading", ...).waitFor()` — nearly every spec starts with this pattern and every reload-persistence check repeats it. Use `translateValue(language, key, value)` instead of hardcoding a rendered `{value}`-templated string (for example `"10%"` or `"Remove 20%"`) — it substitutes into the real translation key so the test tracks copy changes instead of silently drifting from it.
+- Prefer `getByRole` with the translated accessible name (via `translate(language, key)`) as the default locator — it doubles as an accessibility check and tracks markup changes for free. Reserve `data-testid` for elements without a stable accessible name/role, or for elements that stay mounted in the DOM regardless of visibility (for example the payment-paid success overlay, which is toggled via `aria-hidden`/opacity rather than conditionally rendered — matched via `data-testid="payment-paid-panel"`, not a generic `[aria-hidden="false"]` attribute selector). Most local UI primitives (`Button`, `TabsTrigger`, `ToggleGroupItem`, ...) spread `...props` through to the native element, so `data-testid` can be passed directly as a prop without changing the component.
+- Wrap each logical phase of a test — not each individual click — in `test.step(...)` inside the `*.spec.ts` file, typically one step per fixture-helper call (`completeOnboarding`, `createPayment`, `markCashPaid`, final assertion). This keeps the HTML report/trace readable without requiring step support inside the shared fixtures.
+- There is no network mocking yet for Spark/FIO/Yadio/LNURL (planned for a later phase in `e2e.md`) — payment flows that hit those integrations are not yet deterministic in e2e.

bin/generate-doc-screenshots.ts

@@ -5,10 +5,15 @@ import { fileURLToPath } from "node:url"
 import { chromium, expect, type Page } from "@playwright/test"
 import sharp from "sharp"
 import {
-  type Language,
-  resources,
-  type TranslationKey,
-} from "../src/i18n/resources.ts"
+  completeOnboarding,
+  createPayment,
+  enterAmount,
+  markCashPaid,
+  pageHeight,
+  pageWidth,
+  translate,
+} from "../e2e/fixtures.ts"
+import { type Language, resources } from "../src/i18n/resources.ts"
 
 interface ScreenshotScenario {
   readonly name: "home" | "payment" | "paid" | "settings"
@@ -17,20 +22,12 @@ interface ScreenshotScenario {
 
 const documentationLanguages = Object.keys(resources) as Language[]
 
-const languageOptionKeyByLanguage: Record<Language, TranslationKey> = {
-  en: "settings.language.english.title",
-  cs: "settings.language.czech.title",
-  sk: "settings.language.slovak.title",
-}
-
 const localeByLanguage: Record<Language, string> = {
   en: "en-US",
   cs: "cs-CZ",
   sk: "sk-SK",
 }
 
-const pageWidth = 406
-const pageHeight = 818
 const deviceScaleFactor = 3.5
 const capturedWidth = pageWidth * deviceScaleFactor
 const capturedHeight = pageHeight * deviceScaleFactor
@@ -86,81 +83,6 @@ async function waitForApp(): Promise<void> {
   throw new Error("Timed out waiting for the documentation screenshot server.")
 }
 
-function translate(language: Language, key: TranslationKey): string {
-  return resources[language][key]
-}
-
-async function completeOnboarding(
-  page: Page,
-  language: Language
-): Promise<void> {
-  await page.goto(appUrl, { waitUntil: "domcontentloaded" })
-  await page
-    .getByRole("heading", { name: translate(language, "onboarding.title") })
-    .waitFor()
-  await page
-    .getByRole("button", {
-      name: translate(language, languageOptionKeyByLanguage[language]),
-    })
-    .click()
-  await page
-    .getByRole("button", { name: translate(language, "onboarding.next") })
-    .click()
-  await page
-    .getByRole("button", {
-      name: translate(language, "onboarding.accountChoice.new.title"),
-    })
-    .click()
-  await page
-    .getByRole("button", { name: translate(language, "onboarding.next") })
-    .click()
-  await page
-    .getByRole("button", { name: translate(language, "onboarding.next") })
-    .click()
-  await page
-    .getByRole("checkbox", {
-      name: translate(language, "onboarding.payments.btc.title"),
-    })
-    .click()
-  await page
-    .getByRole("checkbox", {
-      name: translate(language, "onboarding.payments.iban.title"),
-    })
-    .click()
-  await page.getByRole("textbox").fill("CZ6508000000192000145399")
-  await page
-    .getByRole("button", { name: translate(language, "onboarding.next") })
-    .click()
-  await page
-    .getByRole("button", { name: translate(language, "onboarding.finish") })
-    .click()
-  await page
-    .getByRole("button", { name: translate(language, "settings.title") })
-    .waitFor()
-}
-
-async function enterAmount(page: Page, language: Language): Promise<void> {
-  await page.getByRole("button", { name: "5", exact: true }).click()
-  await page
-    .getByRole("button", {
-      name: translate(language, "home.keypad.decimal"),
-    })
-    .click()
-  await page.getByRole("button", { name: "9", exact: true }).click()
-}
-
-async function createPayment(page: Page, language: Language): Promise<void> {
-  await enterAmount(page, language)
-  await page
-    .getByRole("button", { name: translate(language, "home.pay") })
-    .click()
-  await page
-    .getByRole("tab", {
-      name: translate(language, "paymentWait.method.iban"),
-    })
-    .waitFor()
-}
-
 async function capturePage(
   page: Page,
   name: ScreenshotScenario["name"],
@@ -175,15 +97,15 @@ const scenarios: ReadonlyArray<ScreenshotScenario> = [
   {
     name: "home",
     async capture(page, language) {
-      await completeOnboarding(page, language)
+      await completeOnboarding(page, language, { baseURL: appUrl })
       await enterAmount(page, language)
       await capturePage(page, "home", language)
     },
   },
   {
     name: "payment",
     async capture(page, language) {
-      await completeOnboarding(page, language)
+      await completeOnboarding(page, language, { baseURL: appUrl })
       await createPayment(page, language)
       await page
         .getByRole("tab", {
@@ -201,25 +123,17 @@ const scenarios: ReadonlyArray<ScreenshotScenario> = [
   {
     name: "paid",
     async capture(page, language) {
-      await completeOnboarding(page, language)
+      await completeOnboarding(page, language, { baseURL: appUrl })
       await createPayment(page, language)
-      await page
-        .getByRole("button", {
-          name: translate(language, "paymentWait.cashPaid.action"),
-        })
-        .click()
-      await page
-        .locator('[aria-hidden="false"]')
-        .getByText(translate(language, "paymentWait.paid"))
-        .waitFor()
+      await markCashPaid(page, language)
       await page.waitForTimeout(350)
       await capturePage(page, "paid", language)
     },
   },
   {
     name: "settings",
     async capture(page, language) {
-      await completeOnboarding(page, language)
+      await completeOnboarding(page, language, { baseURL: appUrl })
       await page
         .getByRole("button", { name: translate(language, "settings.title") })
         .click()

e2e/activity.spec.ts

@@ -0,0 +1,54 @@
+import {
+  createPayment,
+  expect,
+  gotoPage,
+  markCashPaid,
+  test,
+  translate,
+} from "./fixtures.ts"
+
+test("a paid payment shows up in activity list and detail", async ({
+  seededPage: page,
+}) => {
+  await test.step("create a cash payment", () => createPayment(page, "en"))
+  await test.step("mark the payment as paid", () => markCashPaid(page, "en"))
+
+  await test.step("open activity from the paid confirmation", async () => {
+    await page
+      .getByTestId("payment-paid-panel")
+      .getByRole("button", { name: translate("en", "paymentWait.detail") })
+      .click()
+    await page
+      .getByRole("heading", { name: translate("en", "paymentDetail.title") })
+      .waitFor()
+  })
+
+  await test.step("verify the payment detail shows paid status", async () => {
+    await expect(
+      page.getByText(translate("en", "paymentDetail.status.paid"), {
+        exact: true,
+      })
+    ).toBeVisible()
+  })
+
+  await test.step("navigate to the activity list", () =>
+    gotoPage(page, "/activity", "en", "activity.title"))
+
+  await test.step("open the payment from the activity list", async () => {
+    await page
+      .locator("nav")
+      .getByRole("link", {
+        name: translate("en", "paymentHistory.status.paid"),
+      })
+      .first()
+      .click()
+    await page
+      .getByRole("heading", { name: translate("en", "paymentDetail.title") })
+      .waitFor()
+    await expect(
+      page.getByText(translate("en", "paymentDetail.status.paid"), {
+        exact: true,
+      })
+    ).toBeVisible()
+  })
+})