AGENTS.md@e2e/console · diff

git:20261014.c1def64 to git:20261020.8d47d7a

43 added, 76 removed. Audit A to A.

# Agent Instructions — `e2e/console`

- Playwright project for the console's five runtime boundaries. Defer to root

- [`AGENTS.md`](../../AGENTS.md) for repo-wide rules; lane descriptions and the

- secret-handling caveat live in [`README.md`](README.md).

- ## The five lanes

- - `moon run e2e:console-smoke` — **embedded shell smoke**: Vite-preview of the

- built console under its production embed base `/ui/console/`. No live API.

- - `moon run e2e:console-real` — **real-instance resource coverage**: one

- ephemeral real instance via `@zitadel/testing`

- ([`packages/testing/AGENTS.md`](../../packages/testing/AGENTS.md)), console

- served by the Vite dev server through its (credential-free) API proxy; each

- test's user is granted access through the API and signs in with its

- session cookie (`signIn` in `support/sign-in.ts`). Playwright workers share the

- instance and seed a fresh user per test.

- - `moon run e2e:console-embedded` — **embedded production-path coverage**:

- the built Go binary serves the console, hosted login, and API from one

- origin, with no Vite proxy. This is the only lane that proves the API base

- and Go mux agree on the request path customers receive.

- - `moon run e2e:console-platform` — **platform-project coverage**: the

- same binary with the platform project bootstrapped (the server default). An

- operator signs up through the console, is granted the harness project by

- email, and uses the screens on the session cookie alone. The console selects

- that project on its own (the operator's only grant, as `?project=`), so the

- screens run in a project other than the one the console signs into.

- - `moon run e2e:console-deployment` — **hosted-cloud deployment

- coverage**: no server of its own; it checks a deployment that `CLOUD_URL`

- names, where the console is a Vercel service at `/console/` beside the

- server. It pins the routing (`/console/runtime.json` to the server, the old

- `/ui/console` links redirected) and the signed-out sign-in screen down to

- the login widget's first step. It holds no credential but

- `VERCEL_AUTOMATION_BYPASS_SECRET`, so it records no traces and writes no

- HTML report. `pnpm check:cloud` runs it beside the docs' deployment suite.

- Console screens act on the selected project (`?project=`, see

- [`apps/console/AGENTS.md`](../../apps/console/AGENTS.md)). The guard only ever selects

- a project the signed-in person holds a grant on: their only project, else

- none. `console-real` grants each signed-in user the harness project (`signIn` in

- `support/sign-in.ts`), so it is selected there; a user with no grant lands on

- Projects with nothing selected. The project the console signs into comes from

- the instance's `/console/runtime.json` in every lane; no lane pins it. A spec

- that navigates by URL either lets the guard fill it in or names it, and asserts

- it survives navigation where that is the point.

+ The console's runtime boundaries, the part its Vitest specs cannot reach. Lane

+ details and secret handling: [`README.md`](README.md).

- The first four lanes are dependencies of `e2e:all`, which the `full-pr` job

- runs in its own e2e step whenever one of them is affected (they carry

- `runInCI: "skip"`, which only keeps them out of the build-and-test graph; see

- [`../moon.yml`](../moon.yml)). `console-deployment` is not part of it

- (`runInCI: false`): `deployment-checks.yml` runs it against every cloud

- deployment. The `@zitadel/testing` interaction is documented in

- [`packages/testing/AGENTS.md`](../../packages/testing/AGENTS.md).

+ ## Lanes

- ## Shared helpers

+ - `moon run e2e:console-smoke`: the built console in Vite preview under its

+ embed base `/ui/console/`, with no API.

+ - `moon run e2e:console-real`: one real instance through `@zitadel/testing`,

+ the console on the Vite dev server behind its credential-free proxy. Each

+ test grants and signs in its own user (`signIn` in `support/sign-in.ts`).

+ - `moon run e2e:console-embedded`: the built Go binary serves the console,

+ the login and the API from one origin. The only lane that proves the API

+ base and the Go mux agree on the path customers receive.

+ - `moon run e2e:console-platform`: the same binary with the platform project

+ bootstrapped, as `zitadel start` (and so `@zitadel/testing`) does by

+ default; the server alone leaves it off (`platform.bootstrap_project`). An

+ operator works in a granted project other than the one the console signs

+ into.

+ - `moon run e2e:console-deployment`: checks the hosted-cloud deployment

+ `CLOUD_URL` names. It holds only `VERCEL_AUTOMATION_BYPASS_SECRET`, so it

+ records no traces and no HTML report. `pnpm check:cloud` runs it with the

+ docs and schemas deployment suites; `deployment-checks.yml` runs it for

+ every deployment.

- `support/` holds what more than one spec uses: the console sign-in (`sign-in.ts`,

- grant then login), the API arrangements on the typed client (`api.ts`), screen

- helpers (`screens.ts`), the runtime-document stubs (`runtime.ts`) and the

- console copy the specs assert on (`copy.ts`). Two of them have importers with

- less in reach: `runtime.ts` imports only `@playwright/test`, because the smoke

- lane builds no test kit, and `copy.ts` imports nothing, because the journey's

- claim suite reads it (the journey lanes list it as an input).

+ How the other four run in CI and locally:

+ [`packages/testing/AGENTS.md`](../../packages/testing/AGENTS.md#moon-and-the-e2e-lanes).

- ## Hard rules

+ ## Rules

- - **Port pinning**: `REAL_ZITADEL_PORT: 8093`, `EMBEDDED_ZITADEL_PORT: 8095`

- and `PLATFORM_ZITADEL_PORT: 8097` are fixed pins deliberately outside the

- deferred-bind blocks — the full doctrine (why config-time ports cannot live

- in the dynamically scanned reservation domains, and the neighbor map) is in

- the lane configs (`playwright.*.config.mts`) and

- [`../journey/scripts/ports.mjs`](../journey/scripts/ports.mjs). Do not

- move any of these lanes onto a scanned block, and sweep orphans with

- `moon run workspace:cli -- stop --all`.

- - **Secrets**: the `.zitadel-testing/` handshake contains the project secret —

- gitignored, never uploaded as a CI artifact. Failure artifacts are limited

- to Playwright results and the HTML report.

- - **Test placement**: this project covers only console runtime boundaries

- (embed base, dev proxy, live resource data, binary-served production path,

- the hosted cloud's routing).

- Screen behavior belongs in `apps/console` Vitest specs

- (`src/routes/**/*.spec.tsx`); component behavior in the component packages —

- same layering rule as root `AGENTS.md` Testing Layers.

+ - Cover only runtime boundaries (embed base, dev proxy, live data, the

+ binary-served path, the cloud's routing). Screen behaviour belongs in

+ `apps/console`'s specs (`src/routes/**/*.spec.tsx`), component behaviour in

+ the component packages.

+ - Screens act on the selected project (`?project=`). The guard selects only a

+ project the person holds a grant on, and no lane pins the project the

+ console signs into: it comes from the instance's `/console/runtime.json`. A

+ spec that navigates by URL lets the guard fill in `?project=` or names it.

+ - `REAL_ZITADEL_PORT`, `EMBEDDED_ZITADEL_PORT` and `PLATFORM_ZITADEL_PORT` are

+ fixed pins outside the scanned port blocks (why: the lane configs and

+ [`../journey/scripts/ports.mjs`](../journey/scripts/ports.mjs)). Never move

+ a lane onto a scanned block.

+ - The `.zitadel-testing/` handshake holds the project secret: keep it

+ gitignored and never upload it. Failure artifacts are only the Playwright

+ results and the HTML report.

+ - Put helpers more than one spec uses in `support/`. `support/runtime.ts`

+ imports only `@playwright/test`, because the smoke lane builds no test kit;

+ `support/copy.ts` imports nothing, because the journey's claim suite reads

+ it.