Jest Best Practices

Analogy categoryAnalogies

Structuring Tests for Clarity

Every Jest test should follow the Arrange-Act-Assert pattern: set up fixtures and mocks, perform the single action under test, then verify the outcome. Nesting describe blocks by feature and it blocks by scenario keeps failures easy to locate, since Jest prints the full describe chain in its output when a test fails.

🏏

Cricket analogy: Arrange-Act-Assert mirrors how Bumrah sets his field before delivery, runs in and bowls the yorker, then the umpire signals the outcome - each phase happens in strict order and is never skipped or merged.

Isolating State Between Tests

Tests that share mutable module-level state or forget to reset mocks between runs become flaky and order-dependent. Use beforeEach to reset spies with jest.clearAllMocks() or jest.resetAllMocks(), and avoid module-level variables that accumulate state across it blocks, since Jest reuses the module registry within a test file by default.

🏏

Cricket analogy: Resetting mocks in beforeEach is like relaying the pitch between Test matches - Kohli's side cannot inherit worn footmarks from the previous game, so every match starts on a fresh surface.

Mock only at the boundaries of the system under test - network calls, file system access, timers, and third-party SDKs - rather than mocking your own internal functions, which turns the test into a check of the mock rather than a check of real behavior. Over-mocking hides integration bugs that only appear when real modules interact.

🏏

Cricket analogy: Mocking only the DRS review system's external hardware, while letting the umpire's actual decision logic run, is like tests mocking network calls but exercising the real business logic underneath.

Choosing the Right Assertions

Prefer toEqual for deep value comparisons over toBe, which checks reference identity and only suits primitives. Use toMatchObject when only a subset of an object's fields matter, and reserve snapshot testing for stable, reviewed output rather than volatile data, since unreviewed snapshot updates can mask real regressions.

🏏

Cricket analogy: Choosing toEqual over toBe for scorecards is like a scorer comparing two identical run tallies by value, not by whether they are the same physical scoresheet - Root's 120 equals another 120 on different paper.

javascript

// user.test.js
import { createUser } from './userService';
import { db } from './db';

jest.mock('./db');

describe('createUser', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('persists a normalized user and returns the saved record', async () => {
    // Arrange
    db.insert.mockResolvedValue({ id: 1, email: 'a@b.com' });

    // Act
    const result = await createUser({ email: 'A@B.com  ' });

    // Assert
    expect(db.insert).toHaveBeenCalledWith(
      expect.objectContaining({ email: 'a@b.com' })
    );
    expect(result).toEqual({ id: 1, email: 'a@b.com' });
  });
});

Name tests as behavior statements, e.g. 'returns 401 when the token is expired', not implementation statements like 'calls checkToken'. Behavior-focused names survive refactors and double as living documentation.

Keeping Suites Fast in CI

Avoid asserting on implementation details such as internal function call counts for logic that could legitimately change shape during a refactor. Tests coupled to implementation rather than observable behavior force unnecessary rewrites and erode trust in red test failures.

Follow Arrange-Act-Assert and nest describe/it blocks to make failures easy to locate.
Reset mocks in beforeEach with jest.clearAllMocks() to prevent order-dependent flakiness.
Mock only external boundaries (network, filesystem, timers) - not your own internal logic.
Prefer toEqual for value comparisons and toMatchObject for partial-object checks over toBe.
Treat snapshots as reviewed contracts, not a substitute for meaningful assertions.
Write test names that describe observable behavior, not internal implementation calls.
Keep each test focused on one behavior so failures point directly at the cause.