e2e test

CLAUDE.md

@@ -35,10 +35,50 @@ for technical deep-dives, USECASES.md for expected behaviors.
 
 ## Build and test
 
-No build step. No tests. Verify changes by:
-1. Reading scripts and checking idempotency
-2. Walking through each use case in USECASES.md
-3. Cross-checking docs against scripts
+No build step. Run e2e tests with:
+
+    uvx pytest tests/test_app_e2e.py -v -x
+
+### Prerequisites
+
+- `uv` installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+- CLI tools: `bws`, `jq`, `dig`, `ssh`, `curl`, `git`
+- bws token: set `BWS_ACCESS_TOKEN` env var or save to `~/.config/hantim/bws-token`
+- Vultr API key must allow requests from the machine's IP (check https://my.vultr.com/settings/#settingsapi)
+
+### Test structure
+
+- `tests/conftest.py` -- Fixtures: preflight checks, bws secrets, API helper, cleanup
+- `tests/test_app_e2e.py` -- E2E tests for `tools/app.sh` against real services
+- `tests/test_security_headers.py` -- Verify security headers on live sites
+- `tests/test_default_server.py` -- Verify unknown Host headers are dropped
+- `tests/test_tls.py` -- Verify TLS hardening
+
+### E2E tests (`test_app_e2e.py`)
+
+Tests use `kgfamily.com` as a throwaway test domain. Two phases:
+
+1. **TestAppSubcommands** -- Runs each `app.sh` subcommand individually (dns, repo,
+   files, cert, garage, build, monitor), verifies side effects via API, then cleans up.
+   Does not test `verify` (needs full deploy flow).
+2. **TestAppAll** -- Runs `app.sh all kgfamily.com`, verifies everything including
+   site liveness and git commit, then cleans up (including reverting the commit+push).
+
+Cleanup is done directly via APIs (Vultr, Gitea, Garage, UptimeRobot) + local file
+deletion. Does NOT use `remove-app.sh` to avoid coupling. Runs before and after each
+phase to handle leftovers from crashed runs.
+
+### Known issue
+
+- Vultr API keys can be IP-restricted. If `test_dns` fails with HTTP 401, add the
+  machine's IP to the Vultr API access control list.
+
+### Other tests
+
+The security/TLS/default-server tests run against live sites and are triggered
+automatically after nginx deploy. They can also be run locally:
+
+    uvx pytest tests/ -v --ignore=tests/test_app_e2e.py
 
 ## Commit style