# Testing rules for AI agents

> Source: <https://gist.github.com/jakubjanczyk/e9fb16d88b5b69d6ac8671c42fb86f4a>
> Published: 2026-07-01 21:16:56+00:00

| # Testing Rules for AI Agents | |
| ## Intent | |
| - Never decide what "correct" means on your own. Ask for the behavior, or work from the scenarios you were given. | |
| - Before writing code, propose behavior scenarios — group them as happy path / edge / error / non-goals — and wait for the human to approve, cut, and add to them. | |
| ## Writing tests | |
| - Test behavior, not implementation. The test should describe what the system does, never how the code is structured inside. | |
| - Name the test after the behavior. The body is setup → action → expected result. | |
| - A test must be able to fail. Write it first and watch it go red, or temporarily break the implementation to confirm it fails — a test you've never seen fail proves nothing. | |
| - Mock only what you don't own (network, clock, filesystem, third-party APIs). Let the real domain code run. | |
| - Never write a test that just confirms the current (possibly buggy) behavior. If there's no approved spec, ask before asserting. | |
| ## Maintaining tests | |
| - When a test fails, read the message and fix the code — don't edit the test to make it pass unless the expected behavior actually changed. | |
| - If a refactor breaks a test but the behavior didn't change, the test was wrong — fix the test's coupling, don't chase the implementation. | |
| - Keep failures specific: assert on meaningful values and messages, so the next failure says what broke, not just "expected true, got false." | |
| ## Structure | |
| - Put shared setup behind helpers written in domain language; hide noise, never meaning. | |
| - Split tests by feature or behavior. Don't append everything to one giant file. | |
| - Match the existing good tests in the repo — they are the template. If none exist, ask the human to seed the first ones. |