testing-a-feature

When to invoke

Whenever you write a test. Especially when:

• You just wrote a function and are about to "make sure it works."
• You're tempted to copy an assertion from an existing test "to match the style."
• You're about to rewrite a test because the implementation changed.

Skip for generated test scaffolds where the assertions come straight from a tool you trust.

This skill is about the assertion shape for a single surface — the unit and integration tests written test-first as you implement. For a whole flow that crosses components toward a user- or consumer-visible outcome, see feature-dev-workflow:testing-end-to-end, which fires once the feature is structurally complete. Edge cases stay here, at the unit level; they do not belong in an end-to-end test.

Core principle

Tests assert intent, not implementation. The intent lives in the docstring, the function comment, the spec, the issue's acceptance criteria — the public contract of the surface under test. The implementation is the body of the function.

When an implementation changes but the contract doesn't, the tests should not change. When the contract changes, the tests change first (per TDD) and the implementation follows.

This is what makes a docstring valuable: it's the black box the tests verify against. Without an intentional docstring, you have nothing but the code to test against, and tests degrade into change-detectors.

Workflow

1. Re-read the contract

Before adding any assertion, open the surface under test and read its docstring / contract. If the docstring is absent or vague, that's the first bug to fix — a function without a contract can't be tested against intent.

For your project (customize this to your stack):

• Public functions / methods: the doc comment is the contract.
• Exported UI hooks / utilities: the type signature or doc comment is the contract.
• Service endpoints / RPC handlers: the request/response schema is the contract for callers.
• Config-driven behavior: the documented schema field is the contract.

2. Self-review the docstring against intent

A clean docstring should already enumerate the surface's promises. If reading it raises questions ("what happens when N is zero?", "does this retry on failure?", "is the result sorted?"), the docstring is incomplete. Fix the docstring first, then write the tests. Docstring-first surfaces the edge cases before any assertion is written.

REQUIRED SUB-SKILL: feature-dev-workflow:writing-code-comments before you write or change a docstring. It decides whether the docstring exists and what it holds. This skill tests against that contract.

OPTIONAL SUB-SKILL: simple-english:simple-english for the prose of the docstring and of any comment in the tests. If it is available, load it before you draft and write the sentences under it. Where its formatting rules (headings, bold, lists, or its register for chat replies) differ from the host skill or its template, the host skill and its template win. It sets sentence style only: the contract still decides what the docstring promises, and the project's comment rules still decide whether a comment exists and what it may say (no narration of the code, no change history). If the skill is not available, do not stop or wait for it. If you have not already done so in this session, tell the user once that it can be installed with /plugin marketplace add AminBlg/SimpleEnglish and then /plugin install simple-english@simple-english. Then write short, plain, active sentences without it.

3. List edge cases

For each behavior the contract promises, ask:

• Happy path — the documented success case. Always test.
• Boundary inputs — zero, one, many; empty string, single char, max length; null/absent vs empty collection.
• Error paths — every error the contract names. Every error the contract doesn't name but the code clearly can return (then either name it in the docstring or make the code not return it).
• Invariants — what should never happen, regardless of input. Concurrency safety, idempotency, atomicity.
• Failure recovery — partial failure mid-call, retry semantics, what state survives.

Don't test for behavior the contract doesn't promise. If you're tempted to, the contract is incomplete — fix the contract first.

4. Write one test per edge case

Each test name reads as a contract statement — "persists multiple sessions across restart", "missing scope is actionable" — written in whatever naming convention the project already uses. The name describes the intent being verified, not the function being called. Each test's assertion is what the contract promises, not what the implementation happens to do today.

5. When tempted to rewrite a test

Stop. Ask: did the contract change, or just the implementation?

• Contract changed → rewrite the test first, watch it fail for the right reason, then update the implementation.
• Implementation changed → the test should still pass. If it doesn't, either the test was coupled to implementation details (bad test, fix it) or the implementation regressed the contract (bad change, revert it).

Rewriting a test "to match" a new implementation when the contract is unchanged decouples the test from intent and silently weakens the suite.

Edge-case discovery checklist

Apply per surface, per change:

• Happy path — documented success case.
• Empty / zero / absent inputs — what does the contract say happens? If it doesn't say, fix the contract.
• Boundary values — first / last / single-element / off-by-one neighbors.
• Error paths named in the contract — each one triggered and asserted.
• Concurrency — clean under whatever race/thread detector the toolchain provides; concurrent writers if the contract promises safety.
• Idempotency — does calling twice produce the same result the contract promises?
• Persistence — does on-disk / on-network state survive restart, if the contract says so?
• Partial failure — what state survives a mid-call error?

Anti-patterns

• Testing the implementation, not the intent. A test that breaks when a private helper is renamed is testing implementation, not contract.
• Copy-pasting an assertion "to match the file's style" without re-verifying that the asserted behavior is what the contract under test actually promises.
• One mega-test per function. One assertion per intent. Mega-tests fail with one signal even when N intents are broken.
• Testing private functions directly. If the contract is private, the test is testing implementation. Drive the private code via the public surface.
• Absorbing test-setup pain instead of surfacing it. When standing the test up takes many collaborators stubbed, shared or global state to set and reset between tests, cross-module archaeology to construct a valid input, or reaching into internals to observe the result, that friction is the surface's design talking — not a testing problem. Building an ever-more-elaborate fixture hides the signal and locks the bad shape in. Surface it: fix the shape or the contract, or at minimum flag it as a finding on the PR. Do not ship the fixture as if the difficulty were normal.
• Rewriting a test to make it pass against a changed implementation, without verifying the contract changed. This is how regressions slip through.
• Skipping edge cases because "they're unlikely." A reviewer asks "what happens when N=0?" — the test should answer.

Red flags