auth-emulator-e2e

Files (1)

• SKILL.md

SKILL.md (first lines)

# Auth-emulator E2E

Emulator-backed auth e2e fails in a different layer each time because the pieces disagree **silently**: login looks fine, the failure just moves (wrong bucket → 401 → empty session → schema 500). This skill is the verified checklist to align them. Provider-agnostic invariants first, concrete per-provider commands after.

## Role and boundary

This skill OWNS the **test configuration** for emulator-backed auth e2e: bringing the layers into agreement and proving it. It does **not** write or run feature tests, derive test cases, or assert on behavior — that is `feature-testing`'s job.

Invoke it when:

- setting up an emulator-backed auth e2e suite for the first time, or
- a suite is failing for a configuration reason (the symptoms in this skill's description: login works but API 401s, saved session empty / specs logged out, signup "already exists" against a fresh emulator, authed write 500s with an undefined column).

`feature-testing` hands off here instead of debugging config itself. Fix the config, prove it, then hand back (see "On completion").

## Detect first — does this apply?

Run the checklist only if ALL hold:

- repo has a browser e2e config (e.g. `playwright.config.*`), AND
- e2e authenticates a real user (a setup/login step, not anonymous), AND
- auth goes through a local emulator/stub (config references an emulator host/port, or a fake/`test` API key).

If e2e hits the **real** provider, skip — different concerns. Identify the provider from deps to pick the concrete section: `firebase`/`firebase-admin` → Firebase; `@supabase/*` + `supabase` CLI → Supabase; `cognito-local` → Cognito; an OIDC/Auth0 mock → Auth0.

## The four invariants (every provider)

Each maps to one real failure mode. Verify all four before trusting a green or chasing a red.

### A — One project/tenant id across all three consumers
The emulator-minted token carries a project/tenant (`aud`/`iss`). The SAME id and SAME emulator host must be used by: (1) the client SDK in the browser bundle, (2) the server-side token verifier, (3) any test helper that mints/inspects tokens.
**Symptom:** signup "succeeds" or "already exists" in one bucket while the verifier/helper queries an empty other bucket; setup passes but nothing lands where you look.
**Verify:** list the emulator's users for the configured project AND decode a freshly minted token's `aud` — they must equal the server's expected project.

### B — Server told to trust emulator tokens
Emulator tokens are unsigned; the server's admin SDK verifies real signatures unless an emulator-mode env var is set **on the server process**.
**Symptom:** login works, every authed API call is 401 "invalid token".
**Verify:** the server process env has the provider's emulator var; one authed request returns non-401.

### C — Test server must not serve prod config
If the runner can reuse an already-running dev server, it may serve one started without the emulator env, so the SDK silently hits the real provider. A committed `.env` with real values can shadow what you think you injected (env precedence).
**Symptom:** SDK reaches the real provider; signup says "already exists" (a real account) while the emulator is empty.
**Verify:** force the run to start its own server (disable reuse), or assert the emulator host string reached the served bundle.

### D — Session capture includes the SDK's real storage
Saving a logged-in session persists only the stores you ask for. Some SDKs keep the session in IndexedDB, not cookies/localStorage.
**Symptom:** saved state file is near-empty; specs reusing it start logged out.
**Verify:** the saved state file is non-trivial and contains the auth payload; a reusing spec lands on an authed page without touching the login form.

### Then — DB schema (the next failure after auth)
Auth e2e exercises the write path. A test DB behind the model 500s on the first authed write with "undefined column"/"no such table" — looks like an app bug, is a missing migration. Migrate to head before trusting writes.

**Isolate that DB per worktree/branch when agents run concurrently.** The app server the browser hits reads and writes a database; if two parallel worktrees point their servers at the *same* database, they fight over its schema and migration head the same way parallel unit runs do — one branch's `alembic upgrade head` strands the other on an unknown revision, or a reshaped table/function 500s the other's writes. Point this run's server at its own database (a per-branch/worktree name via the same env override the unit suite uses), provision + migrate it, and inject that into the test server's env (invariant C already forces the run to start its own server — give that server the isolated DB URL). `feature-testing` §1a owns the naming/provisioning/teardown mechanics; do not point an e2e run at a shared or dev database.

## Provider: Firebase Auth + Playwright (concrete)

Detect: `firebase` in frontend deps, `firebase-admin` in backend, a `firebase.json` / emulator host in config.

**A — align project (the silent one):**
- Pin the emulator project. `firebase emulators:start` with no `--project` and no `.firebaserc` picks an unpredictable default; with `singleProjectMode:true` all SDK writes go to that one project, so it must be the right one. Add `.firebaserc` `{"projects":{"default":"<id>"}}` or pass `--project <id>`.
- Client config project (`NEXT_PUBLIC_FIREBASE_PROJECT_ID` or equivalent) == that id. Backend `FIREBASE_PROJECT_ID` == that id.
- List users: `curl -s -X POST "http://<host>/identitytoolkit.googleapis.com/v1/projects/<id>/accounts:query" -H "Authorization: Bearer owner" -H "Content-Type: application/json" -d '{}'`
- Decode token `aud`: sign in via `accounts:signInWithPassword?key=<anykey>`, base64-decode the JWT payload (middle segment), confirm `aud`/`iss` name `<id>`.

**B — backend trusts emulator:** set `FIREBASE_AUTH_EMULATOR_HOST=<host>` on the backend process; the Admin SDK then skips signature verification. Token `aud` must still match the backend project.

**C — no prod server:** in `playwright.config`, `webServer.reuseExistingServer: false` for e2e, and inject the emulator host + project via `webServer.env`. Confirm the frontend init gates `connectAuthEmulator(...)` on that env var (so prod is untouched when it is absent).

**D — IndexedDB:** Firebase persists the session in IndexedDB (`firebaseLocalStorageDb`). Save with `page.context().storageState({ path, indexedDB: true })` (Playwright ≥1.51). Without the flag the file is `{"cookies":[],"origins":[]}` and reuse starts logged out.

**Emulator helpers** (it sends no email, validates no key): clear users `DELETE /emulator/v1/projects/<id>/accounts`; verify email `POST .../accounts:update {localId,emailVerified:true}`.

## Provider: Supabase + Playwright (sketch)

Detect `@supabase/supabase-js` + `supabase` CLI; `supabase start` runs GoTrue locally.
- **A:** project ref + anon key from `supabase status` must match client and server.
- **B:** the API validates JWTs with the **local** GoTrue JWT secret (`SUPABASE_JWT_SECRET` from `supabase status`), not the prod secret.
- **C/D:** same traps; Supabase keeps its session in localStorage by default, so `storageState` captures it without the IndexedDB flag — but confirm rather than assume.

## Provider: Auth0 / OIDC mock (sketch)

Use a local mock (OIDC stub / `@auth0/*` mock).
- **A:** align `audience` + `issuer` between the SDK and the API.
- **B:** point the API's JWKS/issuer at the mock so it trusts mock-signed tokens.
- **C/D:** identical — isolate the test server, capture whatever storage the SDK uses.

## On completion — hand back

Report which invariant(s) failed, the command that proved each, and the one-line fix applied. Prove the config is sound before declaring done:

- the session-setup step runs green and the saved state file actually carries the session,
- one authed request returns non-401,
- one authed write succeeds (no schema 500).

That is the boundary. Do **not** go on to write or run the feature's test ladder here — you were configuring, and a test pass should not be judged from the same agent that just mutated the environment. Hand back so the caller runs the real pass from a **fresh `feature-testing` agent** (clean context, cold start, closest to CI). State explicitly in your return that the configuration is verified and a fresh test run is the next step.

From 2003gdb/My-Claude-Workflows, MIT.

More from 2003gdb/My-Claude-Workflows