unit-testing

Unit Testing Rules

Core Principles

• Scope: Test one unit in isolation (pure functions, small utilities, or a single module's public API). Avoid integration concerns.
• Location & naming: Place files under /tests/unit mirroring the src path; name them *.test.ts or *.test.tsx.
• Dependencies: Never mock internal code; only mock external dependencies (APIs, DB, file system). Use MSW for HTTP.
• Determinism: Eliminate flakiness. Control time, randomness, and async with fake timers (vi.useFakeTimers, vi.setSystemTime) and stubs for Math.random.
• Structure: Use Arrange–Act–Assert; name tests by behavior ("should … when …").
• Assertions: Prefer explicit assertions over snapshots; only use small, stable snapshots when necessary.
• Coverage: Cover happy path, key error states, and edge cases; don't chase line coverage for its own sake.
• Isolation: Reset state and mocks between tests (vi.restoreAllMocks, vi.resetModules). No cross-test data coupling.
• Quality gates: Tests must pass TypeScript strict checks and ESLint; no any or untyped helpers.

Test Structure

describe("Feature", () => {
  describe("when condition", () => {
    it("should expected behavior", async () => {
      // Arrange
      const input = { /* test data */ };

      // Act
      const result = await functionUnderTest(input);

      // Assert
      expect(result).toEqual(expectedOutput);
    });
  });
});

Mocking Guidelines

• External APIs: Mock with MSW or vi.mock() for HTTP clients
• Database: Mock repository functions, not the ORM itself
• Time: Use vi.useFakeTimers() and vi.setSystemTime()
• Randomness: Stub Math.random() with vi.spyOn(Math, 'random').mockReturnValue(0.5)
• Environment: Mock process.env values as needed

Common Patterns

Testing Pure Functions

describe("formatUserData", () => {
  it("should format user name correctly", () => {
    const user = { firstName: "John", lastName: "Doe" };
    const result = formatUserData(user);
    expect(result.name).toBe("John Doe");
  });
});