Add Test

tRPC Router Test Template

import { describe, test, expect } from 'bun:test';
import { createCallerFactory } from '../trpc';
import { appRouter } from '../routers';
import type { Context } from '../trpc';
import { createMockDb, createTestUser, TEST_USER_ID } from './helpers';

function createTestContext(overrides: Partial<Context> = {}): Context {
  return {
    db: createMockDb(),
    user: null,
    req: new Request('http://localhost:3002'),
    ...overrides,
  };
}

const createCaller = createCallerFactory(appRouter);

describe('routerName', () => {
  describe('list', () => {
    test('returns items', async () => {
      const caller = createCaller(createTestContext());
      const result = await caller.routerName.list({ limit: 20, offset: 0 });
      expect(result.items).toBeArray();
    });
  });

  describe('create', () => {
    test('throws UNAUTHORIZED for unauthenticated user', async () => {
      const caller = createCaller(createTestContext({ user: null }));
      await expect(caller.routerName.create({ name: 'test' })).rejects.toMatchObject({
        code: 'UNAUTHORIZED',
      });
    });
  });
});

What to Test per Procedure/Function

For tRPC routers:

• Happy path with valid input
• Invalid input → BAD_REQUEST
• Unauthenticated → UNAUTHORIZED (protected procedures)
• Wrong owner → FORBIDDEN
• Missing resource → NOT_FOUND
• Edge cases (empty results, pagination boundaries)

For Zod schemas:

• Valid input with all required fields
• Valid input with optional fields omitted
• Each required field missing
• Invalid types for each field
• Boundary values (min/max length, min/max number)
• Default values applied correctly

For utility functions:

• Normal inputs → expected outputs
• Edge cases (empty strings, zero, null)
• Error conditions

Mock Patterns

Database Mock

Use createMockDb() from apps/api/src/__tests__/helpers.ts.

Module Mock

import { mock } from 'bun:test';
mock.module('@x4/database', () => ({ db: createMockDb() }));

CRITICAL: bun mock.module runs ALL test files in the same process. First call wins. Extract shared mocks into a single helper file.

Environment Variables

env.ts validates eagerly at import time — set env vars BEFORE importing:

process.env.DATABASE_URL ??= 'postgres://test:test@localhost/test';

Conventions

• Always import from bun:test (never jest)
• Use describe blocks grouped by function/procedure name
• Use descriptive test names: "returns X when Y", "throws Z for invalid input"
• Use toMatchObject for partial error matching
• Test tRPC error codes: NOT_FOUND, UNAUTHORIZED, FORBIDDEN, BAD_REQUEST

Workflow

1. Read the source file to understand exports and logic
2. Determine the test pattern based on file location
3. Check for existing test helpers in apps/api/src/__tests__/helpers.ts
4. Generate the test file at the correct location
5. Run bun test <test-file-path> to verify tests pass