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:

   uv init
   

3. Add pytest as a dev dependency:

   uv add --dev pytest pytest-cov
   

4. Confirm the test runner works:

   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

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

# 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

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

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