# Python Tdd With Uv

> Test-driven development in Python using uv as the package manager. Covers the red-green-refactor cycle, vertical slicing, and uv project setup.

- Skill: `spencerpauly/python-tdd-with-uv` (Agent Skill)
- Install (CLI): `npx skillmds add spencerpauly/python-tdd-with-uv`
- Raw SKILL.md: https://api.skillmd.com/api/skills/spencerpauly/python-tdd-with-uv/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: spencerpauly (https://skillmd.com/u/spencerpauly)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/spencerpauly/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:
   ```bash
   uv init
   ```
3. Add pytest as a dev dependency:
   ```bash
   uv add --dev pytest pytest-cov
   ```
4. Confirm the test runner works:
   ```bash
   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

```python
# 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

```bash
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

```bash
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](https://github.com/mattpocock/skills) — vertical-slice TDD philosophy
- [nizos/tdd-guard](https://github.com/nizos/tdd-guard) — automated TDD enforcement via hooks
- [s2005/uv-skill](https://github.com/s2005/uv-skill) — uv workflow patterns