Running tests

HERITRACE uses pytest for testing. This guide covers running tests locally and understanding the testing infrastructure.

Test overview

Test types

• Unit tests: Test individual functions and classes
• Integration tests: Test component interactions and database operations

Setting up test environment

Prerequisites

• uv for dependency management
• Docker for test databases
• Python 3.10+ (supports 3.10, 3.11, 3.12, 3.13)

Test database lifecycle

Test databases start and stop automatically. A session-scoped pytest fixture (docker_services in tests/conftest.py) runs docker compose -f tests/docker-compose.yml up -d --wait before the first test and docker compose down after the last test. No manual setup or teardown is needed.

The test services and their host ports:

• Dataset database (Virtuoso): port 41800
• Provenance database (Virtuoso): port 41802
• Redis: port 41804

Running tests

Install dependencies

# Install all dependencies including development tools
uv sync --locked --dev

Basic test execution

All Tests

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run with detailed output
uv run pytest -vvv

Specific Test Files

# Run unit tests only
uv run pytest tests/unit/

# Run integration tests only
uv run pytest tests/integration/

# Run specific test file
uv run pytest tests/unit/test_api.py

Specific Test Cases

# Run specific test function
uv run pytest tests/unit/test_api.py::test_get_entity

# Run tests matching pattern
uv run pytest -k "test_entity"

# Run tests with specific marker
uv run pytest -m "integration"

Coverage analysis

Basic Coverage

# Run tests with coverage
uv run pytest --cov=heritrace

# Coverage with missing lines
uv run pytest --cov=heritrace --cov-report=term-missing

HTML Coverage Report

# Generate HTML coverage report
uv run pytest --cov=heritrace --cov-report=html

# Open the report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux
start htmlcov/index.html  # Windows

XML Coverage

# Generate XML coverage (for CI/CD)
uv run pytest --cov=heritrace --cov-report=xml

Test configuration

Test settings

Tests use a separate configuration file:

tests/test_config.py

class TestConfig(object):
    TESTING = True
    DATASET_DB_URL = "http://localhost:41800/sparql"
    PROVENANCE_DB_URL = "http://localhost:41802/sparql"
    REDIS_URL = "redis://localhost:41804/0"
    SECRET_KEY = "test-secret-key-for-testing-only"
    CACHE_VALIDITY_DAYS = 1

    ORCID_CLIENT_ID = "test-client-id"
    ORCID_CLIENT_SECRET = "test-client-secret"
    # ...

Fixtures

Common test fixtures are defined in tests/conftest.py:

@pytest.fixture(scope="session", autouse=True)
def docker_services():
    subprocess.run(
        ["docker", "compose", "-f", COMPOSE_FILE, "up", "-d", "--wait"],
        check=True,
    )
    yield
    subprocess.run(
        ["docker", "compose", "-f", COMPOSE_FILE, "down"],
        check=True,
    )

@pytest.fixture
def app():
    app = create_app(TestConfig)
    with app.app_context():
        yield app

@pytest.fixture
def client(app):
    return app.test_client()

Test databases are stopped automatically when the pytest session ends.