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

Test structure

tests/
├── conftest.py                      # Pytest configuration and fixtures
├── unit/                           # Unit tests
│   ├── test_api.py
│   ├── test_auth.py
│   ├── test_editor.py
│   └── ...
├── integration/                    # Integration tests
│   ├── test_entity_integration.py
│   ├── test_shacl_utils_integration.py
│   └── ...

Setting up test environment

Prerequisites

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

Test database setup

Tests require dedicated databases running on different ports:

Linux/MacOS

# Make scripts executable
chmod +x ./tests/start-test-databases.sh
chmod +x ./tests/stop-test-databases.sh

# Start test databases
./tests/start-test-databases.sh

This creates:

• Test dataset database on port 9999
• Test provenance database on port 9998

Windows PowerShell

# Start test databases
.\tests\Start-TestDatabases.ps1

This creates:

• Test dataset database on port 9999
• Test provenance database on port 9998

Port Separation

Test databases use different ports (9998, 9999) than development databases (8998, 8999) to avoid conflicts.

Running tests

Install dependencies

# Install all dependencies including development tools
poetry install --with dev

Basic test execution

All Tests

# Run all tests
poetry run pytest

# Run with verbose output
poetry run pytest -v

# Run with detailed output
poetry run pytest -vvv

Specific Test Files

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

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

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

Specific Test Cases

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

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

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

Coverage analysis

Basic Coverage

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

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

HTML Coverage Report

# Generate HTML coverage report
poetry 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)
poetry run pytest --cov=heritrace --cov-report=xml

Test configuration

Test settings

Tests use a separate configuration file:

tests/test_config.py

class TestConfig(Config):
    TESTING = True
    DATASET_DB_URL = 'http://localhost:9999/sparql'
    PROVENANCE_DB_URL = 'http://localhost:9998/sparql'
    SECRET_KEY = 'test-secret-key'

    # Disable external services in tests
    ORCID_CLIENT_ID = 'test-client-id'
    ORCID_CLIENT_SECRET = 'test-client-secret'

Fixtures

Common test fixtures are defined in conftest.py:

@pytest.fixture
def app():
    """Create application instance for testing."""
    app = create_app(TestConfig)
    return app

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

@pytest.fixture
def dataset_db():
    """Dataset database connection."""
    # Database setup logic

Cleanup

Stop test databases

When finished testing:

Linux/MacOS

./tests/stop-test-databases.sh

Windows PowerShell

.\tests\Stop-TestDatabases.ps1