python-tdd-with-uv

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python TDD with uv

使用uv进行Python测试驱动开发（TDD）

Write Python code test-first using

uv

for fast dependency and environment management.

采用测试优先的方式编写Python代码，使用

uv

实现快速的依赖项和环境管理。

Setting Up the Project

项目搭建

Check if
```
uv
```
is installed:
```
uv --version
```
If the project doesn't have a
```
pyproject.toml
```
, initialize:
bash
```
uv init
```
Add pytest as a dev dependency:
bash
```
uv add --dev pytest pytest-cov
```
Confirm the test runner works:
bash
```
uv run pytest --co
```

检查
```
uv
```
是否已安装：
```
uv --version
```
如果项目没有
```
pyproject.toml
```
文件，初始化项目：
bash
```
uv init
```
添加pytest作为开发依赖项：
bash
```
uv add --dev pytest pytest-cov
```
确认测试运行器正常工作：
bash
```
uv run pytest --co
```

TDD Workflow — Vertical Slicing

TDD工作流——垂直切片

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

以小循环的方式工作。永远不要同时编写多个失败的测试用例。

Planning Phase

规划阶段

Before writing code, answer:

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

编写代码前，先回答以下问题：

需要哪些接口变更？（函数、类、API）
哪些行为最为重要？（优先处理关键路径）
我们能否设计出易于测试的代码？（注入依赖项，避免全局状态）

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)

红（RED）→ 为下一个行为编写一个失败的测试用例
绿（GREEN）→ 编写最少的代码使测试通过
重构（REFACTOR）→ 在不改变行为的前提下清理代码
重复（REPEAT）

规则：

永远不要在失败的测试用例存在之前编写实现代码
永远不要同时编写多个失败的测试用例
每次变更后运行
```
uv run pytest
```
测试必须断言可观察的行为，而非实现细节
仅在系统边界（I/O、网络、时钟）使用Mock

Test File Structure

测试文件结构

python

undefined

python

undefined

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)

undefined

class TestFeatureName: """对相关行为进行分组。"""

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)

undefined

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

bash

uv run pytest                      # 运行所有测试
uv run pytest tests/test_foo.py    # 运行单个文件的测试
uv run pytest -k "test_name"       # 按名称模式运行测试
uv run pytest --cov=src            # 运行测试并生成覆盖率报告
uv run pytest -x                   # 遇到第一个失败时停止运行

uv Essentials

uv核心命令

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

bash

uv add <package>           # 添加依赖项
uv add --dev <package>     # 添加开发依赖项
uv remove <package>        # 移除依赖项
uv sync                    # 根据锁定文件同步环境
uv run <command>           # 在管理的环境中运行命令
uv lock                    # 重新生成锁定文件

始终使用
```
uv run
```
执行命令——不要手动激活虚拟环境
提交
```
pyproject.toml
```
和
```
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

mattpocock/skills — TDD skill — 垂直切片TDD理念
nizos/tdd-guard — 通过钩子实现自动化TDD强制执行
s2005/uv-skill — uv工作流模式