python3-tdd

TDD Workflow

Consult standards-for-python-development for the shared rules. Load python3-testing for detailed test patterns.

Input

Task: $ARGUMENTS

Phases

1. Design Interface

• Define only the interface needed to express the behavior under test
• Preserve the project's existing architecture and typing conventions
• Load python3-typing when boundary types or models are involved

2. Write Failing Tests

• Load python3-testing for fixture patterns and test structure
• Tests must fail initially (RED)
• AAA pattern; behavioral naming
• Run the smallest relevant pytest target and confirm RED
• Record the expected failure reason before running it; RED is valid only when the observed failure demonstrates the missing behavior. A syntax/import/fixture failure or a test that already passes does not establish the requirement.

3. Implement to Pass

• Minimal code to make tests pass (GREEN)
• Run the smallest relevant pytest target after each change and compare the observed result with the expected GREEN result
• Refactor only while tests stay green

4. Verify

# Linting, formatting, and type checking
uv run prek run --files src/ tests/
# Fallback when no .pre-commit-config.yaml:
# uv run ruff check src/ tests/
# uv run ruff format --check src/ tests/

# Tests with coverage
uv run pytest --cov=src --cov-report=term-missing

5. Quality Gate

• All tests pass
• No lint errors
• No type errors
• Changed behavior, boundaries, and regressions have appropriate tests
• Existing project coverage gate is respected, if configured
• Shebang validated on scripts