scaffold-test

Scaffold Test File

Generate a Vitest test file for an existing source file following project conventions.

Workflow

1. Read the source file to discover all exported functions, classes, and types.
2. Read 1-2 nearby test files in the same directory to learn existing mock patterns and style.
3. Generate the test file co-located next to the source, following the template below.

Test File Location

• Source files: src/app/lib/foo-actions.ts -> src/app/lib/foo-actions.test.ts
• Library files: src/lib/bar.ts -> src/lib/bar.test.ts
• Route files: src/app/api/baz/route.ts -> src/app/api/baz/route.test.ts (same directory)

Critical Rules

1. FIRST LINE must be // @vitest-environment node -- the jsdom environment has a broken tldts dependency. Every test file in this project requires this pragma.
2. Mock @/lib/db if the source imports prisma -- use vi.mock('@/lib/db', () => ({ prisma: { ... } })) with vi.hoisted() mock functions for each Prisma model method used.
3. Co-locate tests next to the source file. Never create a separate __tests__ directory.
4. Use vi.hoisted() for all mock function declarations to ensure they are hoisted above vi.mock() calls.
5. Mock next/cache if the source imports revalidatePath or revalidateTag.
6. Suppress console.error in beforeEach with vi.spyOn(console, 'error').mockImplementation(() => {}).

Template

// @vitest-environment node
import { describe, it, expect, vi, beforeEach } from 'vitest';

// ── Mocks ────────────────────────────────────────────────────────────────────

const mocks = vi.hoisted(() => ({
  // Auth mocks (include if source imports auth-guard or @/auth)
  requireUser: vi.fn(),
  // auth: vi.fn(),

  // Prisma mocks (include if source imports @/lib/db)
  // modelNameFindFirst: vi.fn(),
  // modelNameCreate: vi.fn(),
  // modelNameUpdate: vi.fn(),
  // modelNameUpdateMany: vi.fn(),

  // Activity logger (include if source imports @/lib/activity-logger)
  // logActivity: vi.fn(),

  // Cache (include if source imports next/cache)
  // revalidatePath: vi.fn(),
  // revalidateTag: vi.fn(),

  // Cron guard (include if source imports @/lib/cron-guard)
  // verifyCronRequest: vi.fn(),
  // acquireCronLock: vi.fn(),
  // releaseCronLock: vi.fn(),
}));

// Include each vi.mock() only for modules the source file actually imports:

// vi.mock('@/lib/db', () => ({
//   prisma: {
//     modelName: {
//       findFirst: mocks.modelNameFindFirst,
//       create: mocks.modelNameCreate,
//       update: mocks.modelNameUpdate,
//       updateMany: mocks.modelNameUpdateMany,
//     },
//   },
// }));

// vi.mock('@/lib/auth-guard', () => ({ requireUser: mocks.requireUser }));
// vi.mock('@/auth', () => ({ auth: mocks.auth }));
// vi.mock('@/lib/activity-logger', () => ({ logActivity: mocks.logActivity }));
// vi.mock('next/cache', () => ({
//   revalidatePath: mocks.revalidatePath,
//   revalidateTag: mocks.revalidateTag,
// }));
// vi.mock('@/lib/cron-guard', () => ({
//   verifyCronRequest: mocks.verifyCronRequest,
//   acquireCronLock: mocks.acquireCronLock,
//   releaseCronLock: mocks.releaseCronLock,
// }));

// ── Imports ──────────────────────────────────────────────────────────────────

import {
  // TODO: Import all exported functions from the source file
} from './SOURCE_FILE';

// ── Helpers ──────────────────────────────────────────────────────────────────

// function authedUser(orgId = 'org-1') {
//   return { id: 'user-1', organization_id: orgId };
// }

// ── Setup ────────────────────────────────────────────────────────────────────

beforeEach(() => {
  vi.clearAllMocks();
  vi.spyOn(console, 'error').mockImplementation(() => {});
  // TODO: Set default mock return values
  // mocks.requireUser.mockResolvedValue(authedUser());
});

// ── Tests ────────────────────────────────────────────────────────────────────

// One describe() block per exported function:

// describe('functionName', () => {
//   it('blocks unauthenticated users', async () => {
//     // TODO: Test auth guard
//   });
//
//   it('returns error when no organization', async () => {
//     // TODO: Test org check
//   });
//
//   it('performs the expected operation', async () => {
//     // TODO: Test happy path
//   });
//
//   it('handles errors gracefully', async () => {
//     // TODO: Test error handling
//   });
// });

Route Handler Tests

For route.ts files, use NextRequest to construct test requests:

import { NextRequest, NextResponse } from 'next/server';
import { GET, POST } from './route';

function makeReq(method = 'GET', body?: object) {
  const url = 'http://localhost/api/path';
  if (body) {
    return new NextRequest(url, {
      method,
      body: JSON.stringify(body),
      headers: { 'content-type': 'application/json' },
    });
  }
  return new NextRequest(url, { method });
}

// For cron routes:
function makeCronReq() {
  return new NextRequest('http://localhost/api/cron/job-name', {
    headers: { authorization: 'Bearer test-secret' },
  });
}

Known Gotchas

• src/lib/financial-export.ts uses document.createElement -- not unit-testable in node environment. Skip or mark as integration-only.
• src/lib/google-places.ts imports @/lib/db at the top level -- mock @/lib/db even when testing pure functions from this module.
• src/lib/super-admin-guard.ts reads process.env at module load time -- vi.resetModules() fails due to the next-auth import chain. Set env vars before the module loads.
• Zod v4: Use .gt(0) not .positive() in test data schemas. The .positive() method is deprecated.
• @/lib/numeric-schemas: If source imports monetaryAmount, mock it: vi.mock('@/lib/numeric-schemas', () => { const { z } = require('zod'); return { monetaryAmount: z.number().gt(0) }; }).