Billing regression coverage

How the dashboard's Billing surface is regression-tested, what each layer proves, and what is deliberately out of scope. Written for the Billing regression infrastructure task (t_cf42b93d); the defect-specific reproduction work builds on this.

Baseline (verified 2026-11-03, commit 8cf06cd)

node --test apps/ui/tests/billing.test.mjs apps/ui/tests/paths.test.mjs

→ 17 pass / 0 fail / 0 skipped, exit 0 (node v26.7.0, ~108 ms). These cover pure presentation/URL logic in lib/billing.ts only — no page renders, no network, no Paddle runtime. A green run here never proves checkout or the rendered page work.

Layers

Layer	File	Provider	Proves
Pure logic	tests/billing.test.mjs, tests/paths.test.mjs	both (unit)	Redirect-host validation, _ptxn parsing, entitlement/limit formatting, denial mapping, deep-link login.
Plan picker (in-place upgrade sheet)	tests/upgrade-sheet.test.mjs	provider: "stripe" mock	Picker opens from every route, focus trap, catalog retry, non-owner gating, updated:true in-place notice. Does not verify Paddle runtime behavior — the summary is mocked with provider='stripe', so nothing here loads Paddle.js or follows a Paddle link.
Billing routes (provider-mocked)	tests/billing-routes.test.mjs	provider: "paddle" mock	The real /billing and /billing/checkout pages in a real browser: plan/status/stat rendering, entitlement table values, unconfigured + non-owner gating, checkout redirect to <origin>/billing/checkout?_ptxn=…, Paddle.js load + Initialize/Checkout.open args, completed/closed returns, updated:true, foreign-host refusal, missing-config errors, portal navigation to the provider host.
Live stack	tests/e2e-live.mjs ("billing" describe)	unconfigured (no provider)	The authenticated live page against the real API/DB (Business period seeded via enableSchedules()): plan card, account status, four credit metrics, all five entitlement rows with their enforced values. No payment flow — Stripe/Paddle are deliberately out of scope in the live stack.

Reusable fixtures — tests/billing-fixtures.mjs

Plain data factories for page.route() mocking, no network I/O:

• billingSummary({...}) and the named states freeSummary, paidSummary, noPeriodSummary, unconfiguredSummary, canceledSummary — summary shapes per apps/api-rust/src/billing/mod.rs::summary / billing/openapi.rs (account, period, configured, live_mode, provider, paddle_js).
• periodFor(planId) / entitlementsFor(planId) — period + capability envelope per plan; remaining derived as allowance - used - reserved like the server. The free plan is not in billing/plans.json (catalog is paid tiers only) — its billing_plans row values are inlined in the fixture.
• catalogPlans({available}) — the checked-in billing/plans.json plus the server-added available flag, wrapped as {plans, currency:"usd", interval:"month"}.
• paddleCheckoutUrl(origin) ({url: "<origin>/billing/checkout?_ptxn=txn_…"}), UPDATED_IN_PLACE ({updated:true}), PORTAL_RESPONSE ({url} on the provider's own https host).
• PADDLE_STUB_JS — served in place of https://cdn.paddle.com/paddle/v2/paddle.js; records Environment.set / Initialize / Checkout.open calls and exposes window.__paddle.completed() / .closed() to fire lifecycle events, so the real lib/paddle.ts loader runs against a deterministic provider.
• assertSummaryContract / assertCatalogContract — key-set + derived-value pins so a server contract change breaks every consumer loudly.

tests/browser-sweep.mjs::serveDashboard gained an opt-in { https: true } mode (throwaway openssl self-signed cert). The billing controller refuses any checkout/portal URL that is not https: on a trusted provider host, so the redirect paths can only be exercised over a genuine https origin. Callers must accept the certificate (ignoreHTTPSErrors). The default http mode and every existing caller are unchanged.

Known gaps (deliberate, for the later defect regression)

1. No live provider. Nothing here contacts Paddle/Stripe; checkout, webhook confirmation (subscription.updated → plan grant) and portal are provider-mocked. A real charge/subscription test needs sandbox credentials and separate authorization.
2. upgrade-sheet.test.mjs is Stripe-only. Its updated:true and gating coverage does not exercise summary.provider='paddle'; the Paddle runtime half lives in billing-routes.test.mjs, which also exercises the shared upgrade picker under Paddle for missing-email remediation.
3. The live-stack billing test is render-only. It seeds a Business period directly in SQL and asserts the rendered page; it cannot see checkout, portal, webhook reconciliation, or updated:true against the real API, because the live stack runs with no payment provider configured.
4. Webhook → grant path. The Paddle webhook reconciliation (subscription.updated granting the paid period) is covered by Rust tests (apps/api-rust/src/billing/{upgrade_tests,webhook_tests}.rs), not by any UI-level test; the UI side of "plan updates after the provider confirms" (10 s refetch) is only implied by the updated:true refetch test.
5. Deployed-revision skew. Production CSP/nginx config (deploy/nginx/scrapingcow-https.conf, route-specific CSP for /billing/checkout) is not exercised by any local fixture; a production Paddle failure that smells like a blocked CDN script must be checked against the served revision, not these tests.

Confirmed missing-email remediation (t_4287e2c2)

The upstream live investigation reproduced POST /platform/v1/billing/checkout returning 400 for a username-only owner with email = NULL and no provider customer. The page displayed the error but offered no path to fix it. This is an actionable-error UX fix, not proof of the reporter's unspecified payment failure or a change to payment-provider behavior. The reported portal 400 ("Subscribe before opening the billing portal") is a separate expected no-customer state, not an email-verification failure.

Source trace: billing/mod.rs::checkout reads dashboard_session_profile.email and calls provider.create_customer only when customer_id is absent; paddle.rs::create_customer refuses None. Migration 0042's session profile returns email and email_verified separately. Despite the 400's wording ("verified billing email"), the current API checks address presence, not the verification flag. This UI change deliberately does not add a verification policy or change the backend contract.

useBilling exposes the requirement only for owner + configured Paddle + no customer + no linked email. Shared BillingPlans explains it, links to /settings/security, and disables checkout until an email is linked. The native link also leaves any open upgrade sheet so it cannot hide the form. Existing customers (including no-active-period subscriptions), linked emails, Stripe, non-owners and unconfigured deployments keep their existing behavior. Strict redirect validation, summary.provider, updated:true, API owner permissions and production configuration are untouched.

Six browser regressions extend billing-routes.test.mjs. They drive the real Billing/upgrade/settings routes, submit the real request/confirm forms through mocked auth endpoints, patch the session identity, return to Billing, and resume checkout. Adjacent cases cover absent/existing customers with no active period, paid in-place updates and portal navigation without a linked email, Stripe, linked-but-unverified email, member/viewer roles, disabled billing and summary errors. No provider or email service is contacted; API owner rejection remains a Rust/API review responsibility, not a claim from these UI mocks.

Red/green (Node v26.7.0, Chromium, BROWSER_SWEEP_REQUIRED=1):

# Build each isolated checkout's actual source (pnpm is not on this worker's PATH):
(cd apps/ui && node node_modules/typescript/bin/tsc --noEmit && node node_modules/vite/bin/vite.js build)
# Run the same final regression file copied into the unfixed e27e486 baseline:
BROWSER_SWEEP_REQUIRED=1 node --test --test-name-pattern='missing billing email:' apps/ui/tests/billing-routes.test.mjs

Unfixed e27e486: exit 1, 3 fail / 3 pass / 0 skipped. Missing remediation fails on the free/new-account page, absent-customer/no-period page, and shared upgrade picker; adjacent unaffected cases pass.

BROWSER_SWEEP_REQUIRED=1 node --test apps/ui/tests/billing.test.mjs apps/ui/tests/paths.test.mjs apps/ui/tests/billing-routes.test.mjs apps/ui/tests/upgrade-sheet.test.mjs

Fixed source: exit 0, 64 pass / 0 fail / 0 skipped; dashboard TypeScript check and Vite build also pass. Full UI glob, live-stack/API billing suites and any deployed/sandbox payment acceptance remain with the downstream QA card. This worker makes no deployment, real payment, webhook-delivery or sandbox-to-live configuration claim.

Running

pnpm --filter @scrapingcow/ui build        # dashboard bundle (needed by the browser layers)
node --test apps/ui/tests/*.test.mjs       # pure logic + provider-mocked routes + picker
DATABASE_URL=… SCRAPINGCOW_SECRET_KEY=… node --test apps/ui/tests/e2e-live.mjs   # live stack (see file header)

The browser layers skip (or hard-fail with BROWSER_SWEEP_REQUIRED=1) when the build, Playwright or Chrome is missing — same policy as the existing sweep.