e2e
Validation of the whole stack, run by hand or by an agent, never by
task check or CI. It needs PostgreSQL 18, five services, Vite and a browser,
which the gate must not. Docker is not needed: without it tasks queue and
park, which is useful data for the dashboard.
| File | What it does |
|---|---|
stack.sh |
Starts PostgreSQL 18 (port 55432) and the five services as local processes, then Vite on 5173 |
seed.sh |
Seeds the stack through the dashboard API; safe to rerun |
run.cjs |
Runs checks/*.cjs in Chromium; screenshots to out/ |
checks/ |
One module per behaviour |
results/ |
One committed report per release |
Run
task e2e:up # build, start everything, seed
task e2e:check # list available checks (no stack needed)
task e2e:check -- list # explicitly list checks
task e2e:check -- workflow-phone # one check
task e2e:check -- all # all checks
task e2e:check -- --headed accessibility # watch a check in Chromium
task e2e:check -- --headed all # watch every check
task e2e:down # stop; e2e/stack.sh reset also deletes the data
Headless is the default. --headed opens visible Chromium and slows browser
actions to 150ms so you can follow them; assertions and saved evidence are the
same in both modes. The terminal prints each check before it starts. Headed mode
requires a graphical desktop.
Nothing reads the installed config: stack.sh points the XDG directories at
${ARCHIE_DEV_DIR:-~/.local/state/archie-dev} and writes its overlay from
deployments/dev.toml. Logs are in its logs/. e2e/stack.sh restart archied
restarts one service. Run task e2e:down before starting again: startup refuses
occupied service ports and checks that each launched process stays alive.
The seed creates a local test administrator: operator@example.test, password
archie-local-e2e-password. Use it at http://localhost:5173; the browser
checks sign in with the same account. These are test fixtures for this
loopback-only stack. To use an existing test account, set ARCHIE_E2E_EMAIL
and ARCHIE_E2E_PASSWORD for both seeding and browser checks. Seeding never
resets an existing account or deletes test data.
The first run needs npm ci --prefix e2e and npx --prefix e2e playwright install chromium. In the cloud environment, Chromium and Playwright are
preinstalled; run with NODE_PATH=$(npm root -g).
Release evidence
node e2e/run.cjs --record v1.54.0 all
writes results/v1.54.0.md, the pass or fail of every check for that
release. Commit it with the release. Screenshots stay in out/.
Writing a check
A module in checks/ exports async ({ page, go, shot, fail }). go(path)
loads a dashboard route, shot(label) saves a screenshot, fail(msg) records
a problem without stopping. A throw, a fail, or any console or page error
fails the check. Wait for elements, never for networkidle: the event stream
never goes idle.
routes loads every static route and flags text with stray leading,
trailing or doubled spaces. seeded checks the seed is visible.
Pitfalls
| Symptom | Cause | Fix |
|---|---|---|
| State Store exits: server is older than PostgreSQL 18 | another server answered | stack.sh uses port 55432; set ARCHIE_DEV_PGPORT if that is taken |
| Startup says a port is in use | a stack or another process already owns it | Run task e2e:down, then task e2e:up; inspect any remaining listener with ss -ltnp |
| Your own shell is killed (exit 144) | pkill -f matched its own command line |
stack.sh stop or restart, which kill by PID |
npx shadcn-vue add cannot fetch the registry |
Node's fetch ignores the cloud agent proxy | curl the registry JSON and copy the files |
| Postgres aborts in the cloud | /tmp/claude-0 is reset to mode 700 |
stack.sh keeps the root cluster in /var/lib/archie-dev |