test-writer

When to use

• User points at a file, function, or class and asks for tests.
• A bug was just fixed and a regression test is needed.
• Coverage report flagged an untested branch and the user wants it filled.
• New function was added alongside a feature and the PR review asked for tests.

Do not use this skill to design a test strategy for an entire service (use a broader testing-strategy skill) or to write end-to-end browser tests (those require a separate harness skill).

Inputs

• Target under test: a file path, or a file path plus a list of function/class/method names.
• Optional: a specific bug description ("reproduce this failure mode first, then fix-verify") or a branch in the code that must be covered.

Outputs

• One or more test files placed where the repo's convention expects them.
• Every new test function follows Arrange-Act-Assert, names the behaviour, and is deterministic.
• A short summary listing each test added with the behaviour it pins down and the branch it covers.

Tool dependencies

• Read, Glob, Grep for inspecting the existing test suite.
• Edit / Write for creating or updating test files.
• Ability to run the project's test command (the user should run it — do not assume a sandbox).

Procedure

1. Locate existing tests. Use Glob on common patterns: **/*.test.ts, **/*.spec.ts, **/test_*.py, **/*_test.go, tests/**/*.rs, spec/**/*_spec.rb. Read 2-3 representative files.
2. Infer conventions and record them before writing:
   • Framework (Jest, Vitest, Mocha, pytest, unittest, go test + testify, Rust #[test], RSpec).
   • File location: sibling (foo.ts -> foo.test.ts) vs mirrored tree (src/foo.ts -> tests/foo.test.ts).
   • Naming (describe/it vs test(...) vs class TestFoo vs TestFoo_Bar).
   • Setup/teardown (beforeEach, pytest fixtures, TestMain, TestFixture).
   • Assertion style (expect().toEqual(), assert ==, require.Equal, etc.).
   • Test data: factories/builders vs inline literals vs JSON fixtures.
   • Mocking library if any (jest.mock, unittest.mock, gomock, mockito).
   • Coverage tool and thresholds if configured (jest.config, pyproject.toml [tool.coverage], go test -cover).
3. Read the target code. List every observable behaviour: normal case, each error/return branch, boundary values (0, 1, max, empty, None/null), and every external effect (DB write, event emit, HTTP call).
4. Design one test per behaviour, not one test per method. Name each test after the behaviour: returns 404 when user is missing, not test_get_user_3.
5. For each test apply the AAA template:
   • Arrange: build inputs with the repo's factory/builder or inline; stub collaborators but never the unit under test.
   • Act: one call to the unit under test.
   • Assert: observable outcome — return value, thrown error, published event, DB state, rendered output. Avoid asserting on internal calls unless that is the contract.
6. Make every test deterministic: fake the clock, seed the RNG, fix timezone to UTC, stub network with the repo's chosen library (nock, responses, httptest, wiremock). Never let a test touch the real network or wall clock.
7. Cover the negative space: invalid input, expired token, empty collection, duplicate key, concurrent write (if applicable), cancellation. At minimum add one "sad path" test per public function.
8. For a bugfix, write the failing test first. Confirm it reproduces the bug against the un-patched code (describe this in the summary, e.g. "this test fails at commit abc123").
9. Run the test command. If any test fails that is not an intended reproduction, fix the test — never relax an assertion to make it pass.
10. Emit a summary: new test files, count of tests added, which branches are now covered. Link each test name to the behaviour it pins down.