Test Convt Web

Test the convt website

apps/web is a TanStack Start app built with Vite and the Cloudflare plugin, deployed with Wrangler as the convt-web Worker. apps/billing is the convt-billing Worker: the Polar webhook route, the billing crons, and the BillingRpc entrypoint the site calls through its BILLING service binding. It holds every billing secret and the license signing key; the site holds none. The landing page is static. The account pages (/sign-in, /dashboard, /dashboard/licenses, /dashboard/billing, /dashboard/api, /account) use Better Auth and read Postgres through the HYPERDRIVE binding. Locally everything runs on this machine: a Postgres and a Mailpit container per checkout, an OAuth mock that stands in for GitHub and Google, and a billing mock (tools/billing-mock) that speaks the parts of Polar's API and Resend's /emails that convt-billing calls, serves Polar-like checkout and portal pages, and signs webhooks with Polar's real scheme. No real email, OAuth app, payment account or database is ever used, and convt-billing signs keys with the local dev key in .convt-dev/license.key.

Doctor

docker info --format '{{.ServerVersion}}'     # Docker must run; no sudo needed
bash scripts/db.sh status                      # this checkout's containers and ports
ss -ltnp 'sport = :3000'                       # who owns the default web port

scripts/db.sh names its containers convt-pg-<hash> and convt-mail-<hash> after a hash of the checkout path and labels them convt.checkout=<path>, so other checkouts and other projects' Postgres containers are never touched. Ports are random on 127.0.0.1; .convt-dev/services.env (mode 0600, gitignored) records them with generated passwords and BETTER_AUTH_SECRET.

Launch

work=$(mktemp -d /tmp/convt-web.XXXXXX)
setsid bun run dev:web >"$work/dev.log" 2>&1 </dev/null &
sleep 1; ps -o pgid= -p $! | tr -d ' ' >"$work/pgid"
for _ in $(seq 90); do grep -q 'dev-web: http' "$work/dev.log" && break; sleep 1; done
origin=$(grep -o 'dev-web: http://localhost:[0-9]*' "$work/dev.log" | cut -d' ' -f2)
curl -fsS "$origin/api/auth/ok"                # {"ok":true}
bun run db:seed                                # fixture accounts; safe to repeat

bun run dev:web runs scripts/dev-web.sh: db.sh up, migrations, the OAuth mock on OAUTH_MOCK_PORT, the billing mock on BILLING_MOCK_PORT (delivering webhooks to the site's /webhooks/polar), apps/web/.dev.vars and apps/billing/.dev.vars from services.env, then Vite on 3000 or the next free port with BETTER_AUTH_URL set to match. convt-billing runs inside Vite as an auxiliary Worker; outside production the site forwards /webhooks/* and /__billing/* to it, because an auxiliary Worker has no port of its own. After seeding, mirror the fixtures into the billing mock with bun tools/billing-mock/src/preload.ts (it is in-memory, so repeat it after every restart). Readiness is /api/auth/ok returning 200. Server-side errors appear in dev.log, not the browser console. setsid puts Vite and the mock in one process group so cleanup can stop exactly those.

For a production-like check, build and serve the Worker with Wrangler. Pass the database through the Hyperdrive variable and point BETTER_AUTH_URL at Wrangler's port:

set -a; . .convt-dev/services.env; set +a
bun run build
cd apps/web && CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE=$DATABASE_URL \
  setsid bunx wrangler dev --port 8788 --ip 127.0.0.1 --var BETTER_AUTH_URL:http://localhost:8788 &

It reads the other values from .dev.vars, which the build copies into dist/server. Never run bun run deploy or wrangler deploy without the user's explicit authorization.

Sign in as a fixture

All fixtures are on the reserved .test domain and exist only in local databases:

trial@ has no key (a trial is not paid coverage); a database seeded before P7 keeps its old trial key, because licenses are never deleted. Every subscription fixture has payment coverage and a billing_customers row with mock ids.

Sign in at /sign-in with the email, then read the code from Mailpit (its web UI is $MAILPIT_URL):

curl -fsS "$MAILPIT_URL/api/v1/search?query=to:pro@convt.test" \
  | python3 -c 'import json,re,sys; print(re.search(r"\d{6}", json.load(sys.stdin)["messages"][0]["Subject"]).group())'

Each address may receive 3 codes per 15 minutes and each IP 10 per hour; every local request comes from the same IP. To clear the limits in this checkout's own database: bash scripts/db.sh psql owner -c 'delete from otp_send_limits; delete from rate_limits'.

GitHub and Google buttons go to the OAuth mock's authorize page, which lists its identities: google-gmail and google-workspace (verified addresses), google-thirdparty and google-unverified (must confirm by code), github-verified, github-public-differs, github-no-email, github-pro (signs in to pro@convt.test), and error (access denied). Append &identity=<name> to the authorize URL to skip the page and &email=<address> to sign up with another address.

Drive and evidence

Use headless agent-browser for UI verification, with a named session and its own persistent profile. Put both --session and --profile on every invocation. Never use a personal browser profile. UI work includes opening the real page and inspecting desktop and mobile screenshots in both themes.

The repeatable checks are scripts in apps/web/e2e, each printing PASS or FAIL lines and saving screenshots:

cd apps/web
E2E_SESSION=convt-web E2E_SHOTS=$work/shots bash e2e/sign-in.sh   # code, emailed link, OAuth identities, verify-email
E2E_SESSION=convt-web E2E_SHOTS=$work/shots bash e2e/fixtures.sh  # every fixture, 5 pages, 1280 and 390 px, light and dark
E2E_SESSION=convt-web E2E_SHOTS=$work/shots bash e2e/account.sh   # activate, copy key, rename, change email, connect, sign out
E2E_SESSION=convt-web E2E_SHOTS=$work/shots bash e2e/billing.sh   # checkout, keys, trial, switch, refund, API, emails, deletion

They read the site origin from apps/web/.dev.vars; set E2E_URL to test Wrangler instead. billing.sh drives the mock's hosted checkout and its /admin/* endpoints (end a trial, renew, fail a card, refund, change settings), runs crons through $E2E_URL/__billing/scheduled?cron=..., and screenshots each billing screen and the four emails (Mailpit's /view/<id>.html) in both themes. Run it once per fresh dev:web: it changes mock settings and deletes an account. account.sh calls a source module directly to prove getLicenseKey refuses another user's license, which only works under Vite. A layout change needs desktop and 390 px screenshots in both themes; look at each one with the Read tool.

Activate opens convt://activate?key=<token> through a temporary link. account.sh stubs HTMLAnchorElement.prototype.click to check the URL, because Chrome lets no page script stub location. Opening the link in the real desktop app is a GUI check (see test-convt-desktop): register the handler with integrations/linux/install.py and use CONVT_LICENSE_STORE=file with HOME and the XDG directories in a mktemp directory. Seeded keys are signed with .convt-dev/license.key, whose public half local builds embed.

Desktop sign-in

/device is the page the desktop app opens to sign in (P8). It needs a signed-in, verified session, so a signed-out visit goes through /sign-in and comes back. Approve stores a five-minute one-time code in verifications and opens convt://auth?state=...&code=...; Cancel opens ...&error=access_denied. The app then calls POST /api/device/token (code and verifier), POST /api/device/license (bearer device token; returns the Pro key from convt-billing's currentProKey) and POST /api/device/sign-out. These routes use no cookies and skip the Origin check; the logic and limits are in src/server/device-auth.ts. test/integration/device.test.ts covers the flow, one-use codes, revocation, cross-account isolation and rate limits. A full run with the real app is in test-convt-desktop, "Sign-in and renewal". Signed-in devices appear under Macs on the dashboard, where Sign out revokes their token.