jest-patterns

Jest Patterns

Modern Jest testing patterns, anti-patterns, and quality rules for JavaScript/TypeScript.

jest_smell.py detects structural test smells deterministically via regex. The prose sections below cover judgment-level guidance that the script cannot evaluate. Never re-derive smell detection by eye when the script can do it; always run the script for consistent, auditable findings.

Core Principles

Principle	Description
Test Behavior	Test what code does, not how it does it
Isolation	Each test independent, no shared state
AAA Pattern	Arrange → Act → Assert structure
Fast Feedback	Tests run in milliseconds

Patterns vs Anti-Patterns

A mock-call assertion (.toHaveBeenCalledWith, .toHaveBeenCalled) is a valid substitute for a real assertion only at an OUTBOUND boundary the test owns — an HTTP request the code constructs, an event published to an external system — where the call itself IS the observable. It is never a substitute for observing a write path's actual effect; see "Testing Implementation Details" below and the write-path rule in qa.md.

Test Structure (AAA)

// GOOD: Clear AAA structure
describe('UserService', () => {
  it('should create user with valid data', async () => {
    // Arrange
    const userData = { name: 'John', email: '[email protected]' };
    const mockRepo = { save: jest.fn().mockResolvedValue({ id: '1', ...userData }) };
    const service = new UserService(mockRepo);

    // Act
    const result = await service.createUser(userData);

    // Assert
    expect(result.id).toBe('1');
    // mockRepo stands in for an injected collaborator here, illustrating AAA structure only —
    // a real createUser write-path test must exercise a real/in-memory DB, not assert on the mock call
    expect(mockRepo.save).toHaveBeenCalledWith(userData);
  });
});

// BAD: Mixed arrange/act/assert
it('creates user', async () => {
  const service = new UserService({ save: jest.fn() });
  expect(await service.createUser({ name: 'John' })).toBeDefined();
  // What are we testing? Unclear!
});