Writing Tests

intent

this skill teaches test-writing discipline across any language or framework. tests prove behavior works; a test that can't fail is worthless, and a test that mocks the system under test is theater. use this skill when writing new tests, adding coverage to existing code, fixing failing tests, or reviewing test quality. pair it with language-specific skills (ia-php-laravel, ia-react-frontend, etc.) for framework conventions and tooling.

inputs

• repository structure and test discovery: where tests live, how they're named, which files the test runner scans
• test runner and config: the project's test command (pytest, phpunit, vitest, jest, etc.), its config file (pytest.ini, phpunit.xml, vitest.config.ts), and the project-local wrapper if one exists (uv run pytest, vendor/bin/phpunit)
• CI/CD pipeline: the test command your CI gates on (.github/workflows/*.yml, .gitlab-ci.yml, etc.) -- authoritative over README when they disagree
• source code and requirements: user requirements (spec, issue, conversation), the diff of implemented features, and the code being tested
• framework test utilities: if using a framework with idiomatic test doubles (Laravel Queue::fake(), React test providers, vi.mock for API layers), familiarize yourself with them -- they're maintained alongside the framework and reduce mock drift
• external service contracts: documentation or schema for any real external services (API specs, database schemas, payment gateway docs) you'll mock or stub -- incomplete mocks fail in production

procedure

step 1: establish test discovery and runner before writing tests

inputs: repository root, CI pipeline file, readme outputs: confirmed test command, runner invocation, test file locations

discover what the repository actually runs, not what seems default.

1. locate the test-config manifest for your ecosystem (pytest.ini, phpunit.xml, vitest.config.ts, tsconfig.json under test, etc.)
2. identify the project-local wrapper over any global binary (uv run pytest vs bare pytest, vendor/bin/phpunit vs phpunit, node_modules/.bin/vitest vs vitest). prefer the wrapper -- global binaries drift from pinned versions
3. check .github/workflows/*.yml or equivalent CI config for the exact test command CI gates on. if CI command differs from README, CI is authoritative
4. confirm test file naming convention and location by scanning existing tests (tests/, tests/, spec/, *_test.py, *.spec.ts, etc.)
5. learn both focused and full invocation forms: one file or one test for the edit loop, whole suite for completion (pytest tests/user_test.py vs pytest, phpunit tests/UserTest.php vs phpunit)
6. run the full test suite once to confirm no pre-existing failures block your work

step 2: derive test cases from three independent sources

inputs: user requirements doc or issue, code diff, existing API/data contracts outputs: enumerated test cases mapped to each source with no coverage gaps

build coverage depth and breadth by sourcing from three independent streams, then verify every item maps to at least one test.

1. from user requirements: extract user journeys ("as a [role], I want to [action], so that [benefit]") from spec, issue, or conversation. generate one test case per journey or atomic action
2. from implemented features: scan the code diff and production code. list every new function, endpoint, branch, state transition, and error handler. each gets a test case
3. from claimed behavior: examine responses, docs, and error messages the code is about to report. every claim ("user created successfully", "duplicate email rejected", "rollback on failure") gets an assertion test
4. map each test case to a test name and describe the assertion (see step 4 for naming)
5. flag any item in any source with no corresponding test as a coverage gap -- implemented-but-untested features are debt

step 3: write test names that describe expected behavior, not method calls

inputs: test case from step 2 outputs: test name and a one-line assertion statement

test names are first-level documentation. a reader should know what happens without opening the test body.

1. write the name as "expected behavior when condition": returns 404 when user does not exist, sends notification after order placed, rejects duplicate email, increments counter on successful save
2. scan for anti-patterns: avoid test method name (test_getUserById), avoid implementation detail (calls repo.save), avoid vague assertions (works correctly)
3. if the name needs "and" in it, split into two tests -- each test verifies one thing

step 4: decide whether to use real objects or mocks

inputs: feature being tested, available test infrastructure (test DB, temp dirs, framework utilities) outputs: decision to use real object or mock, with rationale

mocks are a last resort, not first choice. every mock is an assumption about behavior that may drift from reality.

use real objects for	use mocks/fakes for
database queries (use ephemeral test DB)	external HTTP APIs
internal services and classes	payment gateways
file system operations (use temp dirs)	email/SMS delivery
business logic and transformations	third-party SDKs with rate limits
queues, caches, time-based logic (use framework test doubles)	hard-to-reach error states

exception: framework-provided test doubles (Laravel Queue::fake(), React test providers, vi.mock for API layers) are idiomatic and maintained alongside the framework -- use them. this rule targets hand-rolled mocks that drift.

if mocking is unavoidable, generate the mock from the real type/schema and include all fields consumed downstream, not just the ones the test author knows about. incomplete mocks hide bugs until production.

step 5: write the test body with one assertion per test case

inputs: test name, decision on real/mock, test setup outputs: complete test with explicit assertion

each test verifies exactly one behavior.

1. set up preconditions: create fixtures, inject dependencies, configure the system to the state needed for the test
2. execute: call the function, method, or endpoint under test once
3. assert: use one primary assertion that captures the expected outcome. assertions on outcomes (row exists in DB, response body contains expected fields, error was logged) beat assertions on internal mechanics (mock was called N times)
4. for error-path tests and silent-failure coverage (step 7), assert not just that an error occurred but that it was observable (logger.error was called, specific return value, re-thrown, etc.)

step 6: minimize test setup noise while keeping tests independently readable

inputs: test case, multiple similar tests outputs: test code with shared setup extracted, no hidden test intent

duplication in tests is acceptable, even desirable, when it makes intent obvious. extract shared setup only when it reduces noise without hiding what the test does.

1. if five tests all create a user with the same email, extract a helper or fixture factory
2. if the extracted helper reads like noise (buildTestContext, setupDatabase), inline it back and accept duplication
3. each test should be independently readable without chasing setup through helper chains -- a reader should understand the test intent within 30 seconds

step 7: cover edge cases and silent failures

inputs: feature being tested, error paths and boundary conditions outputs: test cases for empty/null, boundaries, errors, and error observability

for every feature, enumerate and test these categories:

edge cases: empty input, null/undefined, boundary values (0, 1, max, max+1), invalid types (string where number expected), concurrent access (if applicable), unicode and special characters, permission denied, timeout, network failure

silent failure coverage: hunt error paths where failures can be swallowed. for each one, add an assertion that proves the failure was observable:

• empty catch blocks (try { ... } catch {}) trigger the error; assert logger received the exception
• swallowed rejections (.catch(() => []), .catch(() => null)) trigger the rejection; assert the caller sees a distinguishable signal (specific return value, logged error)
• converted errors (catch (e) { return defaultValue; }) assert the return value AND that the error was recorded where an operator can find it
• missing async handling assert a rejected promise inside the function surfaces as a failure, not just an unhandled-rejection warning
• no rollback around transactional work assert mid-transaction failure leaves no partial state (row counts match, queue unchanged)

use specific assertions: instead of expect(result).toBe(null) (passes for both "handled gracefully" and "silent drop"), prefer expect(logger.error).toHaveBeenCalledWith(expect.any(DatabaseError)) -- make the observable signal explicit.

step 8: run tests in the order specified by red-green-refactor

inputs: test written (or test + code together for new features) outputs: passing test, clean refactor (if applicable)

for bug fixes (prove-it pattern):

1. write a test that reproduces the bug
2. 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
3. apply the fix
4. run it and watch it pass -- confirm the fix addresses the specific failure and other tests still pass. a fix that breaks something else isn't a fix
5. if the test passes immediately without a fix, the test is verifying existing behavior, not the bug -- go back to step 1

for new features: write tests alongside implementation, not after. by the time the feature is done, tests exist and pass. when making a test pass, write the simplest code that satisfies it (not the abstraction that seems "right", not the feature that might be next). refactor only after the test is green.

step 9: verify test quality and independence before merge

inputs: all tests written outputs: checklist confirming coverage, naming, real objects, edge cases, speed, independence

before considering tests complete, check:

• every new public function/endpoint has at least one test
• each test has a descriptive name stating expected behavior
• tests use real objects where possible (mocks only at system boundaries)
• edge cases covered (empty, null, boundary, error paths)
• tests assert on outcomes, not implementation details or call counts
• tests are independent -- no shared mutable state. if tests pass individually but fail together, use bisection to find the polluter (run one-by-one until you find the offending test)
• tests run fast enough to run frequently (unit suite under 30 seconds, integration suite under 2 minutes)
• bug fix tests reproduce the original bug and pass only after the fix

step 10: scan for ai-generated test smells before commit

inputs: all tests, especially any written with LLM assistance outputs: corrected tests with smells removed

before committing any test (including self-written), scan for these six smells:

• 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)). test passes even when both are wrong. replace with hand-computed expected value or known fixture
• snapshot of unreviewed output: first-run snapshot committed without reading it. 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(...) / assert ... tied to the behavior under test
• over-broad matchers: expect(result).toBeTruthy() on a function that returns an object. passes for {}, true, "anything", all equally. pin to the specific shape
• implementation-echo assertions: expect(repo.save).toHaveBeenCalledTimes(1) when the real contract is "user exists in database afterward." assert on outcomes (row exists, response contains expected fields), not call counts or internal method invocations

decision points

if you don't know the test runner for this project: discover it before writing tests (step 1). a globally installed binary often resolves to a different version than the project pins. always use the project-local wrapper if one exists.

if the test command in CI differs from the README: follow CI. CI is authoritative because it's what gates code.

if you're unsure whether to test an internal implementation detail or a user-visible outcome: test the outcome. tests that verify framework behavior (the ORM saves records, the router routes) are waste -- trust the framework. test the project's own logic (business rules, transformations, decisions).

if you're tempted to write a test-only method in production code (reset(), clearState(), setTestMode()): stop. if tests need to reset state, the code has a design problem. refactor to make state explicit and injectable.

if you must mock a method but don't know what the real method returns: check the API docs or type definition, then populate the mock with all fields consumed downstream, not just the ones you know about. incomplete mocks fail silently in production.

if a snapshot test is the only test for a feature: add behavioral assertions alongside snapshots. snapshots catch unintended changes but don't verify correctness.

if integration tests fail with row-count multipliers (expected 2 rows, got 8) yet pass on a fresh container: persistent infrastructure kept state from prior runs. reset infrastructure state between runs (ephemeral containers, fixture TRUNCATE, volume teardown) instead of relying on tests cleaning up after themselves.

if tests pass individually but fail together: use bisection to find the polluter. run tests one-by-one in isolation until you find the test with shared mutable state.

if a test is too complicated to write: simplify the interface being tested. if test setup is large, extract helpers that reduce noise without hiding intent. if you must mock everything, code is too coupled -- use dependency injection.

if you're about to skip, defer, or argue against writing a test: load the rationalization table (references/rationalization-table.md) first. thirteen common excuses with counter-truths. if you're still arguing, the argument is probably lost.

output contract

success looks like:

• all tests pass (both locally and in CI)
• test output confirms expected coverage: all new public functions/endpoints have at least one test
• test names are descriptive enough that a reader knows expected behavior without opening the test body
• tests use real objects or framework-blessed test doubles, not hand-rolled mocks at code boundaries
• test suite runs in acceptable time (unit suite under 30 seconds, integration under 2 minutes)
• bug fix tests reproduce the original bug before the fix is applied
• no tests assert on internal implementation details, mock call counts, or framework behavior

file locations:

• tests live in the project's standard location per its convention (tests/, tests/, spec/, *_test.py, *.spec.ts, etc.)
• test runner config (pytest.ini, phpunit.xml, vitest.config.ts) is checked in at the project root
• CI pipeline file (.github/workflows/*.yml, .gitlab-ci.yml) declares the test command

outcome signal

you know the skill worked when:

• you can run the entire test suite using the project's test command (uv run pytest, vendor/bin/phpunit, npm test, etc.) and all tests pass
• the test output shows coverage of new code, not just happy paths -- edge cases, error conditions, and boundary values are tested
• a failing test immediately tells you what went wrong (descriptive name, clear assertion failure) without requiring you to read the test body
• when you break the code intentionally, at least one test fails and describes the broken behavior
• when you run the suite twice in a row, results are identical (no flaky tests, no shared state contamination)
• a new team member can read a test name and understand what behavior is being verified before opening the file
• mocking is limited to system boundaries (external APIs, payment gateways, email services) and internal logic uses real objects or framework test utilities
• when a test uncovers a bug, you fix the code, not the test

anti-patterns to avoid

reaching for a default test command: the bare global runner passes locally while CI invokes the project wrapper and fails. discover the runner, wrapper, and CI command first.

testing mock behavior instead of real behavior: test passes but production breaks. mocks assert correctly but actual system fails. replace mocks with real objects for internal code.

test-only methods in production code: methods like reset(), clearState(), setTestMode() exist only because tests need them. refactor to make state explicit and injectable.

snapshot tests 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.

testing the framework: tests verify the ORM saves records, the router routes, or the framework does what its docs say. trust the framework. test the project's own logic.

incomplete mocks: mock includes only fields the test author knows about. downstream code consumes other fields and gets undefined. mock the complete data structure as it exists in reality.

mocking without understanding: before mocking, 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.

persistent test infrastructure state contamination: integration tests fail with row-count multipliers (expected 2 rows, got 8) yet pass on a fresh container. reset infrastructure state between runs (ephemeral containers, TRUNCATE, volume teardown). never rely on tests cleaning up after themselves.

vacuous forall over an empty collection: forall-style assertion (every, all, .iter().all()) passes vacuously -- the factory never attached children. attach a realistic child set and confirm the predicate flips for at least one populated case.

constructing the object-under-test below the transform layer: the fix lives in an upstream transform (parser, normalizer, from_api_response), but the test builds the object via the leaf constructor with the already-correct value. feed the test the raw pre-transform input so the transform under test executes.

synchronous adapters hiding timing-dependent races: parallel requests through a zero-latency mock settle in the same microtask, so a dedup guard passes. under real wire latency, staggered arrivals miss the window. inject controllable latency; assert the guard holds for arrival-staggered bursts.

asserting only presence, never absence: payload tests assert expected fields exist but never that unexpected fields are absent. pin absence as well as presence: assert "proof_document_id" not in payload.

integration

this skill covers generic test discipline. for framework-specific patterns, conventions, and tooling:

• Laravel/PHP → ia-php-laravel (PHPUnit, factories, feature/unit split, facade faking, data providers)
• React/TypeScript → ia-react-frontend (Vitest, RT