# Testing

The explorer has four test tiers. Run them in order of fidelity when
debugging a regression.

## 1. Unit / package tests

Fast. Run on every PR.

```bash
# Backend
cd backend && go test ./...

# Frontend
cd frontend && npm test          # lint + type-check
cd frontend && npm run test:unit # vitest
```

## 2. Static analysis

Blocking on CI since PR #5 (`chore(ci): align Go to 1.23.x, add
staticcheck/govulncheck/gitleaks gates`).

```bash
cd backend && staticcheck ./...
cd backend && govulncheck ./...
git diff master... | gitleaks protect --staged --config ../.gitleaks.toml
```

## 3. Production-targeting Playwright

Runs against `https://explorer.d-bis.org` (or the URL in `EXPLORER_URL`)
and only checks public routes. Useful as a production canary; wired
into the `test-e2e` Make target.

```bash
EXPLORER_URL=https://explorer.d-bis.org make test-e2e
```

## 4. Full-stack Playwright (`make e2e-full`)

Spins up the entire stack locally — `postgres`, `elasticsearch`,
`redis` via docker-compose, plus a local build of `backend/api/rest`
and `frontend` — then runs the full-stack Playwright spec against it.

```bash
make e2e-full
```

What it does, in order:

1. `docker compose -p explorer-e2e up -d postgres elasticsearch redis`
2. Wait for Postgres readiness.
3. Run `go run database/migrations/migrate.go` to apply schema +
   seeds (including `0016_jwt_revocations` from PR #8).
4. `go run ./backend/api/rest` on port `8080`.
5. `npm ci && npm run build && npm run start` on port `3000`.
6. `npx playwright test scripts/e2e-full-stack.spec.ts`.
7. Tear everything down (unless `E2E_KEEP_STACK=1`).

Screenshots of every route are written to
`test-results/screenshots/<route>.png`.

### Env vars

| Var | Default | Purpose |
|-----|---------|---------|
| `EXPLORER_URL` | `http://localhost:3000` | Frontend base URL for the spec |
| `EXPLORER_API_URL` | `http://localhost:8080` | Backend base URL |
| `JWT_SECRET` | generated per-run | Required by backend fail-fast check (PR #3) |
| `CSP_HEADER` | dev-safe default | Same |
| `E2E_KEEP_STACK` | `0` | If `1`, leave the stack up after the run |
| `E2E_SKIP_DOCKER` | `0` | If `1`, assume docker services already running |
| `E2E_SCREENSHOT_DIR` | `test-results/screenshots` | Where to write PNGs |

### CI integration

`.github/workflows/e2e-full.yml` runs `make e2e-full` on:

* **Manual** trigger (`workflow_dispatch`).
* **PRs labelled `run-e2e-full`** — apply the label when a change
  warrants full-stack validation (migrations, auth, routing changes).
* **Nightly** at 04:00 UTC.

Screenshots and the Playwright HTML report are uploaded as build
artefacts.