Testing

SyntaxKit ships a four-tier test setup: Vitest for unit, integration, and live Stripe tests, and Playwright for end-to-end browser tests. Every layer runs independently, so you can drive any subset locally while CI runs them all on each push. Per-package coverage gates (90% lines / 85% branches) keep the unit tier honest.

The four layers

Unit, integration, live Stripe, and E2E: what each touches and how to run it.

Test environment

The deterministic .env.test escapes and why each one is enabled.

CI pipeline

How the jobs run on every PR, and where to grab failure traces.

Add a test

Drop in a unit, integration, or E2E spec the right way.

The Test Pyramid

Unit Tests

Co-located *.test.ts(x) files run via per-package Vitest configs: jsdom for component tests, node for backend packages. Each package config (apps/web/vitest.config.ts plus the seven packages/*/vitest.config.ts) declares its own coverage gate, and CI fails the build if any of them slips. Every gate uses the same threshold object:

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

Integration Tests

Real Postgres, real Prisma, real aws-sdk calls against a Moto-mocked S3 bucket. The *.integration.test.ts suffix lives outside the unit-test include glob, so pnpm test:run skips them; you opt in with pnpm test:integration. The harness in packages/api/test/integration.ts exposes createIntegrationHarness() with ensureStorageBucket, cleanup, and getStoredObject helpers:

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

const harness = createIntegrationHarness();

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

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

Live Stripe Tests

The opt-in tier. Test-mode Stripe behavior occasionally drifts from what unit-test mocks assume, so the kit ships a small live suite that catches that drift early. Files use *.live.test.ts or *.live.integration.test.ts, gated by RUN_STRIPE_LIVE=1 so they never run during a normal pnpm test:run. CI runs them on a daily cron (0 3 * * *) and on workflow_dispatch via .github/workflows/stripe-live.yml. Locally:

RUN_STRIPE_LIVE=1 pnpm test:stripe

End-to-End Tests

Playwright with Chromium. Specs live in apps/web/e2e/ and cover every critical user flow: marketing, auth, signup, onboarding, dashboard, organization-settings, personal-settings, billing, two-factor, admin. Playwright starts the web server itself via the webServer config in apps/web/playwright.config.ts:

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

The deterministic escapes (DISABLE_ABUSE_PROTECTION, DISABLE_CAPTCHA_FOR_TESTS, empty UPSTASH_*) are loaded from apps/web/.env.test by dotenvx. See The Test Environment for what each one does. The auth specs in apps/web/e2e/auth.spec.ts exercise the same flows documented on Authentication, so changes to login, signup, password reset, or 2FA all re-verify against a real browser.

Parallelization And Worker Fixtures

Playwright runs four workers locally and two in GitHub Actions, and authenticated specs avoid global state by giving each worker its own deterministic user. Three files stay in sync to make this work:

The fixture in apps/web/e2e/helpers/fixtures.ts caches the sign-in once per worker: the first spec signs the user in and writes storageState to a file, and every later spec in that worker reuses the cached cookie state:

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, so uniqueSignupEmail() returns a pid + Date.now() + counter string and concurrent workers never collide on the same email.

The Test Environment

apps/web/.env.test (copied from apps/web/.env.test.example) defines the deterministic test environment. Several escapes are enabled deliberately so tests don't fight production-grade abuse and rate-limit policies. Each is hard-blocked at boot in production.

Mocking Patterns

The canonical recipe lives in packages/api/src/router/storage.integration.test.ts: top-of-file vi.mock("@syntaxkit/shared", ...) with vi.importActual to selectively keep real exports, then vi.fn() for the boundaries you want to control:

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

  return {
    ...actual,
    enforceAbusePolicy: vi.fn(async () => ({
      ok: true,
      reason: "allowed",
      results: {},
    })),
  };
});

Mirror this for any test that mocks a cross-package boundary. Use vi.hoisted() when the mock factory needs data the mocked module reads at load time (rare: it surfaces in middleware and config tests). Pure-function tests need no mock; just call the function and assert.

CI Pipeline

.github/workflows/ci.yml runs on every pull request and every push to main. Jobs run in dependency order:

1. setup installs the workspace and caches node_modules, the generated Prisma client, and built artifacts under a SHA-keyed key. Dependent jobs restore that cache instead of reinstalling.
2. lint, check-types, build, setup-smoke run in parallel after setup.
3. test runs pnpm test:coverage (unit + per-package coverage gates).
4. integration boots Postgres 17 and Moto S3 containers, applies migrations and seeds, then runs pnpm test:integration.
5. e2e boots Postgres 17, installs Chromium, applies migrations and seeds, then runs pnpm test:e2e. Uploads the Playwright HTML report (14-day retention) and traces on failure (7-day retention).
6. validate-schema runs pnpm db:validate against the Prisma schema.

The Stripe live suite runs on a separate workflow (.github/workflows/stripe-live.yml) because it depends on real third-party credentials and shouldn't gate every PR. It runs daily at 03:00 UTC and via workflow_dispatch.

Adding A Test

Where To Go Next