/test

name: test
description: 'Write or assess tests that prove behavior and would fail without the fix. Use when: writing tests, TDD, or asked whether a green test is enough.'
practices:
- tdd
- property-based-testing
- bdd-gherkin
hexagonal_role: supporting
consumes:
- standards
- repo-context
produces:
- test-evidence
context_rel: []
skill_api_version: 1
user-invocable: true
metadata:
  capabilities: [test]
  effects: [write_test_files, write_test_evidence, modify_source_files]
  canonical_status: canonical
  disposition: keep_specialist
  tier: execution
  dependencies: []
output_contract: behavioral tests and reproducible check facts; coverage results when requested

Test

This skill makes a test assert the effect the behavior promises, with exact values, and shows that the test fails without the fix before it counts as proof. A user sees it worked when the handoff names each test's asserted values and how it was shown failing, or says "not shown".

A green test is evidence for the caller's decision, never the test author's merge approval; the binding verdict belongs to [Validate](../validate/SKILL.md). To only run a known suite, run it directly.

Critical Constraints

• **Assert the promised effect.** Check the state change, outbound call or count

the behavior promises at its boundary, reading a stored record back through the product's own read path unless the stored shape is the contract. Take exact expected values from a literal, worked example or the specification, never the implementation's own formula or a mock's answer: for a 20% discount on 50, assert 40. A status code, a returned object or the absence of an exception alone does not prove the behavior; would the test stay green if the code returned an empty or default result? A rejection test asserts the error its name claims, since another guard can reject the same input.

• **A regression test proves nothing until it fails on the defect.** Show that

it fails on the pre-fix code (see Mutation-kill proof) through the callers, sequence or state that produced the report, not only at the changed line. Until then, report its proof as "not shown"; green alone is not yet proof.

• Derive cases from accepted observable behavior; reuse examples from the

conversation, bead, specification or existing contract before inventing new ones. Keep established domain names; do not unify bounded-context terms by renaming tests.

• Use the repository's framework and real check recipe; keep tests free of

accidental timing, ordering and shared-state dependencies.

• A test that starts green on existing correct behavior is legitimate; use such

tests to pin untested code before changing it, marking an odd result as a suspected defect. Never manufacture a RED claim or alter acceptance to excuse a product defect.

• Repair a discovered defect when already authorized; otherwise report the reproducer and finding, never masking it by deleting or weakening a test ([fix the cause, not the oracle](../implement/SKILL.md#rules-that-decide-the-result)).
• Never refresh a golden or snapshot file to turn a test green. Find the source

change behind the diff; update the artifact only for intended behavior or fixture drift and say why in the handoff; for a bug, fix the generator.

Oracle-strength hierarchy

Prefer exact observable values or errors when known. Use properties or invariants when they express the contract more faithfully than one example. Differential agreement needs an independently credible reference. A smoke check proves only what it observes; it cannot establish an exact behavior by itself. When correctness is a matter of meaning, as for a summary or ranking, a count is only a proxy; judge it as in [proof fidelity](references/proof-fidelity.md#output-judged-for-meaning). Explain a material oracle limit in the native handoff, without creating a worksheet or mandatory report.

Mutation-kill proof

Establish that an important new behavioral check can catch the defect it claims to guard. An authentic pre-fix RED or reproduction is usually sufficient. If a regression test was written after the fix, run it against the pre-fix version (revert the fix in an isolated copy) or use a safe, targeted negative control. Mutate only when that would resolve real doubt about the oracle, then restore and verify the candidate. Do not demand one mutation experiment per table row or new test. Trust a revert or mutation result only from a copy confirmed to hold this candidate's commit and uncommitted changes plus that one edit; a worktree cut from HEAD can lack the fix or test. Never mutate a shared checkout.

Harness health floors

Confirm the runner completed, the intended tests actually ran, and assertions observe the promised behavior. Take the result from the runner's exit status, not its printed output, and keep that status through pipes (`pipefail`): `make test | tail` reports `tail`. A check that edits tracked files has changed the subject; report the edit. Report crashes, truncation, unexpected skips or exclusions as gaps. When runner discovery or failure reporting changed, use a negative control through that same path before trusting green. When the change is itself a check standing in for a real run, also match its context to what it protects ([proof fidelity](references/proof-fidelity.md#a-check-that-stands-in-for-a-real-run)). No need to re-prove an unchanged healthy runner on each edit.

Modes

| Mode | Use when | Result | |---|---|---| | `generate` | Existing behavior needs tests | Useful tests and focused/suite results | | `coverage` | The caller asks to find or fill gaps | Before/after coverage, valuable tests and remaining risks | | `tdd` | The caller asks for TDD on new behavior | A test shown failing without the change, the change, green, then refactor | | `strategy` | The caller wants test design only | Prioritized risks and proposed checks in the existing discussion |

Default to `generate`; mode