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

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.

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

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:

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

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 and 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, 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): Validates cash balances, margin calculations, realized gains, and position updates for both long and short trades.
• Valuation Utilities (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): 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	src/backtesting/portfolio.py	Position management and margin logic
tests/backtesting/test_valuation.py	src/backtesting/valuation.py	Portfolio value and exposure calculations
tests/backtesting/test_engine.py	src/backtesting/engine.py	Core back-testing orchestration
tests/test_api_rate_limiting.py	src/api_rate_limiting.py	Request throttling and rate limiting
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.
• 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. 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. These tests validate end-to-end scenarios by running complete back-tests with multiple agents and verifying final portfolio states.

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