E2E Testing

Frontend apps have no separate unit suite. Two Playwright suites: Web (apps/web) for the product UI, API (apps/api) for Scalar login at /reference. Both use @test.ai addresses when ALLOW_TEST=true.

The Scalar page loads @scalar/api-reference from jsDelivr (pinned version in reference/template.ts). E2E depends on that CDN for the login button script.

Install Chromium for both suites with pnpm setup:playwright (or pnpm setup) if browsers are missing.

Root pnpm qa builds, then ends with pnpm test:e2e (SKIP_BUILD=1, scripts/run-e2e.mjs). That script kills processes on ports 3000 and 3001 unless SKIP_KILL_PORTS=1. Shared spawn env lives in scripts/e2e-local-shared.mjs.

Commands

Pass URLs with --app / --api, or PLAYWRIGHT_APP_URL / PLAYWRIGHT_API_URL. Defaults: http://localhost:3000 and http://localhost:3001.

pnpm test:e2e --app=https://my-app.vercel.app --api=https://my-api.vercel.app

Session model

Use one worker (PGlite cannot take concurrent writers). The setup project logs in as test@test.ai once and writes test-results/.auth/user.json. chromium, security, and chat reuse that file via project storageState. auth, passkey-login, and logout tests use empty storage so they never revoke the shared session.

Import page from @playwright/test in all specs. Navigate to the target route in each authed test (page.goto('/settings/...')).

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

test('shows dashboard when authenticated', async ({ page }) => {
  await page.goto('/')
  await expect(page.locator('text=Signed In')).toBeVisible()
})

Chat E2E needs a real ANTHROPIC_API_KEY (in-app Claude Haiku 4.5 by default). Playwright omits the chat project when hasRealAnthropicKey() is false (empty, sk-ant-xxx, sk-ant-dummy*), so fork CI without org secrets still runs auth and dashboard E2E. When the key is set, chat-assistant.spec.ts skips only quota or credit errors; upstream 5xx and network failures fail the test run. API Scalar E2E (pnpm --filter @repo/api test:e2e:local) does not call AI and does not require Anthropic. API remote tests (ai.spec.ts) use test/utils/ai-remote.ts: skip 402 always; skip 502/503/504 only with placeholder/missing key — real key fails on 502. See AI Architecture.

Test helpers

ALLOW_TEST=true stores plain tokens in verification.token_plain for @test.ai addresses.

Local spawn scripts set ALLOW_TEST. The API process exits if ALLOW_TEST is true in production.

Playwright projects (order)

1. public — legal pages, login smoke, robots/sitemap
2. auth — 01-callbacks … 06-logout (empty storage; depends on public; file-name order)
3. setup — writes user.json (depends on auth)
4. chromium — dashboard smokes, 404 (storageState)
5. security — TOTP, API keys, passkeys CRUD (storageState; never logout)
6. passkey-login — passkey sign-in with e2e-passkey@test.ai (empty storage; depends on setup)
7. chat — assistant (storageState; mobile viewport; last)

Dedicated emails: test@test.ai (shared), e2e-passkey@test.ai, e2e-email@test.ai (change-email).

Web specs

CI and mobile

Path-filtered PR workflows: api-e2e.yml, web-e2e.yml, packages-test.yml. See GitHub Actions.

Expo uses Maestro (apps/mobile/.maestro/flows/home.yml). CI Maestro is deferred; see Mobile CI/CD.

Vercel protection (manual)

For protected previews: enable Protection Bypass for Automation on both projects with the same secret, set VERCEL_AUTOMATION_BYPASS_SECRET, and allowlist OPTIONS / or /auth on the API project.

Troubleshooting

Ports in use: bash scripts/kill-test-servers.sh. Token extraction fails: confirm ALLOW_TEST=true and the correct @test.ai email query on /test/verification/last. Magic link 500 mid-suite: local/CI spawn sets RATE_LIMIT_MAX=10000 (default API limit is 100/min per IP). Passkey registration fails in CI: spawn scripts and web-e2e.yml set WEBAUTHN_RP_NAME=Test App when .env.test is absent.

Related

• Testing
• GitHub Actions
• Frontend Architecture