python-testing-patterns

When to use

• Writing unit or integration tests for the project
• Setting up test infrastructure (conftest.py, fixtures)
• Adding tests for a new module
• Debugging a failing test

Prerequisites

Tests require the dev dependencies:

uv sync --extra dev

Test structure

Tests live in tests/ at the project root, mirroring atlas/:

tests/
├── conftest.py          # Shared fixtures
├── test_chunk.py        # Tests for atlas/chunk.py
├── test_make_bundle.py  # Tests for atlas/make_bundle.py
└── test_embed/
    ├── conftest.py      # Embedder fixtures
    └── test_onnx.py     # Tests for atlas/embed/onnx.py

Fixture patterns

Use conftest.py for shared fixtures. Keep them scoped appropriately.

tests/conftest.py

from __future__ import annotations

from collections.abc import Generator
from pathlib import Path
import tempfile

import pytest


@pytest.fixture
def tmp_bundle_dir() -> Generator[Path, None, None]:
    """Provide a temporary directory for bundle output."""
    with tempfile.TemporaryDirectory() as d:
        yield Path(d)

Mocking external dependencies

For tests that should not hit Hugging Face or the network:

@pytest.fixture(autouse=True)
def mock_hf_download(monkeypatch: pytest.MonkeyPatch) -> None:
    """Prevent accidental network calls during tests."""

    def fake_download(*args, **kwargs) -> str:
        return "/tmp/fake-model-dir"

    monkeypatch.setattr(
        "huggingface_hub.snapshot_download",
        fake_download,
    )

For tests that need real ONNX inference, mark them as integration:

@pytest.mark.integration
def test_onnx_embedder_inference(onnx_embedder: OnnxEmbedder) -> None:
    embeddings = onnx_embedder.embed(["hello world"])
    assert embeddings.shape[1] == onnx_embedder.dim

Test patterns by module

atlas/chunk.py

• Unit test parse_frontmatter with: valid YAML, malformed YAML, no frontmatter, empty file.
• Unit test _split_on_h2 with: normal headings, no headings, consecutive headings, heading at EOF.
• Integration test chunk_file against a real markdown file in tests/fixtures/.