Skip to main content

Testing

Testing Reflow

Required for Changes

Build confidence from one affected contract to the complete release-workflow suite.

Commandpython -m pytest

Category

Developer Guide

Quick Command

python -m pytest [PATH] [OPTIONS]
CLIGitDockerdry-runpre-commit
Framework
pytest
Coverage Target
app
Test Root
tests
Default Import Mode
importlib

Overview​

The default pytest run enables strict configuration, coverage for app, short tracebacks, and missing-line reporting. Tests must not depend on a contributor's .config/reflow/config.toml, Git remotes, credentials, Docker registry, or production repository.

Test Layers

Where Reflow Behavior Is Exercised

CLI

tests/cli covers command wiring, help, target propagation, conversion scopes, recovery, Docker output, errors, and exit status.

Configuration

tests/config and tests/unit/config cover loading, missing files, precedence, metadata, and pre-commit policy.

Core Workflows

tests/core covers Git, GitHub, Docker, conversion, replacement, recovery orchestration, repositories, initialization, and dry-run support.

Developer Workflows

Top-level tests validate Make targets, Docker and Compose contracts, packaging metadata, UI progress, and themes.

Focused Validation

Focused pytest examples
bash
# Repository targeting and configuration
python -m pytest tests/cli/test_repository_targeting.py

# Tag replacement behavior

python -m pytest tests/core/reflow/test_tag_replacement.py

# Dry-run boundaries

python -m pytest tests/core/dry_run

# One regression by node ID

python -m pytest tests/cli/test_error_handling.py::test_dockerize_total_failure_is_concise_and_unsuccessful

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

What to Test

Before You Begin

  • Repository targetRequired

    Cover explicit CLI targets, configured targets, current-directory fallback, and path/URL conflicts.

  • Mutation boundaryRequired

    Prove dry-run performs no persistent local, remote, or registry mutation.

  • Conversion planRequired

    Cover both formats, collisions, signed tags, metadata preservation, confirmation, and atomic replacement.

  • External failureRequired

    Mock Git, GitHub CLI, Docker, and subprocess failures and assert concise remediation and nonzero exits.

  • Configuration independenceRequired

    Provide deterministic test configuration instead of reading a contributor-managed config file.

Pre-Commit Quality Gates

Pre-commit checks
bash
make pre-commit-validate
make pre-commit-run-staged
make pre-commit-run

Repository-level exclusions and matching Ruff and Black exclusions protect archived, copied, deprecated, development, and temporary Python reference files even when tools receive explicit paths.

Complete Validation

Full quality checks
bash
# Complete tests and configured coverage
python -m pytest

# Black check, Ruff lint, then tests

make check

Use applicable Docker, Compose, package, documentation, or CLI --help checks when the changed contract reaches those workflows. Do not push images, tags, or releases as part of ordinary testing.

Related Commands

Commands commonly used together with this command.

Dry Run

Review Reflow's non-mutation contract.