Test Writer

Test Writer

When to use this skill

Use this skill when you’re adding features or fixing bugs and you want tests that lock in behavior, are easy to read, and fail with useful diagnostics.

Core patterns

Test behavior, not implementation

Prefer assertions on:

• outputs and return values
• observable side-effects (DB writes, network calls via mocked boundary)
• rendered UI behavior

Avoid asserting:

• internal helper calls
• private state
• exact call order unless it’s part of the contract

Arrange / Act / Assert (AAA)

Structure tests so readers can skim:

• Arrange: setup inputs + mocks
• Act: execute
• Assert: verify outcomes

it("returns 401 when token is missing", async () => {
  // Arrange
  const req = makeRequest({ headers: {} });

  // Act
  const res = await handler(req);

  // Assert
  expect(res.status).toBe(401);
});

Naming conventions

Use readable test names:

• describe("<unit>")
• it("does <behavior> when <condition>")

Bad:

• it("works")
• it("test1")

Mocking philosophy: mock at the boundary

Mock:

• HTTP clients
• DB adapters/repositories
• filesystem
• time

Avoid mocking deep internals; that freezes implementation and makes refactors painful.

Testing async code

Rules:

• always await promises
• assert rejection paths explicitly

await expect(fn()).rejects.toThrow("missing");

Snapshot tests (use intentionally)

Use snapshots when:

• large stable output (markdown rendering, formatted AST)
• you want quick diff review

Avoid snapshots for:

• small outputs (write explicit asserts)
• unstable values (timestamps, random IDs)

Error paths are first-class

Every critical function should have tests for:

• invalid input
• missing resources (ENOENT)
• permission denied
• timeouts / retries

Unit vs integration vs e2e

Use:

• Unit: pure logic, fast, lots of cases
• Integration: modules wired together (DB in memory, API route handler with mocked network)
• E2E: user flows (Playwright/Cypress), fewer tests but high confidence