# How to Test Agents Created with Hello-Agents: A Complete Guide

> Learn how to test agents created with Hello Agents using its pytest framework. Instantiate agents, register mock tools, and assert outputs for robust agent testing.

- Repository: [Datawhale/hello-agents](https://github.com/datawhalechina/hello-agents)
- Tags: how-to-guide
- Published: 2026-05-09

---

**Hello-Agents provides a pytest-based testing framework where you instantiate agent classes, register mock tools via `ToolRegistry`, run `agent.run()`, and assert expected outputs against deterministic responses.**

The datawhalechina/hello-agents repository ships with a hands-on learning environment that includes ready-made test suites for every chapter. When you test agents created with hello-agents, you follow a consistent pattern using pytest alongside the framework's `ToolRegistry` to isolate agent behavior from external dependencies.

## Understanding the Hello-Agents Testing Architecture

The testing framework follows a four-step pattern implemented across the `code/` directory:

1. **Agent implementation** – Each chapter provides agent classes (e.g., `SimpleAgent`, `ReActAgent`) in dedicated Python files.
2. **Test harness** – Corresponding `test_*.py` files instantiate agents, inject dependencies, and verify behavior.
3. **Tool registration** – The `ToolRegistry` class in [`tools/registry.py`](https://github.com/datawhalechina/hello-agents/blob/main/tools/registry.py) enables mock tool registration for isolated testing.
4. **Pytest discovery** – Running `pytest` automatically discovers and executes test functions using standard naming conventions.

## Testing Simple Agents

The simplest tests verify agent responses without external tool calls. In [`code/chapter7/test_simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/test_simple_agent.py), the test suite demonstrates this pattern by instantiating the `SimpleAgent` class from [`code/chapter7/simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/simple_agent.py), calling `agent.run(prompt)` with deterministic input, and asserting that expected keywords appear in the response.

## Testing Agents with Tools

For agents that invoke tools—such as the ReAct agent in [`code/chapter7/react_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/react_agent.py) or the plan-and-solve agent in [`code/chapter7/plan_solve_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/plan_solve_agent.py)—you must register mock implementations to avoid external side effects.

The `ToolRegistry.register()` method allows you to substitute real APIs with test doubles. For example, in [`code/chapter7/test_react_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/test_react_agent.py), the test registers a mock search tool before running the agent through its reasoning loop. Similarly, [`code/chapter7/test_my_calculator.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/test_my_calculator.py) demonstrates registering a calculator mock using `ToolRegistry.register("calculator", mock_calc)` to test arithmetic tool usage without executing real calculations.

## Running the Test Suite

Execute tests using standard pytest commands after installing dependencies listed in the repository's [`requirements.txt`](https://github.com/datawhalechina/hello-agents/blob/main/requirements.txt).

Install development dependencies:

```bash
pip install -r requirements.txt

```

Run a specific test file:

```bash
pytest code/chapter7/test_simple_agent.py -q

```

Run all Chapter 7 agent tests:

```bash
pytest code/chapter7 -q

```

## Writing Custom Agent Tests

When building custom agents, create `test_<your_agent>.py` files following the established pattern. This example shows how to test a custom `WeatherAgent` that calls a weather tool:

```python

# test_my_weather_agent.py

import pytest
from utils.logging import get_logger
from tools.registry import ToolRegistry
from my_agents import WeatherAgent   # ← your agent implementation

logger = get_logger(__name__)

def mock_weather(city: str) -> str:
    return f"The weather in {city} is sunny."

def test_weather_agent():
    # Register the mock tool so the agent can call it

    ToolRegistry.register("weather", mock_weather)
    
    agent = WeatherAgent()
    prompt = "What's the weather in Paris?"
    answer = agent.run(prompt)
    
    # Verify that the agent incorporated the mock tool's response

    assert "sunny" in answer.lower()
    logger.info("WeatherAgent test passed")

```

Execute the custom test:

```bash
pytest test_my_weather_agent.py -q

```

Reference these key source files when writing tests:

- [`code/chapter7/simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/simple_agent.py) – Minimal agent implementation
- [`code/chapter7/reflection_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/reflection_agent.py) – Self-reflective agent logic
- [`code/chapter7/react_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/react_agent.py) – ReAct-style reasoning
- [`code/chapter7/plan_solve_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/plan_solve_agent.py) – Multi-step planning agent
- [`code/chapter7/advanced_search_tool.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/advanced_search_tool.py) – Complex external tool example
- [`tools/registry.py`](https://github.com/datawhalechina/hello-agents/blob/main/tools/registry.py) – Tool registration mechanism

## Summary

- **Use pytest** as the test runner for all agent validation in hello-agents.
- **Register mocks** via `ToolRegistry.register()` to isolate agents from external APIs.
- **Structure tests** by instantiating agents, calling `agent.run()`, and asserting output content.
- **Locate existing tests** in `code/chapter7/` alongside their corresponding agent implementations.
- **Follow the naming convention** `test_*.py` for automatic test discovery.

## Frequently Asked Questions

### How do I run a single test file in hello-agents?

Use the pytest command with the specific file path: `pytest code/chapter7/test_simple_agent.py -q`. The `-q` flag provides concise output while still showing failures and error details.

### Can I use unittest instead of pytest for hello-agents tests?

Yes, pytest supports the built-in `unittest` API, so you can write tests using `unittest.TestCase` classes if preferred. However, the repository examples use native pytest functions for simplicity and cleaner fixture support.

### How do I mock external API calls when testing agents?

Import `ToolRegistry` from [`tools/registry.py`](https://github.com/datawhalechina/hello-agents/blob/main/tools/registry.py) and register mock functions using `ToolRegistry.register("tool_name", mock_function)`. This intercepts tool calls during `agent.run()` execution, allowing you to return deterministic responses without network requests.

### Where are the test files located in the repository?

Test files live alongside agent implementations in chapter-specific directories, such as [`code/chapter7/test_simple_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/test_simple_agent.py), [`code/chapter7/test_react_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/test_react_agent.py), and [`code/chapter7/test_reflection_agent.py`](https://github.com/datawhalechina/hello-agents/blob/main/code/chapter7/test_reflection_agent.py). Each test file corresponds to an agent implementation file in the same directory.