15c0c35df6
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
217 lines
12 KiB
Markdown
217 lines
12 KiB
Markdown
---
|
|
id: session-hostname-resolution-04
|
|
title: E2E and final verification
|
|
status: pending
|
|
wave: 4
|
|
depends_on: [session-hostname-resolution-03]
|
|
plan: docs/plans/session-hostname-resolution/plan.md
|
|
spec: docs/specs/session-hostname-resolution/spec.md
|
|
---
|
|
|
|
# E2E and final verification
|
|
|
|
## Inputs
|
|
|
|
Tasks 01-03 and the [spec](../../specs/session-hostname-resolution/spec.md)
|
|
acceptance criteria. Existing E2E patterns:
|
|
`apps/web/e2e/tests/auth/auth-screenshots.spec.ts` (auth-mode restart +
|
|
account security page), `apps/web/e2e/helpers/auth.ts` (`setupAdmin`, `login`,
|
|
`mintPAT`), `apps/web/e2e/helpers/causal-waits.ts` (causal wait primitives),
|
|
and `apps/web/e2e/README.md` for projects/commands.
|
|
|
|
## Project placement (verified against `apps/web/e2e/playwright.config.ts`)
|
|
|
|
- `tests/auth/*.spec.ts` runs in the **`auth` project**: the backend is
|
|
restarted with auth enabled and the whole API is locked behind a login;
|
|
`mobile-*.spec.ts` files under `tests/auth/` run in the **`mobile-chrome`**
|
|
project instead (the auth project's `testIgnore` excludes them). The new
|
|
spec **must not** claim to run on the default project.
|
|
|
|
## Implementation
|
|
|
|
### Desktop spec — `apps/web/e2e/tests/auth/account-security-hostnames.spec.ts`
|
|
|
|
Setup (mirror `auth-screenshots.spec.ts` for the restart shape, plus
|
|
`mobile-users-self-actions.spec.ts` for DB isolation):
|
|
|
|
- `beforeAll`: `backend.restart({ KANDEV_FEATURES_AUTH: "true",
|
|
KANDEV_DATABASE_PATH: path.join(backend.tmpDir,
|
|
"kandev-hostnames-desktop.db") })` — **an isolated DB path is required**,
|
|
exactly as in the mobile spec. The auth project's worker is serial/shared
|
|
and `backend.restart` preserves the existing SQLite DB, so without an
|
|
isolated path this spec's second login (focus-refetch step), hostname
|
|
cache rows, and admin state leak into later auth-project tests, and
|
|
`setupAdmin` may find the instance already past setup mode. The isolated
|
|
DB also makes this spec's own row-count assertions deterministic across
|
|
runs.
|
|
- **Lifecycle (pinned):** call **`setupAdmin(...)` only** to create the
|
|
admin and authenticate the page context — `/auth/setup` already creates
|
|
the admin's session and sets the `kandev_session` cookie on the context,
|
|
so the baseline sessions table has exactly **one** row. Do NOT call
|
|
`login(...)` for the main flow (it would create a second baseline row and
|
|
skew the isolation proof). `login(...)` is used only in the focus-refetch
|
|
step to create the second session row. The page context must carry the
|
|
authenticated session cookie for both the settings page and the
|
|
`afterEach` cleanup PATCH.
|
|
- `afterAll`: `backend.restart()` to return to the baseline env (this
|
|
reverts the DB path too).
|
|
- `afterEach`: PATCH `resolve_session_hostnames` back to `false` using the
|
|
authenticated API client (the E2E worker does not reset user settings
|
|
between tests).
|
|
- **Isolation model (single test, no false claims):** the spec is **one
|
|
`test(...)`** containing the whole flow below — a second test cannot
|
|
assert a fresh one-row baseline because the isolated DB persists across
|
|
tests within the worker (setupAdmin runs once in `beforeAll`, and the
|
|
focus-refetch `login` adds a session that no `afterEach` removes).
|
|
Cross-spec isolation comes from the isolated `KANDEV_DATABASE_PATH`
|
|
itself (other auth-project specs use their own/`backend`'s DB), not from
|
|
an in-spec two-test proof. Within the single test, the row-count
|
|
assertions are: exactly **one** row after `setupAdmin` (fresh DB), and
|
|
exactly **two** after the focus-refetch `login` — these are
|
|
deterministic because the DB is dedicated to this spec.
|
|
|
|
Flow (assertions are env-robust; DNS answers vary — never assert an exact
|
|
hostname). The E2E **never depends on `auth.session.hostname.resolved`
|
|
events**: the worker-scoped backend keeps its DB (and therefore the hostname
|
|
cache) across tests, and every e2e login comes from the same loopback IP, so
|
|
a first-resolution or changed-result event is not guaranteed for any toggle.
|
|
Streaming behavior is covered by the resolver/WS-handler/component unit
|
|
tests; the E2E validates the UI contract (column, hostname-or-`N/A` cells,
|
|
cached rendering on re-enable, persistence, focus-refetch):
|
|
|
|
0. Before navigation: `const watch = watchWs(page);` then `page.goto(...)`
|
|
(per `causal-waits.ts`, `watchWs` must precede the first `goto`).
|
|
1. Navigate to `/settings/account/security`; assert the sessions table has no
|
|
Hostname column (toggle is off by default).
|
|
2. Toggle the switch on; assert the column appears and every row's cell is
|
|
either `N/A` or a non-empty hostname immediately (empty always renders
|
|
`N/A`; there is no pending state).
|
|
3. Toggle off; assert the column is hidden.
|
|
4. Toggle on again; assert the column reappears with values (cached from the
|
|
in-memory map and/or the enable-transition refetch's `hostname` values —
|
|
`N/A` or a non-empty hostname). Do NOT wait for a WS event here: an
|
|
unchanged or fresh-cache result intentionally emits none.
|
|
5. Reload the page; assert the toggle is still on and the column is shown
|
|
with hostname-or-`N/A` cells (persistence through user settings).
|
|
6. New-session discovery (required, not skippable): with the page still
|
|
open, call `login(...)` **again through the same BrowserContext's request
|
|
client** — that is what creates a second `auth_sessions` row (navigating
|
|
alone only reuses the cookie and adds nothing; the baseline is the single
|
|
`setupAdmin` session, so the table must grow from one row to two). Then:
|
|
a. `const page2 = await ctx.newPage();`
|
|
b. **Explicitly activate page 2 first:** `await page2.bringToFront();`
|
|
— `goto` alone is navigation, not activation, and the focus handler
|
|
on page 1 must deterministically fire from a real blur/focus
|
|
transition.
|
|
c. `await page2.goto("/")` (shared cookies authenticate it); wait for
|
|
the app shell to render on page 2.
|
|
d. Arm a causal wait for the sessions refetch (`watch.waitForHttp` or
|
|
`page.waitForResponse` on `GET /api/v1/auth/sessions`), then
|
|
`await page.bringToFront()` on the original page; await the sessions
|
|
response — this proves the focus handler fired and refetched.
|
|
e. Assert the sessions table now has **two** rows (the `setupAdmin`
|
|
session plus the new login) and the new row's hostname cell is
|
|
hostname-or-`N/A`. If the auth fixture cannot create a second session
|
|
for the same admin, fix the fixture rather than dropping the
|
|
assertion.
|
|
|
|
### Mobile spec — `apps/web/e2e/tests/auth/mobile-account-security-hostnames.spec.ts`
|
|
|
|
Runs in the **`mobile-chrome`** project (routed away from the desktop `auth`
|
|
project via its `testIgnore`), which does NOT inherit the auth project's
|
|
backend restart — the spec must set it up itself, mirroring
|
|
`mobile-users-self-actions.spec.ts`:
|
|
|
|
- `beforeAll`: `backend.restart({ KANDEV_FEATURES_AUTH: "true",
|
|
KANDEV_DATABASE_PATH: path.join(backend.tmpDir,
|
|
"kandev-hostnames-mobile.db") })` (an isolated DB so the hostname cache
|
|
does not leak between the desktop and mobile workers); `afterAll`:
|
|
`backend.restart()` to the baseline env.
|
|
- Create a manual context: `browser.newContext({ ...devices["Pixel 5"],
|
|
baseURL: backend.frontendUrl })` (manual contexts do not inherit project
|
|
device options), then `setupAdmin` + `login` before navigating.
|
|
- `afterEach`: PATCH `resolve_session_hostnames` back to `false` with the
|
|
authenticated client.
|
|
|
|
Flow at the Pixel 5 viewport: enable → column appears → cells are
|
|
hostname-or-`N/A` (no WS waits, per the desktop flow), disable → hidden,
|
|
re-enable → restored. Assert the toggle switch row is reachable/tappable and
|
|
the page has no document-level horizontal overflow with the Hostname column
|
|
rendered.
|
|
|
|
## Final verification
|
|
|
|
```sh
|
|
(cd apps/backend && go test -race ./internal/auth/... ./internal/user/... ./internal/gateway/websocket/... ./internal/backendapp/... ./pkg/websocket/...)
|
|
make -C apps/backend lint
|
|
(cd apps/web && pnpm run i18n:check)
|
|
(cd apps/web && pnpm run i18n:ratchet)
|
|
(cd apps/web && pnpm run typecheck)
|
|
(cd apps/web && pnpm run lint)
|
|
(cd apps/web && pnpm exec vitest run lib/ssr/user-settings.test.ts lib/ws/handlers/users.test.ts lib/ws/handlers/session-hostnames.test.ts lib/state/slices/auth/auth-slice.test.ts components/settings/account/security-settings.test.tsx)
|
|
(cd apps/web && pnpm e2e:run --project auth tests/auth/account-security-hostnames.spec.ts)
|
|
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/auth/mobile-account-security-hostnames.spec.ts)
|
|
git diff --check
|
|
```
|
|
|
|
Update the plan's wave table and this task's status to `done` when green.
|
|
|
|
## Acceptance
|
|
|
|
1. The desktop spec (auth project) proves default-off, enable → column +
|
|
hostname-or-`N/A` cells (no WS-event waits), disable → hidden, re-enable →
|
|
restored with cached values, reload persistence, and focus-refetch
|
|
discovery of a second login, with authenticated setup/cleanup.
|
|
2. The mobile spec (mobile-chrome project) proves the same flow at Pixel 5
|
|
width with no horizontal overflow, using its own auth-enabled backend
|
|
restart (isolated DB), `setupAdmin`/`login`, and authenticated cleanup.
|
|
3. All focused backend and frontend checks pass; `git diff --check` is clean.
|
|
4. The spec/plan/task statuses are updated to match reality.
|
|
|
|
## Verification
|
|
|
|
The commands in "Final verification" are the acceptance gate.
|
|
|
|
## Dependencies
|
|
|
|
Tasks 01-03.
|
|
|
|
## Risks
|
|
|
|
- Running the spec without the auth project's env/helpers: `GET
|
|
/api/v1/auth/sessions` is behind `RequireRealIdentity`, so an unauthenticated
|
|
page cannot load sessions. Always restart with `KANDEV_FEATURES_AUTH:
|
|
"true"` and log in first.
|
|
- Exact-hostname assertions flake across environments (no PTR, `localhost`,
|
|
synthesized `.in-addr.arpa`). Assert column presence/absence and
|
|
hostname-or-`N/A` cell text only; because `N/A` renders immediately there
|
|
is no pending state to wait for.
|
|
- Never await `auth.session.hostname.resolved` in E2E: the worker backend
|
|
keeps its cache across tests and e2e logins share one loopback IP, so a
|
|
first-resolution or changed-result event is not guaranteed (fresh cache
|
|
and unchanged results intentionally emit nothing). Streaming is proven by
|
|
unit/component tests.
|
|
- Focus-refetch coverage must **call `login` again** through the same
|
|
context's request client (only setup/login create `auth_sessions` rows;
|
|
navigation reuses the cookie), then navigate a second same-context page so
|
|
page 1 really loses focus, then `bringToFront` page 1 and assert the row
|
|
count grew by exactly one. It must not be skippable; fixture limitations
|
|
are fixture bugs.
|
|
- The desktop spec must restart with an isolated `KANDEV_DATABASE_PATH`
|
|
(the auth worker is serial/shared and `backend.restart` preserves the DB);
|
|
without it, the focus-refetch second login, hostname cache, and admin
|
|
state leak into later auth-project tests and `setupAdmin` may not be in
|
|
setup mode. Keep the spec a single test with deterministic 1-row → 2-row
|
|
assertions; cross-spec isolation comes from the dedicated DB path, not an
|
|
in-spec two-test proof (the DB persists across tests, so a second test
|
|
cannot claim a fresh baseline).
|
|
- The mobile spec runs in the `mobile-chrome` project, which does not
|
|
inherit the auth project's backend restart; it must restart auth-enabled
|
|
with an isolated DB itself (per `mobile-users-self-actions.spec.ts`) or
|
|
the page hits setup/unauthenticated mode and sessions never load.
|
|
- A leftover enabled setting leaks into later specs; always reset in
|
|
`afterEach` with the authenticated client.
|
|
- The managed E2E runner must rebuild production assets on the first run;
|
|
re-run with `--no-build` only after a successful prior build from the same
|
|
tree.
|