Testing Philosophy

• Test public interfaces and observable outcomes
• Assert on return values, state changes, and side effects
• Write tests that survive refactoring

Don't:

• Test private methods directly
• Assert on internal data structures
• Mock everything — only mock at system boundaries
• Test that specific internal functions were called

// Bad: Tests implementation
test("calls processOrder internally", () => {
  const spy = jest.spyOn(service, "processOrder")
  service.submitOrder(order)
  expect(spy).toHaveBeenCalled()
})

// Good: Tests behavior
test("submitted order appears in order history", () => {
  service.submitOrder(order)
  const history = service.getOrderHistory()
  expect(history).toContainEqual(expect.objectContaining({ id: order.id }))
})

Principle 2: Arrange-Act-Assert

Every test follows the same three-part structure.

Why: Consistent structure makes tests scannable. A reader can instantly find the setup, the action, and the expectation.

test("returns 404 when user not found", async () => {
  // Arrange — set up preconditions
  const db = createTestDb()
  const api = createApp(db)

  // Act — perform the action under test
  const response = await api.get("/users/nonexistent-id")

  // Assert — verify the outcome
  expect(response.status).toBe(404)
  expect(response.body.error).toBe("User not found")
})

Rules:

• One logical action per test (the Act section should be 1-3 lines)
• One assertion per logical concept (multiple expect calls are fine if they verify the same concept)
• If Arrange is complex, extract to a helper or beforeEach

Principle 3: Deterministic by Default

Tests must produce the same result every time, on every machine.

Why: Flaky tests erode trust. A test suite that occasionally fails teaches developers to ignore failures.

Sources of non-determinism to avoid:

• Time: Don't use Date.now() or setTimeout directly — inject a clock
• Network: Don't call real APIs — use fixtures or test doubles
• Random values: Don't use Math.random() — use seeded generators
• File system: Use temp directories, clean up after yourself
• Ordering: Tests must not depend on execution order
• Shared state: Each test gets its own state — no globals

// Bad: Non-deterministic
test("token expires after 1 hour", () => {
  const token = createToken()
  expect(token.expiresAt).toBeGreaterThan(Date.now()) // Depends on wall clock
})

// Good: Deterministic
test("token expires after 1 hour", () => {
  const now = new Date("2026-01-01T00:00:00Z")
  const token = createToken({ now })
  expect(token.expiresAt).toEqual(new Date("2026-01-01T01:00:00Z"))
})

Principle 4: Test Names Are Documentation

A test name should describe the requirement, not the implementation.

Why: When a test fails, the name is the first thing you read. A good name tells you what broke without reading the code.

Format: should [expected behavior] when [condition]

// Bad: Describes implementation
test("test validateEmail function")
test("email validation test 1")
test("it works")

// Good: Describes requirement
test("should reject email without @ symbol")
test("should accept email with subdomain")
test("should return 401 when token is expired")
test("should retry failed request up to 3 times")

Rules:

• Start with should or describe the expected outcome
• Include the condition or trigger
• Be specific enough that a failure message tells you what broke
• If you can't name it clearly, the test may be doing too much

Testing Patterns

Test Doubles (When to Use What)

Rule of thumb: Only mock at system boundaries (network, database, file system). Internal modules should use real implementations.

Test Organization

tests/
├── unit/           # Fast, isolated, no I/O
├── integration/    # Multiple modules working together
└── e2e/            # Full system tests

• Unit tests should be fast (<100ms each) and require no setup
• Integration tests can use test databases or containers
• E2E tests are slow and should be minimal — test critical paths only

Adherence Checklist

Before completing your tests, verify:

• Tests verify behavior, not implementation details?
• Each test has clear Arrange/Act/Assert structure?
• No flaky tests that depend on timing, network, or order?
• Test names describe the expected behavior and condition?
• Mocks used only at system boundaries?
• Each test is independent and can run in isolation?
• Failed test name alone tells you what broke?