Testing

On This Page

The Test PyramidUnit, integration, live Stripe, and E2E: what each touches and which command to run.Unit TestsCo-located Vitest specs, jsdom vs node, and per-package coverage gates.Integration TestsReal Postgres and Prisma, Moto-mocked S3, and the integration harness.Live Stripe TestsOpt-in suite against Stripe test mode, gated by RUN_STRIPE_LIVE.End-to-End TestsPlaywright with Chromium, seeded users, and the webServer config.Parallelization And Worker FixturesWorker count, seeded users, and cached storageState per worker.The Test EnvironmentThe deterministic .env.test escapes and why each one is enabled.Mocking Patternsvi.hoisted plus vi.mock with importActual for cross-package boundaries.CI PipelineWhich jobs run on a PR, and where to grab failure traces.Adding A TestDrop in a unit, integration, or E2E spec the right way.

The Test Pyramid

Pick the layer that matches what you need to prove. Each layer has its own command and file pattern.

Unit and coverage run on every web-touching PR. Integration and E2E do too. Stripe live stays opt-in (see CI Pipeline).

Unit Tests

Put a *.test.ts or *.test.tsx next to the file under test. Vitest configs live in apps/web/vitest.config.ts and eight packages/*/vitest.config.ts files. apps/web and packages/storage use jsdom; the rest use node.

Coverage thresholds come from defaultCoverageThresholds in @syntaxkit/shared/testing. Every package spreads the same object:

coverage: {
  thresholds: {
    lines: 90,
    statements: 90,
    functions: 90,
    branches: 85,
  },
},

CI fails if any package slips below those numbers.

Integration Tests

These hit real Postgres and Prisma. S3 calls go to a Moto mock. The *.integration.test.ts suffix is excluded from the unit include glob, so pnpm test:run skips them. Opt in with pnpm test:integration.

The harness in packages/api/test/integration.ts exposes createIntegrationHarness() with ensureStorageBucket, cleanup, and getStoredObject:

import { createIntegrationHarness } from "../../test/integration";

const harness = createIntegrationHarness();

beforeEach(async () => {
  await harness.ensureStorageBucket();
  await harness.cleanup();
});

afterEach(async () => {
  await harness.cleanup();
});

Live Stripe Tests

Use this when unit mocks might drift from real Stripe test-mode behavior. Files use *.live.test.ts or *.live.integration.test.ts. Suites call describe.skip unless RUN_STRIPE_LIVE=1 and real test-mode keys are set, so a normal pnpm test:run never hits Stripe.

RUN_STRIPE_LIVE=1 pnpm test:stripe

The full suite runs from .github/workflows/stripe-live.yml on workflow_dispatch only. A lighter pnpm billing:check-prices job runs on pushes to main to catch catalog drift. Neither gates every PR.

End-to-End Tests

Playwright drives Chromium against the real app. Specs live in apps/web/e2e/ and cover marketing, auth, onboarding, dashboard, organization settings, personal settings, billing, two-factor, and admin.

Playwright starts the server itself via webServer in apps/web/playwright.config.ts:

webServer: {
  command: `npx dotenvx run --overload -f .env.test -- next start --port ${TEST_PORT}`,
  env: { NODE_ENV: "test", SYNTAXKIT_E2E: "true" },
  url: TEST_BASE_URL,
  reuseExistingServer: !process.env.CI,
  timeout: 30_000,
},

dotenvx loads the escapes from apps/web/.env.test (DISABLE_ABUSE_PROTECTION, DISABLE_CAPTCHA_FOR_TESTS, empty UPSTASH_*). See The Test Environment. Auth specs in apps/web/e2e/auth.spec.ts exercise the same flows as Authentication, so login, signup, password reset, and 2FA re-verify in a real browser.

Parallelization And Worker Fixtures

Playwright uses four workers locally and two in GitHub Actions. Authenticated specs avoid shared state by giving each worker its own seeded user.

The single source of truth is @syntaxkit/shared/testing:

Change the count or emails in @syntaxkit/shared/testing. Seed, Playwright workers, and helpers stay aligned.

The fixture in apps/web/e2e/helpers/fixtures.ts caches sign-in once per worker. The first spec signs in and writes storageState; later specs in that worker reuse the cookie file:

workerStorageState: [
  async ({ browser }, apply) => {
    const id = test.info().parallelIndex;
    const fileName = path.resolve(
      test.info().project.outputDir,
      `.auth/${id}.json`
    );

    if (fs.existsSync(fileName)) {
      await apply(fileName);
      return;
    }

    const user = getWorkerUser(id);
    const page = await browser.newPage({ storageState: undefined });
    // ...sign in, then:
    await page.context().storageState({ path: fileName });
    await apply(fileName);
  },
  { scope: "worker", timeout: 120_000 },
],

Signup specs create new users instead of reusing seeded ones. uniqueSignupEmail() builds a pid + Date.now() + counter address so concurrent workers never collide.

The Test Environment

Copy apps/web/.env.test.example to apps/web/.env.test. Several escapes are on so tests do not fight production abuse and rate-limit policies. Each escape is hard-blocked at boot in production.

Mocking Patterns

For unit tests that cross package boundaries, mirror packages/api/src/router/storage.test.ts: declare mocks with vi.hoisted, then vi.mock with vi.importActual to keep real exports you still need.

const mocks = vi.hoisted(() => ({
  enforceAndResolveAbuse: vi.fn(),
  // ...
}));

vi.mock("@syntaxkit/shared/abuse", async () => {
  const actual = await vi.importActual("@syntaxkit/shared/abuse");

  return {
    ...actual,
    enforceAndResolveAbuse: mocks.enforceAndResolveAbuse,
  };
});

Integration tests use the same idea with a lighter mock (see storage.integration.test.ts): keep the real module, stub only enforceAndResolveAbuse. Use vi.hoisted() when the mock factory needs data the mocked module reads at load time. Pure-function tests need no mock: call the function and assert.

CI Pipeline

.github/workflows/ci.yml runs on pull requests and pushes to main. Path filters skip heavy jobs when a change cannot affect them (for example docs-only PRs). When web code changes, the shape is:

1. changes decides which areas moved (web, docs, setup, …).
2. setup installs the workspace and caches node_modules, the generated Prisma client, and built package artifacts under a SHA key. Later jobs restore that cache.
3. static-checks runs pnpm lint, pnpm check-types, pnpm db:validate, and build-arg sync in one job.
4. build-test builds docs when needed and runs pnpm test:coverage (unit + per-package gates).
5. setup-smoke runs only when setup-related files change.
6. integration boots Postgres 17 and Moto S3, migrates, seeds, then runs pnpm test:integration.
7. e2e boots Postgres 17, installs Chromium, migrates, seeds, builds the app, then runs pnpm test:e2e:run. Uploads the Playwright HTML report (7-day retention) and traces on failure (3-day retention).
8. ci-gate fails the workflow if any required job failed or was cancelled.

Stripe live is a separate workflow (.github/workflows/stripe-live.yml). The full suite is workflow_dispatch only. Catalog price drift (pnpm billing:check-prices) runs on pushes to main.

Adding A Test

Where To Go Next

Also useful: Authentication, Security, and Going To Production.