# How to Run the Test Suite for AI Hedge Fund: A Complete Guide

> Run the comprehensive pytest test suite for the AI Hedge Fund repository. Execute pytest after installing dependencies to validate back-testing, portfolio logic, and valuation utilities.

- Repository: [Virat Singh/ai-hedge-fund](https://github.com/virattt/ai-hedge-fund)
- Tags: how-to-guide
- Published: 2026-03-09

---

**Run `poetry run pytest` from the repository root after installing dependencies with `poetry install` to execute the comprehensive pytest-based test suite that validates the back-testing engine, portfolio logic, and valuation utilities.**

The `virattt/ai-hedge-fund` repository includes a robust test suite located in the `tests/` directory. Running the test suite ensures that modifications to the back-testing engine, agent strategies, or portfolio calculations maintain expected behavior and do not introduce regressions.

## Prerequisites

Before executing tests, ensure you have Poetry installed to manage the Python environment and dependencies specified in [`pyproject.toml`](https://github.com/virattt/ai-hedge-fund/blob/main/pyproject.toml).

```bash

# Install Poetry if not already present

curl -sSL https://install.python-poetry.org | python3 -

```

The project requires **Python 3.11+** as specified in the project configuration.

## Running the Test Suite

### Run All Tests

To execute the complete test suite using the isolated virtual environment created by Poetry:

```bash
poetry install
poetry run pytest

```

This command discovers all `test_*.py` modules under `tests/` and runs parametrized cases for the back-testing engine, portfolio mechanics, and API utilities.

### Run Specific Test Files

Target individual components to debug specific functionality:

```bash

# Run portfolio logic tests only

poetry run pytest tests/backtesting/test_portfolio.py -v

# Run valuation utility tests

poetry run pytest tests/backtesting/test_valuation.py -v

# Run API rate limiting tests

poetry run pytest tests/test_api_rate_limiting.py -v

```

### Generate Coverage Reports

To verify which source files are exercised by the test suite:

```bash
poetry run pytest --cov=src --cov-report=term-missing

```

This outputs coverage statistics for the `src/` directory, highlighting untested lines in modules like [`src/backtesting/engine.py`](https://github.com/virattt/ai-hedge-fund/blob/main/src/backtesting/engine.py) and [`src/backtesting/portfolio.py`](https://github.com/virattt/ai-hedge-fund/blob/main/src/backtesting/portfolio.py).

## What the Test Suite Covers

The pytest suite validates critical components of the AI hedge fund system:

- **Back-testing Engine** ([`tests/backtesting/test_controller.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_controller.py), [`tests/backtesting/test_engine.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_engine.py)): Confirms that the engine schedules agents, processes market data, and produces expected execution flows.
- **Portfolio Mechanics** ([`tests/backtesting/test_portfolio.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_portfolio.py)): Validates cash balances, margin calculations, realized gains, and position updates for both long and short trades.
- **Valuation Utilities** ([`tests/backtesting/test_valuation.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_valuation.py)): Checks `calculate_portfolio_value`, `compute_exposures`, and `compute_portfolio_summary` against expected numeric outcomes.
- **API Rate Limiting** ([`tests/test_api_rate_limiting.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/test_api_rate_limiting.py)): Ensures the built-in throttling wrapper respects configured request limits.
- **Integration Tests** (`tests/backtesting/integration/`): Runs end-to-end scenarios that spin up full back-tests with multiple agents and verify final portfolio performance.

## Key Test Files and Source Mapping

| Test File | Source Module Under Test | Purpose |
|-----------|-------------------------|---------|
| [`tests/backtesting/test_portfolio.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_portfolio.py) | [`src/backtesting/portfolio.py`](https://github.com/virattt/ai-hedge-fund/blob/main/src/backtesting/portfolio.py) | Position management and margin logic |
| [`tests/backtesting/test_valuation.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_valuation.py) | [`src/backtesting/valuation.py`](https://github.com/virattt/ai-hedge-fund/blob/main/src/backtesting/valuation.py) | Portfolio value and exposure calculations |
| [`tests/backtesting/test_engine.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_engine.py) | [`src/backtesting/engine.py`](https://github.com/virattt/ai-hedge-fund/blob/main/src/backtesting/engine.py) | Core back-testing orchestration |
| [`tests/test_api_rate_limiting.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/test_api_rate_limiting.py) | [`src/api_rate_limiting.py`](https://github.com/virattt/ai-hedge-fund/blob/main/src/api_rate_limiting.py) | Request throttling and rate limiting |
| [`tests/backtesting/integration/test_integration_long_short.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/integration/test_integration_long_short.py) | Multiple modules | End-to-end long/short strategy validation |

## Summary

- Install dependencies with `poetry install` before running tests.
- Execute the full suite with `poetry run pytest` from the repository root.
- Target specific components using file paths like [`tests/backtesting/test_portfolio.py`](https://github.com/virattt/ai-hedge-fund/blob/main/tests/backtesting/test_portfolio.py).
- Generate coverage reports with `poetry run pytest --cov=src` to identify untested code.
- The suite covers back-testing logic, portfolio mechanics, valuation utilities, and API rate limiting.

## Frequently Asked Questions

### How do I run a single test file instead of the entire suite?

Use the file path as an argument to pytest: `poetry run pytest tests/backtesting/test_valuation.py`. Add the `-v` flag for verbose output that shows individual test names and results.

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

The project requires **Python 3.11 or higher**, as specified in [`pyproject.toml`](https://github.com/virattt/ai-hedge-fund/blob/main/pyproject.toml). Poetry will enforce this version constraint when creating the virtual environment.

### How do I check which parts of the source code are covered by tests?

Run `poetry run pytest --cov=src --cov-report=term-missing` to display a coverage summary. This shows the percentage of lines covered in each source file and lists specific line numbers that lack test coverage.

### Where are the integration tests located?

Integration tests reside in `tests/backtesting/integration/` and include files like [`test_integration_long_short.py`](https://github.com/virattt/ai-hedge-fund/blob/main/test_integration_long_short.py). These tests validate end-to-end scenarios by running complete back-tests with multiple agents and verifying final portfolio states.