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

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 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, the test suite demonstrates this pattern by instantiating the SimpleAgent class from 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 or the plan-and-solve agent in 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, the test registers a mock search tool before running the agent through its reasoning loop. Similarly, 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.

Install development dependencies:

pip install -r requirements.txt

Run a specific test file:

pytest code/chapter7/test_simple_agent.py -q

Run all Chapter 7 agent tests:

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:

# 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:

pytest test_my_weather_agent.py -q

Reference these key source files when writing tests:

• code/chapter7/simple_agent.py – Minimal agent implementation
• code/chapter7/reflection_agent.py – Self-reflective agent logic
• code/chapter7/react_agent.py – ReAct-style reasoning
• code/chapter7/plan_solve_agent.py – Multi-step planning agent
• code/chapter7/advanced_search_tool.py – Complex external tool example
• 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 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, code/chapter7/test_react_agent.py, and code/chapter7/test_reflection_agent.py. Each test file corresponds to an agent implementation file in the same directory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}