Architecture, Design & Testing
Testing Strategy, Postgres Template Cloning & Worker E2E
Multi-tier test suite (server unit, design-tokens/i18n tools, millisecond Postgres template DB cloning, Playwright browser tests, and workerd E2E).
Slloy uses a multi-layered test architecture (tests/README.md and server/POSTGRES.md) covering fast in-memory server tests, static build/token audits, real PostgreSQL 17 integration tests, Playwright browser tests against dist/, and full workerd E2E tests.
1. Test Tiers & Build Prerequisites
| Test Command | Directory & Runner | Build / Runtime Prerequisites | What It Verifies |
|---|---|---|---|
npm test | tests/server/*.test.ts & tests/tools/*.test.ts (Vitest) | None (no dev server or local database needed) | In-memory repository logic, margin guards, Stripe webhooks/disputes/3DS, fail reasons, legacy redirects, design tokens (design-tokens.test.ts), i18n catalog completeness (i18n-catalog.test.ts), and internal model links (model-links.test.ts). |
npm run test:postgres | tests/postgres/*.test.ts (Vitest) | npm run db:up + TEST_POSTGRES_DATABASE=slloy_test_* (dispute-consistency.test.ts also requires npm run build:server) | Real PostgreSQL 17 transactions, row-level locks, financial settlement idempotency, dispute consistency, and Drizzle migrations. |
npm run test:browser | tests/browser/*.spec.ts (Playwright) | npm run build:web (dist/ must be current) + Chromium installed (npx playwright install chromium) | Pre-rendered public pages, dark/monochrome/RTL layouts, workbench interactions, /admin SPA flows, pricing promo display, and table scroll across viewports. |
npm run test:e2e / test:worker | tests/e2e/full-flow.spec.ts (Playwright + workerd) | npm run build:web && npm run build:worker (dist/ and .worker-dist/) + local Postgres | Full end-to-end flow running inside real Cloudflare workerd with isolated ports and local state directories. |
npm run test:integration | Full integration suite | npm run db:up + TEST_POSTGRES_DATABASE=slloy_test_full | Runs all PostgreSQL integration and compiled server boundary tests. |
2. PostgreSQL 17 Architecture & Millisecond Template DB Cloning
Drizzle ORM & Schema Boundaries (server/POSTGRES.md)
- Single Database Implementation: Production, staging, and local development all run PostgreSQL 17 via
server/src/db/postgres.ts(pinned to stable Drizzle ORM0.45.4/ Drizzle Kit0.31.10). - Explicit Incremental SQL Migrations:
- Schema lives in
server/src/db/postgres/schema.ts. npm run db:generategenerates reviewable incremental SQL files underserver/drizzle/, applied explicitly viamigrate-postgres --apply(never usedrizzle-kit push, which can overwrite data).
- Schema lives in
- Session Timezone & Financial Locking:
- Timestamps use
timestamptzwith the database session timezone set toAsia/Shanghai, preserving natural-day semantics for daily check-in bonuses and daily video spending caps. - All financial mutations (credit bucket deductions, order settlement, dispute revocations, generation refunds) execute inside single-connection transactions with explicit PostgreSQL row locks (
FOR UPDATE).
- Timestamps use
Local Container & Millisecond Template Cloning (tests/support/postgres-database.ts)
- Start Local PostgreSQL 17:
npm run db:up # Reuses shared container slloy-postgres-local; writes port & credentials to .docker-postgres/.docker-postgres/is git-ignored with0700directory and0600file permissions (passwordholds the DB password;app.envholds local random JWT secrets with payments and channels disabled). - Safety Guards on
TEST_POSTGRES_DATABASE:HOST,PORT,USER, andPASSWORDautomatically read from the current worktree's.docker-postgres/app.env(never hardcode port15432).HOSTonly accepts loopback addresses (127.0.0.1/localhost), refusing to run destructive test teardowns against remote hosts.TEST_POSTGRES_DATABASEmust be explicitly provided, must start withslloy_test_, and be< 40characters:TEST_POSTGRES_DATABASE=slloy_test_full npm run test:integration
- Template Database Cloning:
- At the beginning of a
test:postgressession, the test harness creates and migrates a single template database once. - Each test file clones its own isolated database (
CREATE DATABASE slloy_test_<rand> TEMPLATE ...) in milliseconds and drops only the databases it created on teardown.
- At the beginning of a
3. Running & Filtering Specific Tests
# Run a single server unit test file
npm test -- tests/server/canonical-path.test.ts
# Run a single PostgreSQL integration test file or test name pattern
TEST_POSTGRES_DATABASE=slloy_test_dev npm run test:postgres -- tests/postgres/financial-settlement.test.ts
TEST_POSTGRES_DATABASE=slloy_test_dev npm run test:postgres -- -t "只退款一次"
# Run a single Playwright browser spec or grep pattern
npm run test:browser -- payment.spec.ts
npm run test:browser -- --grep "撤回"
# Debug Playwright tests with UI or inspect HTML report / trace
npx playwright test --ui
npx playwright show-report playwright-report/browser
npx playwright show-trace <failure-dir>/trace.zip