testing-mocks

Testing Mocks

This skill describes mocking patterns and best practices for creating maintainable, type-safe mocks in this codebase.

When to Use This Skill

Use when asked to:

• Create mocks for services, repositories, or dependencies
• Mock modules or external libraries
• Set up NestJS test containers with mocked providers
• Configure mock return values or assertions
• Write integration tests with mocked I/O

Core Principle 1: createMock<T>() for All Injectable Classes

Use @golevelup/ts-vitest's createMock<T>() to auto-mock any TypeScript class or interface. It returns a fully-typed DeepMocked<T> where every method is a vi.fn() and properties are recursively mocked. Never write manual stub objects — createMock stays in sync with the source type automatically.

import { createMock } from "@golevelup/ts-vitest";
import type { DeepMocked } from "@golevelup/ts-vitest";

const mockService = createMock<MyService>();

Core Principle 2: Declare Services Outside Hook, Instantiate Inside

Always declare service variables at the describe block scope using let, then populate them inside beforeAll or beforeEach using module.get() or await module.resolve(). This ensures services are available to all tests and maintains proper isolation.

describe(MyService, () => {
  // ✅ Declare services OUTSIDE the hook at describe scope
  let service: MyService;
  let repository: DeepMocked<Repository<MyEntity>>;

  // ✅ Instantiate INSIDE the hook
  beforeAll(async () => {
    const module = await Test.createTestingModule({
      providers: [MyService, /* mocks */],
    }).compile();

    // Retrieve using module.get() or await module.resolve()
    service = module.get(MyService);
    repository = module.get(getRepositoryToken(MyEntity));
  });

  it("uses the service", async () => {
    // ✅ All tests have access to instantiated services
    const result = await service.doWork();
    expect(result).toBeDefined();
  });
});

Why this pattern matters: