Python Tdd With Uv

Python TDD with uv

Write Python code test-first using uv for fast dependency and environment management.

Setting Up the Project

1. Check if uv is installed: uv --version
2. If the project doesn't have a pyproject.toml, initialize:

   bashCopy code
   uv init
   

3. Add pytest as a dev dependency:

   bashCopy code
   uv add --dev pytest pytest-cov
   

4. Confirm the test runner works:

   bashCopy code
   uv run pytest --co
   

TDD Workflow — Vertical Slicing

Work in small cycles. Never write more than one failing test at a time.

Planning Phase

Before writing code, answer:

1. What interface changes are needed? (functions, classes, APIs)
2. Which behaviors matter most? (prioritize critical paths)
3. Can we design for testability? (inject dependencies, avoid global state)

The Cycle

Copy code
RED   → Write ONE failing test for the next behavior
GREEN → Write the MINIMUM code to make it pass
REFACTOR → Clean up without changing behavior
REPEAT

Rules:

• Never write implementation before a failing test exists
• Never write more than one failing test at a time
• Run uv run pytest after every change
• Tests must assert observable behavior, not implementation details
• Mocks should only be used at system boundaries (I/O, network, clock)

Test File Structure

pythonCopy code
# tests/test_<module>.py

class TestFeatureName:
    """Group related behaviors."""

    def test_does_expected_thing_when_given_input(self):
        result = function_under_test(input_value)
        assert result == expected

    def test_raises_when_given_invalid_input(self):
        with pytest.raises(ValueError):
            function_under_test(bad_input)

Running Tests

bashCopy code
uv run pytest                      # all tests
uv run pytest tests/test_foo.py    # single file
uv run pytest -k "test_name"       # by name pattern
uv run pytest --cov=src            # with coverage
uv run pytest -x                   # stop on first failure

uv Essentials

bashCopy code
uv add <package>           # add dependency
uv add --dev <package>     # add dev dependency
uv remove <package>        # remove dependency
uv sync                    # sync environment from lockfile
uv run <command>           # run in managed environment
uv lock                    # regenerate lockfile

• Always use uv run to execute commands — never activate venvs manually
• Commit both pyproject.toml and uv.lock

References

• mattpocock/skills — TDD skill — vertical-slice TDD philosophy
• nizos/tdd-guard — automated TDD enforcement via hooks
• s2005/uv-skill — uv workflow patterns