test-behavior-not-implementation

Test Behavior, Not Implementation

A test calls the code the way its users do and asserts the result they observe against a literal expected value. A test that asserts which calls the code made, or restates a constant the code contains, does neither.

The check: before you keep a test, ask whether it would still pass if every function it imports returned undefined. If yes, it observes no behavior and cannot fail for a defect. Rewrite the assertion or delete the test.

Why: A test that cannot fail for a defect costs CI time and review attention and catches nothing. A constant pin also fails when someone edits the constant or the prompt it restates, so it prevents that edit.

Five Weak Shapes

• Weak or no assertion. No expect, or only toBeDefined, toBeTruthy, not.toThrow, toBeInstanceOf, toBeGreaterThan(0).
• Mock or absence only. Only toHaveBeenCalled, not.toHaveBeenCalled, toHaveBeenCalledTimes(N), toBeUndefined, toEqual([]), toHaveLength(0), not.toBe(wrongValue).
• Self-referential. The expected value comes from the code under test: expect(f(a)).toBe(f(a)), expect(parsed.url).toBe(buildUrl(...)).
• Constant pin. The assertion restates a hand-maintained constant: expect(LIMITS.maxTools).toBe(8), expect(PROMPT).toContain("You are").
• Fixture asserts fixture. The assertion reads data the test built in beforeEach, and the subject never runs inside the test body.

The Fix

For mock-only: Assert the payload the mock received or the state after the call, not that it was called.

// WRONG
expect(handleClick).toHaveBeenCalledTimes(1)

// RIGHT
expect(handleClick).toHaveBeenCalledWith('item-42')

For weak assertion: Call the subject inside the test body with one concrete input and assert the literal output or the observable effect.

// WRONG
expect(slugify("Hello")).toBeDefined()

// RIGHT
expect(slugify("Hello, World!")).toBe("hello-world")

For self-referential: Test the mechanism that reads it with one concrete input instead of calling the same function twice.