# How to Run Unit Tests for Agent Components in TradingAgents-CN

> Learn how to run unit tests for agent components in TradingAgents-CN. Execute agent-specific tests with pytest -k "agents" or run the full suite easily.

- Repository: [hsliuping/TradingAgents-CN](https://github.com/hsliuping/tradingagents-cn)
- Tags: tutorial
- Published: 2026-02-19

---

**Use `pytest -k "agents"` after installing dependencies to execute only the agent-specific unit tests, or run `pytest` to execute the full suite while automatically excluding integration tests.**

TradingAgents-CN is an open-source multi-agent trading system that relies on rigorous unit testing to ensure the reliability of its analyst, manager, and risk-debator components. This guide explains how to run unit tests for the agent components using the **pytest** framework configured in the repository.

## Prerequisites and Environment Setup

Before executing tests, you must install the project dependencies and activate the virtual environment.

```bash

# Clone the repository

git clone https://github.com/hsliuping/TradingAgents-CN.git
cd TradingAgents-CN

# Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies

pip install -r requirements.txt

```

The [`requirements.txt`](https://github.com/hsliuping/TradingAgents-CN/blob/main/requirements.txt) file at the repository root defines all necessary packages, including pytest and testing utilities.

## Understanding the Test Structure

TradingAgents-CN organizes its test suite under the `tests/` directory, with configuration defined in [`tests/pytest.ini`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/pytest.ini). This configuration restricts test collection to the `tests/` folder and automatically skips any test marked with the `integration` label.

Agent-related unit tests target the core modules located in `tradingagents/agents/`. Key test files include:

- **[`tests/tradingagents/test_app_cache_toggle.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/tradingagents/test_app_cache_toggle.py)** – Validates agent-level caching mechanisms and data-service wiring.
- **[`tests/unit/tools/analysis/test_indicators_uil.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/unit/tools/analysis/test_indicators_uil.py)** – Tests technical-indicator utilities consumed by analyst agents.

## Running Unit Tests for Agent Components

### Run All Unit Tests

To execute the complete suite of unit tests while excluding integration tests (as configured in [`pytest.ini`](https://github.com/hsliuping/TradingAgents-CN/blob/main/pytest.ini)), run:

```bash
pytest

```

This command collects all tests from the `tests/` directory and respects the exclusion rules defined in the configuration file.

### Filter for Agent-Specific Tests

To run unit tests for the agent components specifically, use the `-k` flag to filter by keyword:

```bash
pytest -k "agents"

```

This executes only tests whose node IDs contain the substring "agents", effectively targeting files like [`test_app_cache_toggle.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/test_app_cache_toggle.py) and other agent-related modules.

Alternatively, specify the exact test file path:

```bash
pytest tests/tradingagents/test_app_cache_toggle.py

```

### Verbose Output and Debugging

For detailed output that shows individual test names and failure details, add the verbose flag:

```bash
pytest -v -k "agents"

```

This format helps identify which specific agent component tests pass or fail during debugging sessions.

## Handling Integration Tests

By default, TradingAgents-CN excludes integration tests from the standard pytest run. The [`pytest.ini`](https://github.com/hsliuping/TradingAgents-CN/blob/main/pytest.ini) configuration automatically skips tests marked with `@pytest.mark.integration`.

To override this behavior and include integration tests (which may require external services or databases), explicitly target the integration marker:

```bash
pytest -m integration

```

Use this command only when you have configured the necessary environment variables and external dependencies required for full integration testing.

## Summary

- TradingAgents-CN uses **pytest** configured via [`tests/pytest.ini`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/pytest.ini) to manage the test suite.
- Install dependencies with `pip install -r requirements.txt` before running tests.
- Execute **all unit tests** with the `pytest` command, which automatically excludes integration tests.
- Target **agent components specifically** using `pytest -k "agents"` or by specifying individual test files like [`tests/tradingagents/test_app_cache_toggle.py`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/tradingagents/test_app_cache_toggle.py).
- Use `pytest -v` for verbose output and `pytest -m integration` to include integration tests when needed.

## Frequently Asked Questions

### How do I run only the agent caching tests in TradingAgents-CN?

Execute `pytest tests/tradingagents/test_app_cache_toggle.py` to run only the specific test file that validates agent-level caching and data-service wiring. Alternatively, use `pytest -k "cache"` to filter for any test containing the word "cache" in its name or path.

### What Python version is required to run the unit tests?

The repository requires Python 3.8 or higher, as specified in the [`requirements.txt`](https://github.com/hsliuping/TradingAgents-CN/blob/main/requirements.txt) and project configuration. Ensure you create your virtual environment with a compatible Python version before installing dependencies and running `pytest`.

### Why are my integration tests being skipped when I run pytest?

The [`tests/pytest.ini`](https://github.com/hsliuping/TradingAgents-CN/blob/main/tests/pytest.ini) file explicitly configures pytest to skip tests marked with `@pytest.mark.integration` by default. This design keeps unit test runs fast and isolated from external dependencies. To include integration tests, run `pytest -m integration` after configuring the necessary environment variables.

### Can I run agent tests in parallel to speed up execution?

Yes, install the `pytest-xdist` package (`pip install pytest-xdist`) and run `pytest -n auto -k "agents"` to distribute agent component tests across multiple CPU cores. This significantly reduces execution time when running the full agent test suite.