Automated Testing
Learn what TanStarter tests and how to run its test suites
TanStarter uses Vitest for logic and service boundaries, Playwright for browser flows, and separate real payment sandbox suites for Stripe, Creem, and Waffo. Run the following commands from your application repository.
Test Coverage
| Test type | What it verifies | Command |
|---|---|---|
| Unit | Auth, payment providers, webhooks, permissions, database migrations, content links, and AI response parsing | pnpm test |
| Local E2E | English/Chinese pages, registration/login, admin access, profile/password updates, API keys, files, router boundaries, and Clef interactions | pnpm e2e |
| Worker smoke | Local production build: SSR, hydration, auth redirects, health API, and test-helper isolation | pnpm e2e:production |
| Payment sandbox | Hosted checkout, real webhooks, and local D1 payment state | pnpm e2e:stripe / creem / waffo |
Unit tests mock external services; local E2E uses real local authentication, D1, and R2. Verify email delivery, Google OAuth, and live AI output separately.
Run Tests
Install dependencies and browsers once:
pnpm install
pnpm e2e:installAfter routine changes, run code checks and browser tests:
pnpm check # Read-only Biome check + all unit tests
pnpm e2eBefore an upgrade or release, run the full local validation:
pnpm verify:upgrade # check β build β e2e β e2e:productionTo focus on relevant tests:
pnpm test tests/unit/payment
pnpm test:watch
pnpm e2e -- tests/e2e/specs/auth.spec.ts
pnpm e2e:uiBrowser tests start their own server, initialize isolated state, and apply migrations. Keep the test port free. e2e:production tests a locally built Worker without deploying; verify:upgrade excludes payment sandbox suites.
Payment Automation
What We Test
Payment unit tests cover checkout parameters, signatures, event handling, out-of-order and duplicate delivery, retries, refunds, and order ownership. They protect against treating an older order or another user's payment as the current checkout.
Real sandbox tests complete hosted checkout, wait for provider webhooks, and verify local D1 records:
| Provider | Sandbox coverage |
|---|---|
| Stripe | Monthly/yearly/Lifetime, zero-cost orders, declined payments, portal plan changes, cancellation, and full refunds |
| Creem | Monthly/yearly/Lifetime, declined payments, and scheduled cancellation |
| Waffo | Monthly/yearly/Lifetime, and payment events that do not duplicate or overwrite subscription state |
Stripe confirms payment through invoice.paid; Waffo separates payment events from subscription lifecycle events. Unit tests cover renewal and selected failure paths; sandbox suites do not cover every provider lifecycle.
How to Run
Put the selected provider's test credentials and price/product IDs in .env.e2e, or export them in the shell. All three suites start an isolated Worker and D1 automatically.
| Provider | Default port | Additional setup |
|---|---|---|
| Stripe | 3019 | Install Stripe CLI; the runner starts the listener and injects its temporary webhook secret |
| Creem | 3021 | Start an HTTPS tunnel, register a Test Mode webhook, and configure its signing secret |
| Waffo | 3018 | Start an HTTPS tunnel and register a Test Mode webhook that preserves signature headers |
pnpm e2e:stripe
pnpm e2e:creem
pnpm e2e:waffo
# Run one scenario
pnpm e2e:stripe -- --grep "monthly subscription"Use credentials and products from the same sandbox account. Payment runners exclude the developer's .dev.vars; Creem/Waffo runners do not create tunnels or register webhooks. See tests/e2e/<provider>/README.md in your project for detailed setup.
Maintenance and Troubleshooting
Tests live in tests/unit/ and tests/e2e/; acceptance journeys are recorded in tests/e2e/TEST-CATALOG.md. Update relevant tests when behavior changes. Assert requests, permissions, and persisted outcomes rather than exact copy or styling.
Inspect terminal output and test-results/ on failure. For pending payments, check webhook delivery, signatures, and tunnel connectivity. Open retained traces with pnpm exec playwright show-trace <trace.zip>.
Next Steps
Last updated on