Python 测试完全指南：unittest / pytest / mock / 覆盖率 / TDD 从入门到实战

1
                    /\
2
                   /  \
3
                  / E2E \           ← 少量，慢，高成本
4
                 /________\
5
                /          \
6
               / Integration \      ← 适量，中速
7
              /________________\
8
             /                  \
9
            /   Unit Tests       \  ← 大量，快，低成本
10
           /______________________\

1
测试类型    数量    速度    成本    范围
2
────────────────────────────────────────────
3
单元测试    70%     毫秒级   低     单个函数/类
4
集成测试    20%     秒级     中     模块间交互
5
端到端测试   10%    分钟级   高     完整用户流程

1
# 没有测试的开发：
2
# 1. 改一个 Bug，引入两个新 Bug
3
# 2. 重构时提心吊胆
4
# 3. 回归问题反复出现
5
# 4. 代码交接困难
6
# 5. 部署前手动测试耗时且不可靠
7

8
# 有测试的开发：
9
# 1. 修改代码后立即知道是否破坏了功能
10
# 2. 重构时测试通过 = 安全
11
# 3. 测试即文档，展示代码如何使用
12
# 4. 强制良好的接口设计（可测试 = 可维护）
13
# 5. CI/CD 自动化，部署信心倍增

1
F - Fast          快速：毫秒级执行，开发者愿意频繁运行
2
I - Independent   独立：测试之间互不依赖，任意顺序执行结果相同
3
R - Repeatable    可重复：在任何环境运行结果一致（不依赖网络/时间）
4
S - Self-validating 自验证：自动判断通过/失败，无需人工检查
5
T - Timely        及时：在代码编写前后及时编写，不要堆积到最后

1
import unittest
2
from calculator import Calculator
3

4
class TestCalculator(unittest.TestCase):
5
    """计算器测试"""
6

7
    def setUp(self):
8
        """每个测试前执行（初始化）"""
9
        self.calc = Calculator()
10

11
    def tearDown(self):
12
        """每个测试后执行（清理）"""
13
        pass
14

15
    def test_add(self):
16
        """测试加法"""
17
        result = self.calc.add(2, 3)
18
        self.assertEqual(result, 5)
19

20
    def test_add_negative(self):
21
        """测试负数加法"""
22
        self.assertEqual(self.calc.add(-1, -1), -2)
23

24
    def test_add_float(self):
25
        """测试浮点数加法"""
26
        self.assertAlmostEqual(self.calc.add(0.1, 0.2), 0.3, places=7)
27

28
    def test_divide_by_zero(self):
29
        """测试除零异常"""
30
        with self.assertRaises(ZeroDivisionError):
31
            self.calc.divide(10, 0)
32

33
    def test_is_positive(self):
34
        """测试布尔判断"""
35
        self.assertTrue(self.calc.is_positive(5))
36
        self.assertFalse(self.calc.is_positive(-5))
37

38
# 运行：python -m unittest test_calculator.py
39
# 或在文件末尾添加：
40
if __name__ == '__main__':
41
    unittest.main()

1
class TestAssertions(unittest.TestCase):
2

3
    def test_equality(self):
4
        # 相等
5
        self.assertEqual(1 + 1, 2)
6
        self.assertNotEqual(1, 2)
7

8
    def test_membership(self):
9
        # 包含
10
        self.assertIn(3, [1, 2, 3])
11
        self.assertNotIn(4, [1, 2, 3])
12

13
    def test_identity(self):
14
        # 同一对象
15
        obj = [1, 2]
16
        self.assertIs(obj, obj)
17
        self.assertIsNot(obj, [1, 2])
18

19
    def test_none(self):
20
        # None 判断
21
        self.assertIsNone(None)
22
        self.assertIsNotNone(0)
23

24
    def test_types(self):
25
        # 类型判断
26
        self.assertIsInstance(42, int)
27
        self.assertNotIsInstance("hello", int)
28

29
    def test_comparisons(self):
30
        # 大小比较
31
        self.assertGreater(5, 3)
32
        self.assertGreaterEqual(5, 5)
33
        self.assertLess(3, 5)
34

35
    def test_strings(self):
36
        # 字符串
37
        self.assertIn("world", "hello world")
38
        self.assertTrue("hello".startswith("he"))
39

40
    def test_collections(self):
41
        # 集合
42
        self.assertCountEqual([1, 2, 3], [3, 2, 1])  # 忽略顺序
43
        self.assertListEqual([1, 2], [1, 2])
44
        self.assertDictEqual({'a': 1}, {'a': 1})
45

46
    def test_exceptions(self):
47
        # 异常
48
        with self.assertRaises(ValueError) as ctx:
49
            int("not a number")
50
        self.assertIn("invalid literal", str(ctx.exception))

1
import unittest
2
import tempfile
3
import os
4

5
class TestFileProcessor(unittest.TestCase):
6

7
    @classmethod
8
    def setUpClass(cls):
9
        """所有测试前执行一次（类级别初始化）"""
10
        cls.temp_dir = tempfile.mkdtemp()
11
        cls.test_file = os.path.join(cls.temp_dir, "test_data.json")
12
        # 写入测试数据
13
        with open(cls.test_file, 'w') as f:
14
            f.write('{"name": "test", "value": 42}')
15

16
    @classmethod
17
    def tearDownClass(cls):
18
        """所有测试后执行一次（类级别清理）"""
19
        import shutil
20
        shutil.rmtree(cls.temp_dir)
21

22
    def setUp(self):
23
        """每个测试前执行"""
24
        self.processor = FileProcessor(self.test_file)
25

26
    def test_read_file(self):
27
        data = self.processor.read()
28
        self.assertEqual(data['name'], 'test')
29

30
    def test_write_file(self):
31
        self.processor.update('name', 'updated')
32
        data = self.processor.read()
33
        self.assertEqual(data['name'], 'updated')
34

35
# 跳过测试
36
class TestDatabase(unittest.TestCase):
37

38
    @unittest.skip("功能尚未实现")
39
    def test_future_feature(self):
40
        pass
41

42
    @unittest.skipUnless(os.environ.get('DB_HOST'), "需要数据库环境")
43
    def test_database_connection(self):
44
        pass
45

46
    @unittest.expectedFailure
47
    def test_known_bug(self):
48
        # 已知会失败，失败时测试通过
49
        self.assertEqual(1, 2)

1
# pytest 风格：无需类继承，用 assert 语句
2
# 文件名必须以 test_ 开头或 _test 结尾
3

4
def test_add():
5
    """测试加法"""
6
    calc = Calculator()
7
    assert calc.add(2, 3) == 5
8

9
def test_add_negative():
10
    """测试负数"""
11
    calc = Calculator()
12
    assert calc.add(-1, -1) == -2
13

14
def test_divide_by_zero():
15
    """测试除零"""
16
    calc = Calculator()
17
    # pytest 内置异常检查
18
    import pytest
19
    with pytest.raises(ZeroDivisionError):
20
        calc.divide(10, 0)
21

22
# 对比 unittest 版本：
23
# unittest: self.assertEqual(calc.add(2, 3), 5)
24
# pytest:   assert calc.add(2, 3) == 5
25
#
26
# unittest: self.assertRaises(ZeroDivisionError, calc.divide, 10, 0)
27
# pytest:   with pytest.raises(ZeroDivisionError): calc.divide(10, 0)
28
#
29
# pytest 更简洁直观！

1
import pytest
2

3
# 基础 fixture
4
@pytest.fixture
5
def calculator():
6
    """每个测试自动创建新的计算器实例"""
7
    return Calculator()
8

9
# 使用 fixture
10
def test_add(calculator):
11
    assert calculator.add(2, 3) == 5
12

13
def test_subtract(calculator):
14
    assert calculator.subtract(5, 3) == 2
15

16
# 带清理的 fixture（yield 模式）
17
@pytest.fixture
18
def db_connection():
19
    """测试前连接，测试后关闭"""
20
    conn = Database.connect("sqlite:///:memory:")
21
    conn.create_tables()
22
    yield conn  # yield 之前是 setup，之后是 teardown
23
    conn.close()
24

25
def test_query(db_connection):
26
    db_connection.insert("users", {"name": "Alice"})
27
    result = db_connection.query("SELECT * FROM users")
28
    assert len(result) == 1
29

30
# fixture 作用域
31
@pytest.fixture(scope="session")
32
def app_config():
33
    """整个测试会话只创建一次"""
34
    return load_config()
35

36
@pytest.fixture(scope="module")
37
def api_client():
38
    """每个测试模块创建一次"""
39
    client = APIClient()
40
    yield client
41
    client.close()
42

43
@pytest.fixture(scope="function")  # 默认值
44
def fresh_data():
45
    """每个测试函数创建一次"""
46
    return [1, 2, 3]
47

48
# fixture 依赖注入
49
@pytest.fixture
50
def db(db_connection):
51
    """fixture 可以依赖其他 fixture"""
52
    return UserRepository(db_connection)
53

54
@pytest.fixture
55
def user(db):
56
    """创建测试用户"""
57
    return db.create(name="test_user", email="test@test.com")
58

59
def test_user_creation(user, db):
60
    assert user.name == "test_user"
61
    assert db.find_by_email("test@test.com") is not None
62

63
# fixture 参数化
64
@pytest.fixture(params=["sqlite", "postgres", "mysql"])
65
def db_engine(request):
66
    """为每种数据库引擎运行测试"""
67
    engine = create_engine(request.param)
68
    yield engine
69
    engine.dispose()
70

71
def test_query_all_databases(db_engine):
72
    """此测试会运行 3 次（sqlite/postgres/mysql）"""
73
    result = db_engine.execute("SELECT 1")
74
    assert result is not None
75

76
# conftest.py：共享 fixture
77
# 在 tests/ 目录下创建 conftest.py，所有测试自动可用
78
# tests/conftest.py
79
# @pytest.fixture
80
# def shared_data():
81
#     return {"key": "value"}

1
import pytest
2

3
# 基础参数化
4
@pytest.mark.parametrize("a, b, expected", [
5
    (1, 2, 3),        # 正数
6
    (-1, -1, -2),     # 负数
7
    (0, 0, 0),        # 零
8
    (0.1, 0.2, 0.3),  # 浮点数
9
    (100, 200, 300),  # 大数
10
])
11
def test_add_parametrized(a, b, expected):
12
    calc = Calculator()
13
    assert calc.add(a, b) == expected
14

15
# 带参数 ID（更清晰的测试报告）
16
@pytest.mark.parametrize("input_str, expected", [
17
    ("hello", "HELLO"),
18
    ("World", "WORLD"),
19
    ("123", "123"),
20
], ids=["lowercase", "mixed", "numeric"])
21
def test_uppercase(input_str, expected):
22
    assert input_str.upper() == expected
23

24
# 多参数组合
25
@pytest.mark.parametrize("x", [1, 2])
26
@pytest.mark.parametrize("y", [10, 20])
27
def test_multiply(x, y):
28
    # 会运行 4 次：(1,10) (1,20) (2,10) (2,20)
29
    assert x * y > 0
30

31
# 从文件加载参数
32
import json
33

34
def load_test_cases():
35
    with open("test_cases.json") as f:
36
        return json.load(f)
37

38
@pytest.mark.parametrize("case", load_test_cases())
39
def test_from_file(case):
40
    assert process(case["input"]) == case["expected"]

1
import pytest
2

3
# 自定义标记
4
@pytest.mark.slow
5
def test_large_dataset():
6
    """耗时测试"""
7
    data = list(range(1000000))
8
    assert sum(data) == 499999500000
9

10
@pytest.mark.skip(reason="功能尚未实现")
11
def test_future_feature():
12
    pass
13

14
@pytest.mark.skipif(
15
    sys.platform == "win32",
16
    reason="不支持 Windows"
17
)
18
def test_unix_only():
19
    pass
20

21
@pytest.mark.xfail(reason="已知 Bug #123")
22
def test_known_bug():
23
    assert buggy_function() == "correct"
24

25
# 运行指定标记的测试
26
# pytest -m "not slow"       跳过 slow 标记
27
# pytest -m "slow"           只运行 slow 标记
28
# pytest -m "slow and not skip"  组合标记
29

30
# 注册自定义标记（pytest.ini 或 pyproject.toml）
31
# [tool.pytest.ini_options]
32
# markers = [
33
#     "slow: 标记为耗时测试",
34
#     "integration: 集成测试",
35
#     "unit: 单元测试",
36
# ]

1
# 问题：测试代码依赖外部服务
2
def get_user_info(user_id):
3
    """从 API 获取用户信息"""
4
    response = requests.get(f"https://api.example.com/users/{user_id}")
5
    return response.json()
6

7
# 不用 mock 的问题：
8
# 1. 测试需要网络连接 → CI 环境可能无网络
9
# 2. API 响应不稳定 → 测试时好时坏
10
# 3. API 有调用限制 → 测试消耗配额
11
# 4. 测试速度慢 → 网络延迟
12

13
# 用 mock 解决：
14
# 替换 requests.get，返回预设数据
15
# 测试专注验证逻辑，不依赖外部

1
from unittest.mock import Mock, patch, MagicMock, call
2

3
# 基础 Mock 对象
4
mock_response = Mock()
5
mock_response.status_code = 200
6
mock_response.json.return_value = {"name": "Alice", "age": 30}
7

8
# 使用 mock
9
response = mock_response
10
print(response.status_code)      # 200
11
print(response.json())           # {'name': 'Alice', 'age': 30}
12

13
# 验证调用
14
mock_response.json.assert_called_once()
15
mock_response.json.assert_called_with()
16

17
# Mock 调用记录
18
mock_func = Mock()
19
mock_func(1, 2, key="value")
20
mock_func(3)
21

22
# 检查调用
23
mock_func.assert_called()             # 至少调用一次
24
mock_func.assert_called_once()        # 恰好调用一次（会失败，调了2次）
25
mock_func.assert_called_with(3)       # 最后一次调用的参数
26
mock_func.call_count                  # 2
27
mock_func.call_args_list              # [call(1, 2, key='value'), call(3)]

1
from unittest.mock import patch
2
import requests
3

4
# 方式1：装饰器（推荐）
5
@patch('myapp.services.requests.get')
6
def test_get_user_info(mock_get):
7
    """模拟 API 请求"""
8
    # 配置 mock 返回值
9
    mock_response = Mock()
10
    mock_response.status_code = 200
11
    mock_response.json.return_value = {"name": "Alice"}
12
    mock_get.return_value = mock_response
13

14
    # 调用被测函数
15
    result = get_user_info(123)
16

17
    # 验证结果
18
    assert result["name"] == "Alice"
19

20
    # 验证 mock 被正确调用
21
    mock_get.assert_called_once_with("https://api.example.com/users/123")
22

23
# 方式2：上下文管理器
24
def test_with_context():
25
    with patch('myapp.services.requests.get') as mock_get:
26
        mock_get.return_value.json.return_value = {"name": "Bob"}
27
        result = get_user_info(456)
28
        assert result["name"] == "Bob"
29

30
# 方式3：side_effect 模拟不同返回值/异常
31
@patch('myapp.services.requests.get')
32
def test_api_error(mock_get):
33
    """模拟 API 返回错误"""
34
    mock_get.return_value.status_code = 404
35
    mock_get.return_value.json.return_value = {"error": "Not Found"}
36

37
    # 或模拟异常
38
    mock_get.side_effect = requests.ConnectionError("网络断开")
39

40
    with pytest.raises(ConnectionError):
41
        get_user_info(123)
42

43
# 方式4：模拟多次调用返回不同值
44
@patch('myapp.services.requests.get')
45
def test_multiple_calls(mock_get):
46
    mock_get.side_effect = [
47
        Mock(status_code=200, json=lambda: {"page": 1}),
48
        Mock(status_code=200, json=lambda: {"page": 2}),
49
        Mock(status_code=200, json=lambda: {"page": 3}),
50
    ]
51
    # 第一次调用返回 page 1，第二次 page 2...
52
    assert get_page(1)["page"] == 1
53
    assert get_page(2)["page"] == 2
54
    assert get_page(3)["page"] == 3

1
# pip install pytest-mock
2
# 提供 mocker fixture，更简洁
3

4
def test_get_user_info(mocker):
5
    """使用 pytest-mock"""
6
    mock_get = mocker.patch('myapp.services.requests.get')
7
    mock_get.return_value.json.return_value = {"name": "Alice"}
8

9
    result = get_user_info(123)
10

11
    assert result["name"] == "Alice"
12
    mock_get.assert_called_once()
13

14
# spy：不替换原函数，只监控调用
15
def test_spy(mocker):
16
    """监控真实函数调用"""
17
    spy = mocker.spy(Calculator, 'add')
18

19
    calc = Calculator()
20
    calc.add(2, 3)
21

22
    spy.assert_called_once_with(2, 3)
23
    assert spy.return_value == 5
24

25
# stub：临时替换方法
26
def test_stub(mocker):
27
    """临时替换方法返回值"""
28
    mocker.patch.object(Calculator, 'add', return_value=999)
29

30
    calc = Calculator()
31
    assert calc.add(2, 3) == 999  # 被替换了

1
# 原则1：只 mock 边界（自己拥有的接口）
2
# ✅ 正确：mock 外部依赖
3
@patch('requests.get')
4
def test_fetch_data(mock_get):
5
    mock_get.return_value.json.return_value = {"data": "test"}
6
    result = fetch_data()
7
    assert result["data"] == "test"
8

9
# ❌ 错误：mock 被测对象本身
10
@patch('myapp.Calculator.add')
11
def test_bad(mock_add):
12
    mock_add.return_value = 5
13
    calc = Calculator()
14
    assert calc.add(2, 3) == 5  # 这测试了什么？什么也没有！
15

16
# 原则2：验证行为而非实现
17
# ✅ 验证 API 被调用（行为）
18
mock_get.assert_called_once_with("https://api.example.com/users/123")
19

20
# ❌ 验证内部实现细节（脆弱的测试）
21
mock_get.assert_called_once()
22
assert mock_get.call_args[0][0].startswith("https")
23
assert mock_get.call_args[1]['headers']['Content-Type'] == 'application/json'
24

25
# 原则3：mock 要有明确的返回值
26
# ✅ 明确
27
mock_get.return_value = Mock(status_code=200, json=lambda: {"id": 1})
28

29
# ❌ 不明确（返回默认 Mock，隐藏问题）
30
mock_get.return_value = Mock()  # json() 返回另一个 Mock

1
# .coveragerc 或 pyproject.toml
2
[run]
3
source = src               # 测量 src 目录
4
branch = True              # 启用分支覆盖
5
omit =                     # 排除文件
6
    */tests/*
7
    */__init__.py
8
    */migrations/*
9

10
[report]
11
show_missing = True        # 显示未覆盖的行号
12
skip_covered = False       # 是否隐藏已覆盖文件
13
exclude_lines =            # 排除特定行
14
    pragma: no cover
15
    def __repr__
16
    raise NotImplementedError
17
    if __name__ == .__main__.:
18
    @abstractmethod
19

20
[html]
21
directory = htmlcov         # HTML 报告目录

1
终端报告示例：
2
Name                              Stmts   Miss Branch BrPart  Cover   Missing
3
---------------------------------------------------------------------------
4
src/__init__.py                       0      0      0      0   100%
5
src/calculator.py                    25      1      8      1    94%   42
6
src/services/user_service.py         45      8     12      2    82%   23-30, 55
7
src/api/routes.py                    60     15     10      3    72%   34-48, 67, 89-90
8
---------------------------------------------------------------------------
9
TOTAL                               130     24     30      6    81%
10

11
字段说明：
12
Stmts   语句总数
13
Miss    未执行语句数
14
Branch  分支总数
15
BrPart  未完全覆盖的分支数
16
Cover   覆盖率
17
Missing 未覆盖的行号

1
# TDD 三步循环：Red → Green → Refactor
2

3
# 步骤1: Red — 先写测试（此时会失败）
4
def test_fizzbuzz():
5
    assert fizzbuzz(1) == "1"
6
    assert fizzbuzz(3) == "Fizz"
7
    assert fizzbuzz(5) == "Buzz"
8
    assert fizzbuzz(15) == "FizzBuzz"
9

10
# 运行测试 → 失败（NameError: fizzbuzz 未定义）
11

12
# 步骤2: Green — 写最少代码让测试通过
13
def fizzbuzz(n):
14
    if n % 15 == 0:
15
        return "FizzBuzz"
16
    if n % 3 == 0:
17
        return "Fizz"
18
    if n % 5 == 0:
19
        return "Buzz"
20
    return str(n)
21

22
# 运行测试 → 通过 ✅
23

24
# 步骤3: Refactor — 重构（测试仍通过）
25
# 当前代码已经简洁，无需重构

1
# === 步骤1: Red — 写测试 ===
2

3
def test_password_min_length():
4
    """密码至少 8 位"""
5
    validator = PasswordValidator()
6
    assert validator.validate("Abc123!@") is True
7
    assert validator.validate("short") is False
8

9
# 运行 → 失败
10

11
# === 步骤2: Green — 最少实现 ===
12

13
class PasswordValidator:
14
    def validate(self, password):
15
        return len(password) >= 8
16

17
# 运行 → 通过 ✅
18

19
# === 步骤3: 添加更多测试 ===
20

21
def test_password_requires_uppercase():
22
    """需要大写字母"""
23
    validator = PasswordValidator()
24
    assert validator.validate("abc123!@#") is False
25

26
def test_password_requires_number():
27
    """需要数字"""
28
    validator = PasswordValidator()
29
    assert validator.validate("Abcdefgh!") is False
30

31
def test_password_requires_special_char():
32
    """需要特殊字符"""
33
    validator = PasswordValidator()
34
    assert validator.validate("Abcdefg1") is False
35

36
# 运行 → 部分失败
37

38
# === 步骤4: Green — 更新实现 ===
39

40
import re
41

42
class PasswordValidator:
43
    def validate(self, password):
44
        if len(password) < 8:
45
            return False
46
        if not re.search(r'[A-Z]', password):
47
            return False
48
        if not re.search(r'[0-9]', password):
49
            return False
50
        if not re.search(r'[!@#$%^&*]', password):
51
            return False
52
        return True
53

54
# 运行 → 全部通过 ✅
55

56
# === 步骤5: Refactor — 重构 ===
57

58
class PasswordValidator:
59
    MIN_LENGTH = 8
60

61
    def validate(self, password):
62
        checks = [
63
            len(password) >= self.MIN_LENGTH,
64
            bool(re.search(r'[A-Z]', password)),
65
            bool(re.search(r'[0-9]', password)),
66
            bool(re.search(r'[!@#$%^&*]', password)),
67
        ]
68
        return all(checks)
69

70
# 运行 → 仍然通过 ✅

1
[tool.pytest.ini_options]
2
minversion = "8.0"
3
testpaths = ["tests"]
4
python_files = ["test_*.py"]
5
python_classes = ["Test*"]
6
python_functions = ["test_*"]
7

8
# 命令行默认参数
9
addopts = [
10
    "-v",
11
    "--strict-markers",
12
    "--strict-config",
13
    "--cov=src",
14
    "--cov-report=term-missing",
15
    "--cov-branch",
16
]
17

18
# 自定义标记
19
markers = [
20
    "slow: 标记为耗时测试",
21
    "integration: 集成测试",
22
    "unit: 单元测试",
23
    "e2e: 端到端测试",
24
]
25

26
# 日志配置
27
log_cli = true
28
log_cli_level = "INFO"

1
# 目录结构
2
project/
3
├── src/
4
│   ├── __init__.py
5
│   ├── calculator.py
6
│   └── services/
7
│       ├── __init__.py
8
│       ├── user_service.py
9
│       └── email_service.py
10
├── tests/
11
│   ├── __init__.py
12
│   ├── conftest.py              # 共享 fixture
13
│   ├── unit/                     # 单元测试
14
│   │   ├── test_calculator.py
15
│   │   └── test_user_service.py
16
│   ├── integration/              # 集成测试
17
│   │   ├── test_api.py
18
│   │   └── test_database.py
19
│   └── e2e/                      # 端到端测试
20
│       └── test_user_flow.py
21
├── pyproject.toml
22
└── .coveragerc
23

24
# 命名规范
25
# 测试文件：test_<模块名>.py
26
# 测试类：Test<功能描述>
27
# 测试函数：test_<具体行为>
28
# 示例：test_calculator.py → TestCalculator → test_add_positive_numbers