Skip to Content
Slloy Docs
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 CommandDirectory & RunnerBuild / Runtime PrerequisitesWhat It Verifies
npm testtests/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:postgrestests/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:browsertests/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:workertests/e2e/full-flow.spec.ts (Playwright + workerd)npm run build:web && npm run build:worker (dist/ and .worker-dist/) + local PostgresFull end-to-end flow running inside real Cloudflare workerd with isolated ports and local state directories.
npm run test:integrationFull integration suitenpm run db:up + TEST_POSTGRES_DATABASE=slloy_test_fullRuns 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 ORM 0.45.4 / Drizzle Kit 0.31.10).
  • Explicit Incremental SQL Migrations:
    • Schema lives in server/src/db/postgres/schema.ts.
    • npm run db:generate generates reviewable incremental SQL files under server/drizzle/, applied explicitly via migrate-postgres --apply (never use drizzle-kit push, which can overwrite data).
  • Session Timezone & Financial Locking:
    • Timestamps use timestamptz with the database session timezone set to Asia/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).

Local Container & Millisecond Template Cloning (tests/support/postgres-database.ts)

  1. 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 with 0700 directory and 0600 file permissions (password holds the DB password; app.env holds local random JWT secrets with payments and channels disabled).
  2. Safety Guards on TEST_POSTGRES_DATABASE:
    • HOST, PORT, USER, and PASSWORD automatically read from the current worktree's .docker-postgres/app.env (never hardcode port 15432).
    • HOST only accepts loopback addresses (127.0.0.1 / localhost), refusing to run destructive test teardowns against remote hosts.
    • TEST_POSTGRES_DATABASE must be explicitly provided, must start with slloy_test_, and be < 40 characters:
      TEST_POSTGRES_DATABASE=slloy_test_full npm run test:integration
  3. Template Database Cloning:
    • At the beginning of a test:postgres session, 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.

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

On this page