Writing Tests

intent

tests prove behavior works. a test that can't fail is worthless, a test that tests mocks instead of real code is theater. this skill covers test quality standards, assertion patterns, edge case discovery, anti-pattern detection, and the discipline to push back on "we'll add tests later." use it whenever writing tests, adding coverage, fixing failing tests, or reviewing test quality across any language or framework. complements language-specific test skills (ia-php-laravel, ia-react-frontend, etc.) which handle tooling and convention; this skill covers the why and what.

inputs

development environment:

• source code repository with a test runner installed (jest, vitest, phpunit, pytest, rspec, etc.)
• test database or ephemeral test container setup (if testing data layers)
• access to the original requirements (spec, issue, PR description, user story)
• the code diff or feature branch under test

context:

• feature specification or bug report (what behavior is being tested)
• implementation details (what code changes were made)
• any claims made in the PR description or response (what's being told to the user as working)
• existing test coverage baseline (how many tests exist, ratio of unit/integration/e2e)

external connections (if applicable):

• test database: ephemeral containerized instance or in-memory database (preferred over shared persistent db to prevent state contamination)
• framework test utilities: Laravel Queue::fake(), Event::fake(); React test providers; Vitest vi.mock() for API boundaries
• logging/observation system: any logger or error sink the test needs to assert on (for silent failure coverage)

procedure

1. derive test cases from three independent sources

input: feature spec, implementation diff, PR/response claims output: enumerated list of test cases mapped to source

map every feature to exactly one source; anything appearing in any source without a corresponding test is a gap:

• source 1: user requirements (stated spec, issue description, conversation, acceptance criteria)
• source 2: features implemented (scan the code diff; what does the code actually do)
• source 3: claims in the response (what you're about to tell the user works; what the PR description asserts)

for each source, enumerate user journeys: "as a [role], i want to [action], so that [benefit]." generate test cases from each journey.

example: feature "users can reset password"

• requirement: user receives reset link in email
• implementation: code writes reset token to database, calls mailer service
• claimed: "users receive a reset email within 1 minute"
• test cases: (a) valid user triggers reset, token stored; (b) email sent with correct link; (c) reset link redirects to form; (d) invalid/expired token rejected; (e) user who never requested reset cannot reset

any test case without a corresponding test is a gap.

2. name tests by expected behavior, not the function being tested

input: feature or edge case to test output: test name statement

test names must describe what happens, not what's being called. the name should be readable as a sentence stating the expected behavior.

good: "returns 404 when user does not exist" bad: "test getUserById"

good: "sends notification after order is placed" bad: "test processOrder"

good: "rejects input with null email" bad: "test validation"

this forces clarity: if you can't name it in one clear behavior statement, the test probably does too much.

3. enforce one behavior per test

input: test code output: test split into atomic assertions

each test verifies exactly one thing. if the test name contains "and" ("creates user and sends email and updates counter"), split it into separate tests.

each test should be independently readable. a reader should understand what the test verifies without reading other tests or helper functions.

example of too many behaviors in one test:

test("creates user and sends welcome email and updates counter") {
  const user = createUser({ email: "foo@bar.com" });
  expect(user.id).toBeTruthy();
  expect(mailer.send).toHaveBeenCalledWith(expect.stringContaining("welcome"));
  expect(counterService.increment).toHaveBeenCalled();
}

split into three:

test("creates user with valid email") { ... }
test("sends welcome email after user creation") { ... }
test("increments user signup counter") { ... }

4. choose real objects or mocks based on system boundaries

input: dependency being tested (internal service, external API, database, etc.) output: decision to mock or use real object

use real objects for internal code and test infrastructure. use mocks only at system boundaries (external APIs, payment gateways, email delivery, third-party SDKs with rate limits).

• use real objects for: database queries (via test db), internal services and classes, file system operations (via temp dirs), business logic and transformations
• use mocks/fakes for: external HTTP APIs, payment gateways, email/SMS delivery, third-party SDKs with rate limits

exception: framework-provided test doubles are idiomatic and maintained. use them. examples: Laravel Queue::fake(), Event::fake(); React test providers; Vitest vi.mock() for API boundaries.

every mock is an assumption about behavior that may drift from reality. the more you mock, the less you know production actually works.

5. test edge cases systematically

input: feature or code path output: enumerated edge case tests

for every feature, test:

• empty input, null, undefined
• boundary values (0, 1, max int, max+1)
• invalid types (string where number expected, wrong object shape)
• concurrent access (if applicable)
• error paths (network failure, timeout, permission denied, malformed input)
• unicode and special characters in string inputs
• partial success / rollback scenarios (if transactional)

example for a "parse user birthdate" function:

• valid: "1990-05-15"
• empty: "" or null
• invalid format: "15/05/1990" or "may 15"
• future date: "2099-01-01"
• boundary: "1900-01-01" (historic), "2023-12-31" (recent)
• special chars: "1990-05-15\x00" or with emoji
• concurrent: if multiple requests parse simultaneously, no race on shared state

6. assert on outcomes, not implementation

input: test code with assertions output: assertions rewritten to verify results, not call counts

assertions must verify the actual outcome (state changed, response contains expected data, side effect occurred) not that a specific internal function was called. mocking a function and asserting it was called doesn't prove the system works; it proves the mock was wired correctly.

bad (testing mock behavior):

expect(repository.save).toHaveBeenCalledWith(user);

good (testing outcome):

const saved = await database.users.find(user.id);
expect(saved.email).toBe(user.email);

bad (testing call count):

expect(serializer.serialize).toHaveBeenCalledTimes(1);

good (testing output):

expect(response.body).toMatchObject({ id: user.id, email: user.email });

7. cover silent failures explicitly

input: code with error handling (catch blocks, swallowed rejections, converted errors, transactional work) output: tests that prove failures are observable

for every code path that catches, logs, or short-circuits on error, add an assertion that proves the failure was observable. hunt for:

• empty catch blocks: try { ... } catch {} , add a test that triggers the error and asserts the logger was called with the original exception
• swallowed rejections: .catch(() => []), .catch(() => null) , add a test that triggers the rejection and asserts the caller sees a distinguishable signal (return value, logged error, re-thrown)
• converted errors: catch (e) { return defaultValue; } , assert both the return value and that the error was recorded somewhere observable
• missing async handling: a rejected promise inside async function; assert the rejection surfaces as a failure, not an unhandled-rejection warning
• no rollback on transactional failure: assert that a failure mid-transaction leaves no partial state (row count before and after match, queue unchanged)

pattern: instead of expect(result).toBe(null) (which passes for both "handled" and "silent drop"), prefer expect(logger.error).toHaveBeenCalledWith(expect.any(DatabaseError)) , make the observable signal part of the contract.

8. write failing test before fix (for bugs)

input: confirmed bug report with reproduction steps output: failing test that reproduces the bug, then passing test after fix applied

for bug fixes, the two-run sequence is non-negotiable proof:

• write a test that reproduces the bug
• run it and watch it fail; confirm it fails for the right reason (not a typo or import error). the failure message should describe the buggy behavior
• apply the fix to the source code
• run the test again and watch it pass; confirm the fix addresses the specific failure and other tests still pass

if the test passes immediately without a fix, the test is verifying existing behavior, not the bug. go back and rewrite the test.

skipping the first run means the test might pass for reasons unrelated to the fix. a fix without a regression test is a fix that will break again.

9. write tests alongside new features

input: feature implementation in progress output: tests existing and passing by feature completion

write tests as you build, not after. "i'll add tests later" means "i won't add tests."

when making a test pass, write the simplest code that satisfies it. not the abstraction you think is "right," not the feature you imagine you'll need next. the simplest thing. refactor only after the test is green (red-green-refactor).

by the time the feature is done, tests exist and pass. whether you wrote the test 5 minutes before or 5 minutes after the code matters less than whether the test exists and is good.

10. maintain test pyramid ratios

input: test suite for a feature or service output: rebalanced test distribution if skewed

aim for ~80% unit, ~15% integration, ~5% e2e. adjust based on project risk profile (data pipelines may need heavier integration; CLI tools may need minimal e2e).

• unit tests (~80%): fast, isolated, test one behavior. run in milliseconds. no database, no network, no filesystem. these form the foundation. cheap to write, cheap to run, fast feedback.
• integration tests (~15%): verify component boundaries. api endpoints hitting real test database, service layers wired to real dependencies, queue producers and consumers together. slower than unit but catch wiring bugs mocks hide.
• e2e tests (~5%): validate critical user paths end-to-end through real system. expensive to write, slow to run, brittle to maintain. limit to high-value flows (signup, checkout, core workflow). every e2e test must justify its maintenance cost.

measure coverage by test count and expected runtime. if 40% of tests are e2e and each runs 5+ seconds, test suite is too slow for frequent feedback.

11. detect and reject anti-patterns before commit

input: completed test code output: test code scanned for anti-patterns, refactored or deleted

scan for these before committing:

• mock of the system under test: mocking the very function being tested so the test asserts what the mock returned. always a mistake. delete the mock; call the real function.
• circular assertion: computing the expected value the same way the code computes the actual value (expect(sum(a,b)).toBe(a+b)). the test passes even when both are wrong. replace with a hand-computed expected value or known fixture.
• snapshot of unreviewed output: first-run snapshot committed without reading it. the snapshot enshrines whatever the code happened to emit, bugs included. hand-write the first snapshot or diff it line by line before accepting.
• assertion-free exercise: test calls the function, checks nothing, passes because nothing threw. every test needs at least one expect(...) tied to the behavior under test.
• over-broad matchers: expect(result).toBeTruthy() on a function returning an object. passes for {}, true, "anything" equally. pin to the specific shape: expect(result).toEqual({ id: 123, name: "foo" }).
• implementation-echo assertions: expect(repo.save).toHaveBeenCalledTimes(1) when the real contract is "the user exists in the database afterward." assert outcomes, not call counts.
• incomplete mocks: mock includes only the fields the test author knows about. downstream code consumes other fields and gets undefined. mock the complete data structure as it exists in reality, not just the fields the immediate test uses. before creating a mock response, check what fields the real API/type contains. include all fields the system might consume downstream.
• test-only methods in production code: methods like reset(), clearState(), setTestMode() that exist only because tests need them. if tests need to reset state, the code has a design problem. refactor to make state explicit and injectable.
• testing the framework: tests verify that the ORM saves records, the router routes requests, or the framework does what its docs say. trust the framework. test your logic, the business rules, transformations, and decisions your code makes.
• snapshot as the only test: all tests are snapshots that get bulk-updated whenever anything changes. snapshots catch unintended changes but don't verify correctness. add behavioral assertions alongside snapshots.
• mocking without understanding: before mocking any method, ask: (1) what side effects does the real method have, (2) does this test depend on any of those side effects, (3) mock at the lowest level that removes the slow/external part. if you can't answer (1), don't mock.
• persistent test infrastructure state contamination: integration tests fail with row-count multipliers (expected 2 rows, got 8; expected 3 jobs, got 12). same test passes in ci on fresh container but fails locally. root cause: long-running docker compose, shared local database, or volume left between iterations. expected vs. actual differs by clean integer multiple (2x, 3x, 4x). fix: use ephemeral containers per test session (testcontainers, pytest-postgresql, docker compose run --rm) or truncate/drop database in fixtures between tests. never rely on tests "cleaning up after themselves."
• vacuous forall over empty collection: assertion over a model's child collection (every, all, .iter().all()) passes but the factory never attached children. every such operator returns true over empty collection. when an assertion's truth depends on a child collection being non-empty, attach a realistic child set explicitly and confirm the predicate actually flips for at least one populated case.
• constructing object-under-test below the layer that transforms it: the fix guards or transforms a field in an upstream layer (parser, normalizer, from_api_response constructor, serializer), but the test builds the object directly via the leaf constructor injecting the already-correct value. upstream transform never runs. fix: enter through the same entry point production uses, drive the test from the input the upstream layer actually receives.
• synchronous adapters hide timing-dependent races: test fires two or more parallel requests through a mock that resolves synchronously and asserts a coalescing/dedup/single-flight guard. it passes only because every call observed shared in-flight state before any reset. under real wire latency staggered arrivals miss the window. fix: don't treat same-tick microtask concurrency as proxy for production burst. inject controllable latency (fake timers, deferred resolution staggered across ticks) so later arrival lands after reset.
• asserting only presence, never absence: tests assert positively on fields that should be there and never assert unexpected fields are absent. when a shared builder is reused across contexts, new field leaking into wrong payload passes every existing test. fix: pin absence as well as presence. assert "proof_document_id" not in payload.

12. damp over dry: readable duplication beats hidden setup

input: test code with shared setup output: setup extracted only when it genuinely reduces noise without hiding intent

each test should be independently readable without chasing shared setup through helper functions. duplication in tests is acceptable, even desirable, when it makes the test's intent obvious at a glance.

extract shared setup only when it genuinely reduces noise without hiding what the test does.

bad (helper obscures intent):

function setupUser() {
  const user = new User();
  user.email = "test@example.com";
  user.verified = true;
  user.tier = "premium";
  user.createdAt = new Date("2020-01-01");
  return user;
}

test("allows premium user to export data") {
  const user = setupUser();
  expect(canExport(user)).toBe(true);
}

good (duplication acceptable here):

test("allows premium user to export data") {
  const user = new User({
    email: "test@example.com",
    verified: true,
    tier: "premium",
    createdAt: new Date("2020-01-01")
  });
  expect(canExport(user)).toBe(true);
}

acceptable helper:

function createPremiumUser(overrides = {}) {
  return new User({
    email: "test@example.com",
    verified: true,
    tier: "premium",
    createdAt: new Date("2020-01-01"),
    ...overrides
  });
}

test("allows premium user to export data") {
  const user = createPremiumUser();
  expect(canExport(user)).toBe(true);
}

test("blocks free user from export") {
  const user = createPremiumUser({ tier: "free" });
  expect(canExport(user)).toBe(false);
}

the helper reduces repetition without hiding what a "premium user" looks like.

decision points

if writing a test for a bug: write the failing test first, run it to confirm it fails for the right reason, apply the fix, then run it to confirm it passes. skip this sequence only if impossible (e.g., test infrastructure doesn't exist yet). if the test passes without the fix, rewrite it; it's testing existing behavior, not the bug.

if test setup is complex or large: simplify the interface being tested, not the test. if a test requires 20 lines of setup to verify one behavior,