restic-manager/docs/e2e.md

End-to-end test harness

The e2e harness stands up the full production-shaped stack (server + agent + rest-server) in Docker Compose and drives it through Playwright. CI runs it on every PR; operators can run it locally too.

Files

e2e/
├── compose.e2e.yml         compose stack: server + rest-server + agent
├── Dockerfile.agent        Linux container for the agent (alpine + restic)
├── agent-entrypoint.sh     decides between announce / token-enrol / run
└── playwright/
    ├── package.json
    ├── playwright.config.ts
    └── tests/
        ├── lib/server.ts   bootstrap, login, accept, poll helpers
        └── smoke.spec.ts   happy-path: enrol → backup → succeeded

Local run

Prerequisites: Docker + Docker Compose, and npx for Playwright.

# 1. Build + bring up the stack (server, rest-server, source data).
docker compose -f e2e/compose.e2e.yml up --build -d server rest-server source-fixture

# 2. Wait for the server, then scrape the bootstrap token from the log.
until curl -fsS http://127.0.0.1:8080/api/version >/dev/null; do sleep 1; done
RM_BOOTSTRAP_TOKEN=$(docker compose -f e2e/compose.e2e.yml logs server \
    | grep -Eo '[a-zA-Z0-9_-]{40,}' | head -1)
export RM_BOOTSTRAP_TOKEN

# 3. Start the agent (it announces against the running server).
docker compose -f e2e/compose.e2e.yml up -d agent

# 4. Install + run Playwright.
cd e2e/playwright
npm install
npx playwright install --with-deps chromium
npx playwright test

When the test passes you'll see:

Running 2 tests using 1 worker
  ✓  smoke: enrol-via-announce → backup › happy path completes in under a minute (47s)
  ✓  smoke: scrape /metrics › metrics endpoint exposes the host gauge (180ms)

  2 passed (47.5s)

Tear-down:

docker compose -f e2e/compose.e2e.yml down -v

-v removes the named volumes too — important between runs because the rest-server volume holds an initialised repo and the agent-config volume holds a stale bearer.

What the test exercises

1. Bootstrap. Posts the admin-creation request to /api/bootstrap with the token scraped from the server log.
2. Login (UI). Drives the login form via Playwright; verifies the dashboard loads with a session cookie set.
3. Pending host appears. Polls the dashboard for the inline accept form generated by the announcing agent; reads the pending-id out of its action URL.
4. Accept. POSTs /api/pending-hosts/{id}/accept with the rest-server URL + repo password. The server mints a Host row
   • bearer + AEAD-encrypted creds and pushes the bearer down the still-open pending WebSocket.
5. Online + auto-init. Polls /api/hosts until the new host is status=online. Auto-init runs as part of this — the first dispatched job after creds save is restic init.
6. Run backup. Submits the host detail page's Run now form; expects HX-Redirect to the live job page.
7. Verify. Polls /api/hosts until the host's last_backup_status flips to succeeded.
8. Metrics. Scrapes /metrics and asserts the server-gauge + build-info lines are present (the compose stack opens the endpoint via RM_METRICS_TRUSTED_CIDR=0.0.0.0/0).

CI workflow

.gitea/workflows/e2e.yml runs the suite on every PR into main. On failure it dumps the last 200 lines of each container log as a workflow annotation and uploads the Playwright HTML report as an artefact.

When tests fail

• Pending host never appears. Agent container probably couldn't reach the server. Check docker compose logs agent for connection errors and docker compose logs server for any 4xx on /api/agents/announce.
• Backup hangs in running. The agent shells out to restic; check the live job log at http://127.0.0.1:8080/jobs/<id> (still up after a failed test as long as you didn't down -v).
• RM_BOOTSTRAP_TOKEN not set. The server log scrape matched the wrong line or the token regex is too tight. The server prints the token on a line starting with (four spaces) inside a banner; widen the regex if your server log format changes.

Adding new tests

The harness is intentionally flat — one *.spec.ts per scenario. Reuse the helpers in lib/server.ts and avoid duplicating bootstrap / login boilerplate. Heavy fixtures (custom users, OIDC IdP) belong in their own compose override file rather than complicating compose.e2e.yml.