testing-guide

name	testing-guide
description	Test writing patterns, mocking strategies, and test data templates for Jest unit and integration tests. Use when writing new tests or need guidance on mocking repositories.
allowed-tools	Read, Glob, Grep

Testing Guide

Patterns and templates for writing Jest unit and integration tests. This complements the unit-tester subagent which handles test execution.

---

Critical Rules (Always Apply)

• NEVER import or use @prisma/client directly in any test file
• NEVER mock @prisma/client - if you need Prisma client, you haven't properly mocked the repository
• ALWAYS mock the specific repository modules used by the code under test
• Never test repositories in src/lib/repositories directly

---

Repository Mocking Pattern

This is the core mocking pattern. Mock the repository module, then configure return values per test.

// ✅ CORRECT: Mock repository modules
jest.mock("@/lib/repositories/userRepository", () => ({
  getById: jest.fn(),
  updateName: jest.fn(),
}));
const mockUserRepository = require("@/lib/repositories/userRepository");

// In your test:
mockUserRepository.getById.mockResolvedValue({
  id: 1,
  name: "Ana Garcia",
  email: "[e-mail]",
});

// ❌ WRONG: Never mock Prisma client
jest.mock("@prisma/client"); // DON'T DO THIS!

---

External Dependencies Mocking

// Mock external libraries at module level
jest.mock("langfuse", () => ({
  Langfuse: jest.fn(),
  TextPromptClient: jest.fn(),
}));

// Spy on console methods
const consoleLogSpy = jest.spyOn(console, "log").mockImplementation(() => {});
afterAll(() => {
  consoleLogSpy.mockRestore();
});

---

Environment Variable Testing

• AVOID direct assignment to process.env.NODE_ENV (TypeScript read-only)
• USE expect.any(Boolean) for environment-dependent behavior
• PREFER testing actual behavior over mocking environment variables

---

Spanish Business Context Test Data

Use realistic Spanish test data for all tests:

const testData = {
  customers: [
    { name: "Ana Garcia", phone: "[phone]" },
    { name: "Jose Maria Fernandez-Vazquez", phone: "[phone]" },
  ],
  businesses: [
    { name: "Salon Bella", address: "Calle Mayor 1, Madrid" },
    { name: "Peluqueria Nona & Coiffeur", services: ["corte", "peinado"] },
  ],
  specialChars: "Hola! Como esta usted?",
};

---

Edge Cases Checklist

Always consider testing these:

• null and undefined values
• Empty objects {} and arrays []
• Complex nested objects
• Special characters and emojis
• Circular references (where applicable)
• Functions within objects
• Large data sets

---

Test File Structure

__tests__/
  unit/            # Unit tests (functions, hooks, utils)
  integration/     # Integration tests (components, API handlers)
  e2e/             # Playwright E2E test scripts
testing/
  setupTests.ts    # Jest global setup file

---

Running Tests

Command	Purpose
npm test	All Jest tests
npm test -- --coverage	With coverage report
npm run test:watch	Watch mode
npm run test:e2e	All Playwright E2E tests
npm run test:e2e:smoke	Smoke tests only (fast, for PRs)
npm run test:e2e:full	Full E2E suite (nightly)

---

Best Practices

• Isolate tests: Avoid shared state or order dependency
• One behavior per test: Follow AAA pattern (Arrange, Act, Assert)
• User-centric: Test components via user interactions (React Testing Library)
• Clean up: Always restore spies and mocks in afterAll/afterEach
• Coverage target: >= 80% on critical code paths

---

Workflow: Finding Existing Test Patterns

When writing new tests, explore for existing patterns:

1. Find similar test files: Glob("__tests__/**/*.test.ts")
2. Find mock patterns: Grep("jest.mock", path="__tests__/")
3. Find test setup: Read("testing/setupTests.ts")
4. Find how a specific repository is mocked: Grep("mock.*Repository", path="__tests__/")