Testing Reference

Testing Reference

Complete reference for the IDX API pytest testing framework.

Available Commands

The Makefile provides several targets for different testing scenarios:

Test Execution

Command	Description	Use Case
make test	Run all tests with coverage	Default test run
make test-fast	Run tests without coverage	Quick iteration during development
make test-html	Generate HTML reports	Full reports with coverage
make test-watch	Auto-run on file changes	Active development

Filtered Tests

Command	Description
make test-auth	Authentication tests only
make test-unit	Unit tests in tests/unit/
make test-integration	Integration tests

Documentation

Command	Description
make publish-docs	Copy reports to docs site
make test-publish	Run tests + publish reports

Test Structure

idx-api/
├── tests/
│   ├── conftest.py          # Shared fixtures
│   ├── test_health.py       # Health check tests
│   ├── test_auth.py         # Authentication tests
│   ├── test_agents.py       # Agent CRUD tests
│   ├── unit/                # Unit tests (isolated)
│   └── integration/         # Integration tests
├── reports/
│   ├── html/
│   │   └── report.html      # pytest HTML report
│   └── coverage/
│       └── index.html       # Coverage report
└── Makefile

Test Markers

Use pytest markers to categorize tests:

import pytest

@pytest.mark.auth
def test_api_key_validation():
    """Tests marked with @pytest.mark.auth"""
    pass

@pytest.mark.integration
def test_database_operations():
    """Tests that require full stack"""
    pass

@pytest.mark.slow
def test_embedding_generation():
    """Tests that take longer to run"""
    pass

Run specific markers:

uv run pytest -m auth        # Only auth tests
uv run pytest -m "not slow"  # Skip slow tests

Test Fixtures

The conftest.py file provides shared fixtures for all tests:

Database

@pytest.fixture
def db_session():
    """Create isolated test database session."""
    engine = create_engine("sqlite:///:memory:")
    Base.metadata.create_all(engine)
    Session = sessionmaker(bind=engine)
    session = Session()
    yield session
    session.close()

Test Client

@pytest.fixture
def client(db_session):
    """FastAPI test client with database override."""
    app.dependency_overrides[get_db] = lambda: db_session
    with TestClient(app) as c:
        yield c
    app.dependency_overrides.clear()

Auth Headers

@pytest.fixture
def admin_headers(db_session):
    """Headers with admin API key."""
    api_key = create_test_api_key(db_session, role="admin")
    return {"X-API-Key": api_key}

Test Configuration

Tests use pytest with the following plugins:

• pytest-asyncio - Async test support for FastAPI
• pytest-html - HTML report generation
• pytest-cov - Coverage measurement

Configuration in pyproject.toml:

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]

Docker Commands

From the project root:

# Run tests in Docker container
make test-docker

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

# Build docs image with embedded reports
make docs-build

Docker Compose Services

The idx-api-test service runs tests in an isolated container:

# 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

Volume Sharing

Test reports are stored in a Docker volume called test-reports:

• idx-api-test: Writes reports to /app/reports → volume
• idx-docs-dev: Mounts volume at /app/public/reports (read-only)

This allows the docs dev server to serve the latest reports without rebuilding.