Test Behavior, Not Implementation
A test calls the code the way its users do and asserts the result they observe against a literal expected value. A test that asserts which calls the code made, or restates a constant the code contains, does neither.
The check: before you keep a test, ask whether it would still pass if every function it imports returned undefined. If yes, it observes no behavior and cannot fail for a defect. Rewrite the assertion or delete the test.
Why: A test that cannot fail for a defect costs CI time and review attention and catches nothing. A constant pin also fails when someone edits the constant or the prompt it restates, so it prevents that edit.
Five shapes that still pass when every imported function returns undefined:
- Weak or no assertion. No
expect, or only toBeDefined, toBeTruthy, not.toThrow, toBeInstanceOf, toBeGreaterThan(0).
- Mock or absence only. Only
toHaveBeenCalled, not.toHaveBeenCalled, toBeUndefined, toEqual([]), toHaveLength(0), not.toBe(wrongValue).
- Self-referential. The expected value comes from the code under test:
expect(f(a)).toBe(f(a)), expect(parsed.url).toBe(buildUrl(...)).
- Constant pin. The assertion restates a hand-maintained constant, config default, table row, or prompt string:
expect(LIMITS.maxTools).toBe(8), expect(PROMPT).toContain("You are").
- Fixture asserts fixture. The assertion reads data the test built or a value computed in
beforeEach, and the subject never runs inside the body.
The fix: call the subject inside the test body with one concrete input and assert the literal output or the observable effect, expect(slugify("Hello, World!")).toBe("hello-world"). For an absence, assert the presence on the other input in the same test. For a constant, test the mechanism that reads it with one input instead of restating the value. For a mock, assert the payload it received or the state after the call, not that it was called. When no such assertion exists, delete the test.
Keep a test of a relation across a table's rows (a key present in two tables, a parent that exists), and a compile-time check in a *.test-d.ts file.
This repository (Asymmetric-al/core)
Vendored from p3-stack (MIT) at commit 09909eb. Provenance is in references/upstream.md. On conflict, the current user request, root AGENTS.md, the nearest nested AGENTS.md, and the matching docs/ai/rules/* rulebook win over this skill.
- Explicit invocation only: use it when the user invokes
/principle-test-behavior-not-implementation (Claude Code, Cursor, T3 Code) or $principle-test-behavior-not-implementation (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.
- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.
Edit this canonical copy in docs/ai/skills/principle-test-behavior-not-implementation/, then run bun run skills:sync and bun run skills:verify.
1---2name: principle-test-behavior-not-implementation3description: "Apply when you write, change, or keep a test. Call the code the way its users do and assert the result they observe against a literal expected value. If the test would still pass when every imported function returns undefined, rewrite the assertion or delete the test."4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/asymmetric-al/principle-test-behavior-not-implementation7---89# Test Behavior, Not Implementation1011A test calls the code the way its users do and asserts the result they observe against a literal expected value. A test that asserts which calls the code made, or restates a constant the code contains, does neither.1213The check: before you keep a test, ask whether it would still pass if every function it imports returned `undefined`. If yes, it observes no behavior and cannot fail for a defect. Rewrite the assertion or delete the test.1415**Why:** A test that cannot fail for a defect costs CI time and review attention and catches nothing. A constant pin also fails when someone edits the constant or the prompt it restates, so it prevents that edit.1617**Five shapes that still pass when every imported function returns `undefined`:**1819- **Weak or no assertion.** No `expect`, or only `toBeDefined`, `toBeTruthy`, `not.toThrow`, `toBeInstanceOf`, `toBeGreaterThan(0)`.20- **Mock or absence only.** Only `toHaveBeenCalled`, `not.toHaveBeenCalled`, `toBeUndefined`, `toEqual([])`, `toHaveLength(0)`, `not.toBe(wrongValue)`.21- **Self-referential.** The expected value comes from the code under test: `expect(f(a)).toBe(f(a))`, `expect(parsed.url).toBe(buildUrl(...))`.22- **Constant pin.** The assertion restates a hand-maintained constant, config default, table row, or prompt string: `expect(LIMITS.maxTools).toBe(8)`, `expect(PROMPT).toContain("You are")`.23- **Fixture asserts fixture.** The assertion reads data the test built or a value computed in `beforeEach`, and the subject never runs inside the body.2425**The fix:** call the subject inside the test body with one concrete input and assert the literal output or the observable effect, `expect(slugify("Hello, World!")).toBe("hello-world")`. For an absence, assert the presence on the other input in the same test. For a constant, test the mechanism that reads it with one input instead of restating the value. For a mock, assert the payload it received or the state after the call, not that it was called. When no such assertion exists, delete the test.2627**Keep** a test of a relation across a table's rows (a key present in two tables, a parent that exists), and a compile-time check in a `*.test-d.ts` file.2829<!-- CORE-OVERLAY-START -->3031## This repository (Asymmetric-al/core)3233Vendored from [p3-stack](https://github.com/uzairansaruzi/p3-stack) (MIT) at commit `09909eb`. Provenance is in `references/upstream.md`. On conflict, the current user request, root `AGENTS.md`, the nearest nested `AGENTS.md`, and the matching `docs/ai/rules/*` rulebook win over this skill.3435- Explicit invocation only: use it when the user invokes `/principle-test-behavior-not-implementation` (Claude Code, Cursor, T3 Code) or `$principle-test-behavior-not-implementation` (Codex), or when an invoked p3-stack skill routes here. Do not route other work to it.36- Confirm before outward-facing or hard-to-reverse actions such as pushing, merging, deploying, deleting, or posting messages, unless the user authorized that action for this task.3738Edit this canonical copy in `docs/ai/skills/principle-test-behavior-not-implementation/`, then run `bun run skills:sync` and `bun run skills:verify`.3940<!-- CORE-OVERLAY-END -->