testing-guide.md

Testing Guide

This guide describes how to test DocGen.

---

Running Tests

Basic Test Run

Run all tests:

pytest -v

Run Specific Tests

Run tests for a specific module:

pytest tests/cli/ -v

Run tests for a specific file:

pytest tests/cli/test_main.py -v

Run with Coverage

pytest --cov=doc_gen --cov-report=term-missing

---

Writing Tests

Test Location

Tests are in the tests/ directory:

tests/
├── cli/
├── config/
├── core/
├── services/
└── utils/

Test Structure

# tests/cli/test_main.py
import pytest
from doc_gen.cli.main import app

def test_main_help():
    # Test implementation
    pass

---

Test Conventions

• Use descriptive test names
• Test one thing per test
• Use fixtures for common setup
• Keep tests independent

---

Running Tests in Docker

make d-test

---

Running Tests in Docker Compose

make c-test

---

Test Coverage

Check coverage:

pytest --cov=doc_gen --cov-report=html

View coverage report:

open htmlcov/index.html

---

CI Testing

Compatibility tests run on Python 3.9 and Python 3.14 with the test extra, which explicitly includes PyYAML for workflow-configuration tests. Black and Ruff run separately on Python 3.14 with the dev extra so developer tool requirements cannot break the supported Python 3.9 runtime.

Equivalent local commands are:

pip install -e ".[test]"
make test-ci

# Standard Python 3.14 development environment
pip install -e ".[dev]"
make format-check-ci
make lint-ci
make c-ci

---

Related Documentation

• Developer Guide
• Docker Workflow