ClaudeTestingLevel 3: Workflows

How Do You Make Claude Test Behavior, Not Implementation?

Write the behaviors as plain sentences yourself, and ask Claude to test those, with mocks allowed only at real boundaries such as the network, disk or clock. Anthropic's docs give the same core advice: when you ask for tests, be specific about what behavior you want to verify.

Prompt to copy
Write tests for [unit, with path]. Test these behaviors, and only these:
1. [Given X, it does Y]
2. [Given Z, it rejects with error E]
3. [...]

Rules:
- Assert what a caller can observe: the return value, the error, or the effect on [database / response / queue].
- Mock only what crosses a real boundary: [network, clock, payment provider]. Use the real versions of our own modules.
- Don't assert on private methods, or on call order unless I listed it above.
- One behavior per test, named with the sentence above.

Then run them and show the output. If one of my behaviors doesn't match what the code does, don't change the test to fit. Tell me which one is wrong.
Do
  • Assert the 6th request is rejected
  • Mock only network, disk or clock
  • Write the behavior sentences yourself
Don't
  • Assert bucket.refill() was called
  • Derive tests by reading the code
  • Let a mock-heavy suite set the style
A rule of thumb, not an Anthropic chart, shown with a rate limiter that allows 5 requests a minute.

Try it now

  1. 1Write three to five sentences in the form an expired token is rejected with a 401.
  2. 2Paste the prompt with those sentences and your test command.
  3. 3Then ask rename the private helpers in [file] and inline one of them without changing behavior, run the tests, show the output, then undo that refactor.
  4. 4The tests should stay green through that. Any that go red are tied to the implementation, so ask Claude to rewrite those.

Use it when

API handlers, service boundaries, reducers and pure functions, especially before a refactor you've planned. Also a suite that goes red on every internal change, which teaches people to stop trusting it.

Skip it when

When the interaction is itself the promise, such as charge the card exactly once or send no email to a user who opted out. Asserting that call is right. Also skip it when you're pinning legacy code before changing it, since the aim then is to capture what the code does today, bugs included.

Why it works

A test that asserts internal calls fails when you refactor, even if nothing a user can see has changed, and it can pass while the outcome is wrong. Claude Code examines your existing test files to match their style, frameworks and assertion patterns. That helps when your suite is good, but it means a suite full of mocks is what it has to copy unless you say otherwise. There's also a risk specific to generated tests. Rule of thumb, not a vendor claim: a test written by reading the code describes what the code does, so a bug can get recorded as expected behavior. Writing the sentences first gives the test a source other than the code.

Example

For a rate limiter that allows 5 requests a minute, your sentences might be the 6th request in a minute is rejected and a request after the window is allowed. The tests use a fake clock, because time is a real boundary, instead of asserting that bucket.refill() was called. If you later rewrite the limiter from a token bucket to a sliding window, those two tests should still apply unchanged. A spy on refill() wouldn't survive it.

Going further

To avoid repeating the rules, put them in a path-scoped rule. A file at .claude/rules/testing.md with paths: frontmatter such as "**/*.test.ts" loads only when Claude works on matching files. Add lines such as Mock only the network, disk and clock. That's context, not enforcement, so add a check for what matters: use a subagent to compare the new tests with this behavior list, report tests that assert internals, and skip style. A reviewer that didn't write the tests doesn't share the reasoning behind them.

Common mistakes

  • Letting Claude work out the behaviors from code it just wrote, so the tests describe the code, bugs included.
  • Accepting a wall of mocks because it passes. When every collaborator is mocked, the test mostly checks its own setup.
  • Asserting log lines or call counts where you could assert the actual result.
  • Packing six behaviors into one test, so a failure doesn't tell you which promise broke.

Sources

Checked 6 November 2026. Products change often, so confirm details with the vendor.

Related

Beyond the course