jest-testing

When to Use

• Writing or refactoring unit and integration tests with Jest.
• Setting up mocking strategies for modules, functions, or APIs.
• Testing async code (Promises, async/await, timers).
• Testing React components alongside @testing-library/react.
• Configuring Jest for TypeScript, coverage, or CI environments.
• Debugging flaky or slow tests.

Critical Patterns

• Arrange-Act-Assert: Every test follows three clear phases — set up state, perform the action, verify the outcome. No mixing.
• Test Behavior, Not Implementation: Assert on observable outcomes (return values, DOM changes, thrown errors), not internal function calls.
• Isolate with Mocking: Mock external dependencies (APIs, databases, file system) but NOT the unit under test. Over-mocking hides real bugs.
• One Assertion Focus Per Test: Each it block should test one logical behavior. Multiple assertions are fine if they verify the same behavior.
• Deterministic Tests: No reliance on real time, network, or random values. Use fake timers, mocked fetch, and seeded data.
• Clean Up After Yourself: Reset mocks in afterEach. Avoid shared mutable state between tests.

Code Examples

Basic Test Structure

describe("UserService", () => {
  let service: UserService;

  beforeEach(() => {
    service = new UserService();
  });

  afterEach(() => {
    jest.restoreAllMocks();
  });

  describe("findById", () => {
    it("returns user when found", async () => {
      // Arrange
      const mockUser = { id: "1", name: "Alice" };
      jest.spyOn(db, "query").mockResolvedValue(mockUser);

      // Act
      const result = await service.findById("1");

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

    it("throws NotFoundError when user does not exist", async () => {
      jest.spyOn(db, "query").mockResolvedValue(null);

      await expect(service.findById("999")).rejects.toThrow(NotFoundError);
    });
  });
});

Common Matchers