principle-test-behavior-not-implementation
Use when writing or changing a test, or deciding whether one should stay. Check what callers can see through the interface they call, so the test breaks when behavior breaks and survives changes to internals alone.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- principle-test-behavior-not-implementation
- description
- Use when writing or changing a test, or deciding whether one should stay. Check what callers can see through the interface they call, so the test breaks when behavior breaks and survives changes to internals alone.
- disable-model-invocation
- true
03 SKILL.md 正文
Test behavior, not implementation
A test should check results visible to the code's users via the interface they call. It should fail once that visible behavior breaks and stay green when nothing but the internals move.
When it applies
Writing a test, changing one, or deciding whether to keep one.
Terms
- Users: callers, end users, and other services.
- Behavior: whatever users can observe. That covers return values, thrown errors, state they can read back afterwards, and effects on external systems (an outgoing request, a database row, a published message).
- Implementation: everything they cannot see, meaning private helpers, the order of internal calls, intermediate data, and which internal component performed the work.
What to do
- Run two thought experiments on each test.
- Break the behavior. Return a wrong value, drop an effect, or duplicate one. If the test stays green, it shows nothing. Usual reasons: the assertion is weaker than the contract, the expected value came from the code being tested, the test restates a constant or prompt string without running the code that uses it, or it asserts on data the test built itself.
- Restructure the internals while keeping every observable result. If the test fails, it is pinned to implementation. It will need rewriting on every refactor and catches no bugs.
- Keep a test only if it catches the first change and tolerates the second. Rewrite or remove the others.
- To write a good test, exercise the code through the interface its users call, using a concrete input. Work out the expected result by reading the requirement, never by running the code, and assert precisely what the contract guarantees.
- Let the contract, not assertion style, decide what counts:
- If the promise is that a request without a valid token never reaches the database, asserting the database client received no query is behavior. Pair it with a positive case where a valid token does produce a query, so the test demonstrably can observe calls.
- The payload sent to a mocked external service is behavior, because that service receives it. Calling an internal helper is an implementation detail.
- An empty list is a precise expected value when nothing should match. It is a hollow assertion when the test only needed some result.
- Callers do not read the exact wording of an error message. They branch on the error type, so the type is the contract. For an auth failure, assert the
Unauthorizedtype and the 401 status, not the sentence.
- A test can pin an invariant rather than a call: for instance, a key required in both of two tables, or a type assertion checked at compile time. Here the invariant is the behavior.
Security tests are where hollow assertions do the most damage. A test named test_rejects_path_traversal that sends ../etc/passwd and asserts "an exception was raised" passes when the code crashes for an unrelated reason. Assert the specific rejection and add a positive case that reads a legitimate file through the same path.
The failure it prevents
Tests that never catch bugs, tests that break on every refactor, and expected values that confirm themselves.
Done when
Each kept test passes both thought experiments.
Related: principle-migrate-callers-then-delete-legacy-apis, principle-foundational-thinking, tdd.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.