Run Tests

How to Run Tests

This guide shows you how to run tests in various scenarios and troubleshoot common issues.

Quick Start

1. Navigate to the API directory

   cd idx-api

2. Run all tests with coverage

   make test

3. View the HTML reports

   make test-html
   open reports/html/report.html

Run All Tests

cd idx-api

# Run all tests with coverage
make test

# Run tests without coverage (faster)
make test-fast

# Run with HTML report generation
make test-html

Run Specific Test Categories

# Run only authentication tests
make test-auth

# Run only unit tests
make test-unit

# Run only integration tests
make test-integration

# Run tests matching pattern
uv run pytest -k "auth" -v

# Run specific test file
uv run pytest tests/test_agents.py -v

Run with Auto-Reload

During active development, use watch mode to automatically run tests when files change:

make test-watch

Generate Coverage Reports

# Generate coverage with HTML report
make test-coverage

# Generate coverage for specific modules
uv run pytest tests/ --cov=idx_api.routers.agents --cov-report=html

# View coverage in terminal
uv run pytest tests/ --cov=idx_api --cov-report=term-missing

Run Tests in Docker

From the project root:

# Run tests in Docker container
make test-docker

# Run tests and publish to docs site
make docs-publish

Using Docker Compose directly:

# Run tests with the test profile
docker compose --profile test run --rm idx-api-test

# View test reports in docs dev server
docker compose --profile dev up idx-docs-dev
# Reports available at: https://help.{DOMAIN}/reports/tests/report.html

Publish Reports to Docs

Test reports can be published to this documentation site for team visibility:

1. Generate fresh reports

   make test-html

2. Publish to docs

   make publish-docs

3. Or combine both steps

   make test-publish

Published reports are available at:

• Test Report
• Coverage Report

Set Up CI/CD

With Docker

# GitHub Actions example with Docker
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests in Docker
        run: make test-docker

      - name: Build docs with reports
        run: make docs-build

      - name: Deploy docs
        run: docker compose --profile prod up -d idx-docs

Without Docker

# GitHub Actions example (local)
- name: Run tests
  run: |
    cd idx-api
    make test-html

- name: Upload reports
  uses: actions/upload-artifact@v4
  with:
    name: test-reports
    path: idx-api/reports/

Troubleshooting

Common Issues

Import Errors

# Ensure package is installed in dev mode
cd idx-api
uv pip install -e ".[dev]"

Database Issues

# Tests use in-memory SQLite by default
# If you see "table not found" errors:
uv run alembic upgrade head

Async Warnings

# Ensure pytest-asyncio is configured
# Check pyproject.toml has:
# [tool.pytest.ini_options]
# asyncio_mode = "auto"

Debug Failed Tests

# Run single test with verbose output
uv run pytest tests/test_auth.py::test_api_key_validation -vvv

# Show print statements
uv run pytest -s

# Drop into debugger on failure
uv run pytest --pdb

# Show local variables in traceback
uv run pytest --tb=long