Test Code

test-code

Two jobs in one skill: write tests that carry the change, and prove behaviour by observing the real outcome — not by inspecting the diff. A green typecheck proves nothing about behaviour, and a test that only asserts the code compiles is theatre. The bar: every feature and fix carries its test, and every "done" is something you watched happen.

When this applies

Writing or changing a test, adding an end-to-end spec, deciding what to cover, or when asked to verify a change works. Driving the real app by hand for a one-off check is part of this too.

Write a note first

Invoke write-notes and record your answers to this form before you write tests:

• What you're proving: Describe the behaviour the test must pin down — the happy path, the edge, and the error.
• Current coverage: Describe what's already covered and what the existing tests assert, and where the gap is.
• Affected parts: Describe which other parts of the system depend on or share code/state with this change, and how you'll check they still work.
• Layer & observation: Describe how and where you'll watch the behaviour actually happen (red→green, real backend, the real app).
• Risks & unknowns: Describe what you can't verify here and why, and where a passing test might still be lying.

Write tests that carry the change

• Every feature and fix carries a test — happy path + one edge + one error condition, minimum.
• Lock behaviour before you change it. Touching untested code? Write the test that captures today's

behaviour first, watch it pass, then change — now any regression is loud.

• Cover the blast radius, not just the unit. A change ripples — run the suites of the callers and the

modules that share its code or state, and add a case where a dependent would break if your change is wrong. A green test on the changed unit while a neighbour silently breaks is the classic miss.

• Watch a new test go red → green. A test you never saw fail proves nothing: it might assert the

wrong thing, or not run at all.

• Query by role / accessible name, not by test-id or CSS. An accessible-name query doubles as an

accessibility check; a test-id couples the test to implementation details and skips that check.

• Match the project's test conventions. Discover the runner, the file naming and location, and the

shared helpers from the existing tests and the config — don't invent a parallel style the next dev won't find.

Prove behaviour — escalate to match the change

Don't stop at the first green layer:

1. Static — the project's lint/typecheck/test gate. Necessary, never sufficient.
2. Unit / integration — run the suite for what you touched; if it isn't covered, add the test and

watch it go red → green.

1. Backend behaviour — exercise the function on a real backend with real arguments; read the logs

and the returned shape. Inspecting the handler is not verifying it.

1. Frontend / UI — drive the real app: navigate → snapshot → act (locate by role + label) → wait on

authoritative state (a control re-enabling, a reload settling), not on text appearing → assert → screenshot before/after → check the console and network for errors.

1. Codify — turn the manual check into a rerunnable artifact (a spec). Outcome-as-test, not

outcome-as-claim — so it survives in CI and the next change can't silently break it.

Report outcome vs expectation with the evidence attached. If a layer couldn't be verified here (no live backend, a hardware-key login, a fresh-DB first-run), say which and why — an honest "couldn't verify X" beats a false "done".

Before you call it tested

Tick every box, or mark it N/A with a reason. An unticked box means not done.

• [ ] The change is covered — happy path + one edge + one error, and you watched the new test go red → green.
• [ ] The blast radius is covered — the suites of dependents and shared-code neighbours still pass, and a case guards the interaction most likely to regress.
• [ ] Located by role / accessible name, never test-id or CSS (for UI tests).
• [ ] Matched the project's test conventions — runner, file naming/location, shared helpers.
• [ ] Behaviour observed at the right layer — backend exercised on a real backend, UI driven in the real app — not just a green typecheck.
• [ ] Codified as a rerunnable artifact so the next change can't silently break it.
• [ ] Anything you couldn't verify is stated, with why.

Patterns

• On a failing UI step, re-snapshot and re-read rather than blindly retrying the same click —

recover, don't thrash.

• Don't tail-truncate a failing test run. You'll throw away the failure detail you need to fix it.
• A flaky test is a bug. Rule out the environment (timing, CPU starvation, an unstable mock) before

you "fix" logic that was never broken.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tale-project
• Source: tale-project/tale
• License: MIT
• Homepage: https://tale.dev

Install and usage instructions live in the source repository linked above.