Testing

Testing Doc Gen

Required for Changes

Validate one scanning, rendering, CLI, or persistence contract before the complete suite.

Commandpython -m pytest

Quick Command

python -m pytest [PATH] [OPTIONS]

CLIgenerationread-onlydry-runpre-commit

Framework

pytest

Coverage Target

app

Test Root

tests

Writable Command

structure generate

Overview

Doc Gen tests should use temporary projects and explicit output paths. Print and analyze must remain read-only; generate may write only the selected document; and dry-run must not create its output directory or invoke the writer.

Test Layers

Where Doc Gen Behavior Is Exercised

CLI

tests/cli covers entry behavior, initialization, errors, and version output.

Configuration

tests/config covers loading and defaults, while tests/unit/config validates packaging and pre-commit policy.

Initialization

tests/core/initialize covers scaffold models, builders, and execution without unsafe overwrites.

Safety and Workflows

Dry-run, developer-workflow, utility, service, and theme tests preserve output and integration contracts.

Focused Validation

Focused pytest examples

bash

# CLI behavior and concise errors
python -m pytest tests/cli

# Initialization builders and execution

python -m pytest tests/core/initialize

# Generated-output and command dry-run boundaries

python -m pytest tests/test_dry_run.py

# Make, Docker, Compose, and metadata contracts

python -m pytest tests/test_developer_workflows.py tests/unit/config

On Windows, use a repository-local --basetemp when the system temporary directory has inherited ACL restrictions.

What to Test

Before You Begin

Print and analyzeRequired
Assert useful output without creating or modifying project files.
GenerateRequired
Assert only the resolved output document is written and unrelated documentation remains untouched.
Dry-runRequired
Allow safe scanning and rendering but prevent output directories, files, and writer calls.
Profiles and ignore rulesRequired
Cover explicit and default profiles, smart mode, depth, visibility, collapse, project type, and ignored content.
ConfigurationRequired
Cover present, missing, defaulted, invalid, and CLI-overridden values at the consuming boundary.

Pre-Commit Quality Gates

Doc Gen runs Ruff lint fixes, Ruff formatting, Black, trailing-whitespace cleanup, and final-newline correction through pre-commit.

Pre-commit checks

bash

make pre-commit-validate
make pre-commit-run-staged
make pre-commit-run

Repository and tool exclusions protect inactive historical and personal reference files from automatic changes.

Complete Validation

Full quality checks

bash

python -m pytest
make check

For developer-workflow changes, also inspect make help, representative Make dry-runs, Docker and Compose configuration, and development and production CLI --help startup. Do not publish packages or images during routine validation.

Related Commands

Commands commonly used together with this command.

Development Setup

Install the complete contributor toolchain.

Contributing

Prepare a focused Doc Gen contribution.

Safety and Dry Run

Review output non-mutation guarantees.

Architecture

Map tests to scanning, rendering, and writing layers.

Overview​

Overview