Testing

Where Teak's tests live, which layer to use, the rules that make a test worth keeping, and how to run the end-to-end suite

How to write tests in Teak that fail when behavior breaks, and pass when it does not. Read this before adding, changing, or deleting a test.

The one rule

A test earns its place only if it fails when the behavior it names is broken. Before you finish, ask: “If I deleted or broke the code under test, would this test fail?” If not, it is not a test. Delete it or rewrite it.

Pick the layer

Prefer the lowest layer that can observe the behavior. Move up a layer only when the behavior lives in the integration: a query index, an auth session, a browser API.

Where files go

Each workspace script runs only the files it matches. A test file outside these paths never runs, and that is a bug.

bun run test at the root runs all of it, and the Unit Tests workflow runs it on every pull request.

Rules

Assert outcomes, not implementation.

• Assert returned values, database state, rendered text, roles, href and src, HTTP status and body, and CLI stdout and exit codes.
• Don’t assert that a mock was called with a query-builder chain (withIndex, eq, take). Seed data and assert the result.
• Don’t assert CSS class names or DOM nesting.

Never test the source text. Don’t readFileSync a source file and toContain a string. Extract the logic into a function and call it. If a regression truly can’t be reached any other way, keep at most one such assertion and name the bug in a comment.

Mock only boundaries you don’t own. That means network, AI providers, R2 storage, Polar, email, time, and native modules. Never mock the module under test or its sibling modules to reach a branch.

Never re-implement the code in the test. Copying a regex list or an if chain into the test and asserting on the copy proves nothing. Export the function and call it (see apps/extension/lib/restrictedUrl.ts).

Always await async assertions. await expect(p).rejects.toThrow(). An unawaited .rejects or .resolves passes even when the promise does the wrong thing.

No filler. None of these count as tests:

• expect(true).toBe(true)
• expect(module).toBeDefined()
• asserting a constant equals its own literal
• building an object in the test and asserting its own fields

Keep tests hermetic.

• Restore any process.env keys you change.
• Clear variables that other modules set at import time. For example, next.config.ts sets NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA whenever a commit SHA is present, as it is in CI.
• Don’t depend on test order. Check with bun test --randomize and bun test --seed=<n>.

One behavior per test, named as the behavior. Write “refuses to auto-save chrome:// pages”, not “test isValidUrl 3”. Use test.each for tables of inputs.

Browser tests:

• Use getByRole and getByLabel locators, and web-first expect assertions. e2e matches names exactly and case-sensitively; pass { exact: false } only when a fragment is the point.
• No agent steps (agent.act, agent.assert): the suite configures no model, so every step is a locator or an exact expect.
• Never waitForTimeout, and never wait for networkidle.
• Never test.skip when an element is missing. A missing element is a failure.
• Credential-gated skips are the only allowed skip.

Data against real backends:

• Use unique markers per run (generateTestContent in packages/tests/src/web/fixtures.ts).
• End-to-end accounts are WorkOS emulator users that exist only for the run. Each spec file makes its own (createAccount or createApiAccount in packages/tests/src/helpers/app.ts), and web specs get one per test from packages/tests/src/web/fixtures.ts. Files share nothing, so they can run in any order.
• Never point a test at production or staging accounts.

Reuse before you write

• Convex:
  • packages/convex/__tests__/helpers/ provides withTestSession, R2 mocks and public API HTTP helpers.
  • packages/convex/edge/occContention.test.ts has insertCard and search sync fixtures.
  • packages/convex/edge/workosSessions.test.ts shows WorkOS-backed sessions with t.withIdentity.
• End-to-end: packages/tests/src/helpers/app.ts (sign-up, hosted sign-in, API keys, deletion), emulator.ts (WorkOS users, emailed codes, session tokens), page-hooks.ts (page errors, blocked requests, Convex socket routing), test.ts (retry, firstVisible), api.ts, cli.ts and mcp.ts. Headless WorkOS sessions against staging: scripts/lib/workos-test-session.ts.
• Raycast: createRaycastApiMock in apps/raycast/src/__tests__/raycastApiMock.ts.

Before you finish

1. For a bug fix, write the failing test first and watch it fail for the right reason.
2. Run the narrowest test, then bun run --cwd <workspace> test, then bun run test if the change crosses workspaces.
3. Break the code on purpose (flip a condition, delete a line) and confirm the new test fails. Then restore it.
4. Re-read the diff for skipped tests, unawaited assertions, and deleted assertions. Never delete or loosen an assertion just to make a test pass.

End-to-end suite

packages/tests holds e2e journeys across the web app, REST API, CLI and MCP server. They run against a local stack that exists only for this suite and the clean-container smoke; development always uses the shared development deployment, which the suite never touches. The stack is:

• the official WorkOS emulator (@workos/emulate), standing in for hosted AuthKit,
• a local Convex backend (API and webhooks on the next port),
• the Files Worker under wrangler dev in local mode (src/stack/filesWorker.ts), which serves files and runs background work on Workflows, Queues, R2, KV and Analytics Engine as Miniflare emulates them,
• the web app.

It needs no secrets, so you can run it without access to the development deployment. Every WorkOS value is a test-only constant in src/stack/config.ts, and the emulator keeps everything in memory; the Files Worker’s signing secret is a test-only constant too. The main checkout uses web 3000, Convex 3210/3211, the emulator 4100/4101 and the Files Worker 4102 (its inspector on 4103); each linked worktree uses its own ports.

The specs drive the browser with locators and exact expect assertions only. They run no agent steps, so the suite needs no model or API key.

Run it

From the repo root, with this checkout’s dev stack stopped (bun run dev --stop):

bun install
(cd packages/tests && bunx e2e-web install chromium webkit)   # once
bun run --cwd packages/tests e2e

e2e checks the pinned runtimes and packages, sets up the local backend (src/stack/backend.ts), starts the stack, warms it up (e2e.warmup.config.ts), runs the Chromium suite (e2e.config.ts) and the WebKit half of the browser matrix (e2e.webkit.config.ts), and stops everything. Pass e2e run arguments to run something narrower, for example bun run --cwd packages/tests e2e src/journey/03-api.e2e.ts or bun run --cwd packages/tests e2e -- --grep editor.

To iterate, keep the stack up in one terminal and run e2e in another:

bun run --cwd packages/tests e2e:stack
cd packages/tests && E2E_TELEMETRY_DISABLED=1 bunx e2e run src/web/markdown-editor.e2e.ts:42

A running stack records its URLs in .agents/.state/stack.json, which the configs and helpers read, and logs to .agents/.state/stack.log. While it runs it takes over packages/convex/.env.local; the next bun run dev selects the development deployment again. A failed test prints the path of its trace page (.e2e/<suite>/results/<test>/trace.md): every step with what it hit, the app’s console errors and failed requests, and the screen at the failure. Read it before re-running. Add --headed to watch a run, --video on to record every attempt, and --trace on to keep traces for passing tests too. --last-failed, --repeat-each=<n>, --grep, --max-failures and path:line selection also work.

The E2E workflow (.github/workflows/e2e.yml) runs the same command daily and on demand (not on pull requests or pushes), and uploads .e2e/ and the stack log. The Clean Container Smoke workflow runs src/matrix in Chromium from a clean checkout on every pull request and posts the result on it.

Suites

Each config runs its own directories and writes to its own .e2e/<suite>/:

Files in a suite run in parallel and share nothing: every spec makes its own accounts. Tests inside a file run in order on one worker, and a describe(..., { serial: true }) group shares one browser and its module state, for flows such as sign-up, sign-out and account deletion.

How the stack is wired

src/stack/backend.ts points packages/convex/.env.local at a local backend and sets WORKOS_CLIENT_ID, WORKOS_API_KEY, WORKOS_API_BASE_URL, WORKOS_ENVIRONMENT_ID and WORKOS_WEBHOOK_SECRET on it. The stack passes the web app its emulator settings, including WORKOS_API_HOSTNAME, WORKOS_API_PORT and WORKOS_API_HTTPS for authkit-nextjs, as process environment, which Next.js prefers over apps/web/.env.local, so the development wiring in that file stays as it is.

The emulator runs with:

• the interactive login pages, with the password step, like hosted AuthKit,
• https://api.workos.com as the token issuer, which the backend requires,
• a JWT template that adds email and email_verified to session tokens, like Teak’s WorkOS environment,
• a webhook endpoint for user.* events at the backend’s /workos/webhook, signed with the pinned test secret.

A small proxy in front of the emulator adds hosted AuthKit’s 30-second refresh-token grace window (session resilience). The web client refreshes its session on every page load, and without the window a navigation that interrupts that refresh would end the session. The backend runs with convex dev --once --start, so the suite’s own file writes never trigger a push.

Accounts

Accounts are real WorkOS users in the emulator. Creating one through the emulator API sends a signed user.created webhook, which gives the address a Teak vault. Browser specs then sign in through the hosted login page (signIn and createAccount in src/helpers/app.ts); the sign-up journey’s account starts unverified, so its first sign-in goes through the emailed verification code. The emulator never sends email: codes and reset tokens are read from its /events API (src/helpers/emulator.ts). API keys come from Settings, the way people create them, except in the API, CLI and MCP specs, which never open a browser: createApiAccount calls the same mutation Settings does, signed in with the emulator’s password grant. Tests sign in fresh instead of reusing saved cookies, which go stale once the client refreshes its session.

What e2e doesn’t do, and the stand-ins

src/helpers/page-hooks.ts covers the Playwright features the specs need that e2e doesn’t have, with init scripts in the page:

• capturePageErrors records uncaught errors and unhandled rejections (Playwright’s pageerror).
• blockAndRecordRequests records and aborts requests to a URL pattern (the request event, for “never fetched” checks).
• routeConvexSocket routes the browser’s Convex sync socket through interceptors that run in the page: a backend that can’t be reached, an injected mutation failure, a rewritten query result (routeWebSocket).

retry and firstVisible in src/helpers/test.ts stand in for expect(...).toPass() and locator.or(). Each test has one page: a second user signs in after app.clearState(), or the check runs at the API.

What the local stack doesn’t cover

• Workers AI, Browser Run, Vectorize and the two Containers. They need a Cloudflare account or Docker. The Worker’s AI binding is a service binding to a deterministic fake (apps/files-worker/e2e/fakeAi.ts), so text and image cards get tags and summaries; link fetching, link screenshots, video and PDF rendering, audio transcripts and embeddings fail the way they do when those services are down, and their stages end failed. Uploads, image analysis (Images is emulated), exports, imports and account deletion run for real.
• AuthKit Actions (the sign-up freeze registration action). The emulator doesn’t run Actions; packages/convex/edge/workosAuthKit.test.ts covers it.
• WorkOS Connect OAuth for the CLI, extensions, Raycast and MCP. The emulator’s Connect flow has no PKCE or refresh tokens. The API, CLI and MCP journeys use Teak API keys, and the browser OAuth flows have hermetic checks: bun run --cwd packages/tests e2e:hermetic, and the Extension OAuth Runtime workflow.
• Billing. Polar checkout needs Polar credentials.
• The browser extension. It signs in with WorkOS Connect, and e2e can’t load a browser extension.

Bun test options

bun test (Bun 1.4) has options that help when a test misbehaves:

• --changed[=<ref>] runs only test files affected by changed files.
• --only-failures, --bail, and --rerun-each=20 confirm a flake is really fixed.
• --randomize with --seed=<n> finds and replays order dependence.
• --isolate gives each file a fresh global, which shows whether a failure is a leak from another file.
• --parallel=<n>, --shard=<i>/<n>, and --coverage --coverage-reporter=lcov are also available.