# e2e

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.

```sh
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 and https 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
```