browser tests that follow a write through every service. a flow drives the web app in a real browser against the localinfra stack, then checks that every service the write passed through (pds, knot, hydrant, bobbin, spindle) agrees with what the page showed.

pnpm e2e                        # the whole suite, bringing the stack up if it isn't
pnpm e2e specs/social.spec.ts   # one spec
pnpm e2e --report=report.html   # also write an html report
pnpm e2e --har=run.har          # also write the requests as a har
pnpm e2e --login=ui             # every new account logs in through the login page
pnpm e2e:up                     # start the stack without running anything
pnpm e2e:sweep                  # cleans up after a crashed run

with 12 workers its about 4-5 minutes for the whole suite on an m5 macbook. --workers=6 or lower might be useful for less RAM / CPU (it uses a ton of cpu in a vm like colima anyway).

the html report is drawn with the web's own components, so it needs pnpm install in web/ (or --web-modules=<a web node_modules>).

the web runs as a prod build (localinfra/docker-compose.web-build.yml for compose, the web service's setup for pc), made when the web starts. pnpm e2e and pnpm e2e:up rebuild it by themselves when anything under web/ changed.

you need the localinfra stack, its dev ca in localinfra/certs, and pnpm install here. the stack is either compose or the container-free one in localinfra/pc. E2E_STACK=compose or E2E_STACK=pc picks, otherwise it is whichever is running, otherwise compose when docker or podman is installed. for pc run pnpm e2e:up (the nix app brings go and cargo), it starts the stack in the background, and localinfra/pc/bin/pc down, from the repo root, stops it. service urls come from E2E_*_URL (see harness/config.ts) and default to the localinfra hostnames. the deliberi hop asks deliberi's dev only /xrpc/_ingested route, so deliberi has to run with DELIBERI_DEV=true (both localinfra stacks set it). making accounts needs the pds admin password, read from localinfra/pds.env or E2E_PDS_ADMIN_PASSWORD.

outages #

outages/ holds flows that stop and start stack processes, so they only exist on the pc stack when asked for, because they would break flows running beside them: E2E_OUTAGES=1 pnpm exec playwright test --project=outages. they stop spindle through process-compose's socket and rewind its saved jetstream cursor (harness/processes.ts, E2E_PC_STATE is the stack's state dir, run sets it). a failed flow starts spindle again in its afterEach.

cleanup #

every flow removes its own accounts and repos. pnpm e2e:sweep cleans up what the tests add in case a crash or something occurs.

layout #

run                     checks the stack, rebuilds the web if it changed, starts playwright
up                      brings the stack up, compose or pc
harness/
  flow.ts               what a spec is written with, flow("...").open(...).click(...)
  vocabulary.ts         the things a spec points at, like buttons, pages and records
  shared.ts             steps and checks that more than one spec uses
  run.ts                who acts, which repo, what each step does
  services.ts           asking pds, knot, etc. what they have after a write
  attestations.ts       claiming the attestation the page writes to the pds after a knot write
  cobgit.ts             looking inside the knot's git for what a write left there
  versions.ts           every version the knot has of a record
  stream.ts             watching hydrant's event stream for a write to show up
  firehose.ts           watching the knot and pds for the action and cid of a write
  frames.ts             bounded frame history and waking checks when a frame arrives
  api.ts                writes from node, accounts, repos, tickets, pulls
  git.ts                pushing and cloning over ssh like a real git client
  net.ts                tracing every http request node makes
  tabs.ts               one browser window per account, waiting for a page to go quiet
  signin.ts             signs in, through the login page or with a session made in node
  auth.setup.ts         logs the four seeded accounts in once so flows start signed in
  config.ts             the service urls and the seeded accounts
  global.ts             cleans up what a killed run left, starts the shared browser
  chores.ts             a list of what a run has to cleanup
  record.ts             remembers what each step did, for the report
  lexicons.ts           record types for checking what setup wrote
  reporter.ts           the terminal output
  report/               the html report
specs/                  one file per product area
tools/sweep.spec.ts     deletes leaked accounts, only runs with `pnpm e2e:sweep`
tools/tidy.spec.ts      a stopped worker starts this to finish its cleanup