Unit and Integration Tests for Agent Code
Test the deterministic parts of your agent properly — tools, the loop, error paths — with mocked model responses and a few real end-to-end checks.
Your agent has grown a lot: validated tools, a streaming loop with retries and stop conditions, memory, caching, cost budgets, approvals, and a web interface. Every one of those features was checked by hand, once, when you built it. Change something tomorrow, say, a tweak to the loop guard or a new field in a tool schema, and you have no quick way to know you haven't broken one of the others.
In this lesson you'll add an automated test suite that runs in under a second, costs nothing, and needs no API key. The trick is to separate what's deterministic in your agent, meaning code that always does the same thing given the same input, from what the model decides. You'll unit-test tools and the memory store, test the agent loop against a scripted fake model, and add a few real end-to-end checks you run on demand.
What to test, and what not to
An agent is mostly ordinary code wrapped around one unpredictable component. The ordinary code is where your bugs live, and it's completely testable:
| Layer | Examples in your agent | How to test | When it runs |
|---|---|---|---|
| Pure logic and tools | safePath, Zod validation, write_file, memory selection, cost math | Unit tests | Every change |
| The loop's mechanics | Tool results paired by id, parallel calls, loop guard, wrap-up, approvals, history | Integration tests with a fake model | Every change |
| Real model behavior | "Does it actually write the file I asked for?" | A few end-to-end tests with the real API | On demand, before releases |
| Quality across many tasks | "Is it good at research tasks?" | Evals | Separately |
The last row is not this lesson's job. Whether the model makes good choices across hundreds of varied tasks is a question for evals, which Module 9, Evals and Reliability, covers in depth. Tests answer a narrower question: given these model responses, does my code do the right thing? That question has a yes-or-no answer, which is exactly what makes it testable.
The most important idea in this lesson follows from that table: you don't need a real model to test the loop. The loop's behavior depends only on what the model returns. If you can script the model's replies, you can test every path through the loop deterministically.