外观
建立单元、集成和端到端测试:隔离、异步与 CI
摘要
测试换个顺序就失败,接口替身正常而服务报错。本文面向有开发经验的 Python 初学者,用 pytest 验证测试分层、数据库回滚、异步取消和 CLI 入口。
资料核验日期为 2026-10-29;pytest 官网使用滚动文档,本文不把该页面称为固定版本源码。实际工具版本和运行证据以工程实践与验收手册为准。
本篇实际验证为 Windows x64、CPython 3.13.7、pytest 9.2.0:原顺序与逆函数顺序均十例通过,三种故意坏改动被对应测试捕获,恢复后十例通过。未执行远程 CI。
1. 场景:一次通过为何不够
教学场景中,测试 A 向数据库插入 id 一,测试 B 同样插入 id 一。分别运行成功,一起执行就主键冲突。另一条测试用 sleep 等待异步任务,电脑空闲时能过,CI 繁忙时偶尔失败。开发者增加重试和更长 sleep,测试变慢,却仍不知道错误来自业务、共享状态还是调度。 可进一步阅读时间复杂度如何决定系统上限:性能测试必须控制工作量而非断言固定耗时。
将每条测试看成一个小实验:前提属于谁,触发改变了什么,断言观察哪个状态,失败后如何恢复资源。四步都明确,换执行顺序才不会改变答案。一次绿色结果只说明某组条件下没有被当前断言发现错误,不能省掉前提与清理,再把重试成功叫作可靠。
先预测两个数据库测试各写id一会不会冲突。若共享同一文件且前一条提交未清除,后一条可能冲突;若各用函数级fixture创建的新文件,它们操作的是两个不同状态,id一可以各自存在。需要改变的是状态作用域,而不是让测试B偷偷依赖测试A的执行结果。
pytest 是第三方测试工具,负责发现测试、提供 fixture 与参数化等能力。Fixture 是明确管理测试准备和清理的资源提供方式,不是把全局变量换一个名字。CI 是 Continuous Integration,持续集成:在受控环境里持续检查变更。工具能执行流程,但无法替我们决定“这条测试证明哪件事”。
本篇接续输入校验与测试、事务和事件循环。我们不追求测试行数,而是选择几个不同层次的真实不变量:合法状态码、调用协议、提交/回滚、取消清理、跨进程 CLI 输出。
2. 按被证明的边界划分测试层次
Unit test,单元测试,关注一个小范围逻辑,尽量让外部影响可控。本例 parse_status 接受文本,检查状态码范围;参数化给出正常与非法输入。它不需要启动服务或数据库,所以失败通常直接对应转换或值域规则。若把合法范围扩大到九十九,这层就应立即报错。
Integration test,集成测试,验证多个真实组件之间的协作。本例使用真正的 sqlite3 驱动、临时文件和事务,检查重复键触发回滚。它不会假装连接返回预设结果,因此能发现错误 SQL 和事务边界。它也不证明 PostgreSQL 的隔离级别、连接池或网络中断;同名数据库能力不意味着实现行为完全一致。
End-to-end test,端到端测试,从实际外部入口触发一条完整使用路径,观察协议输出。本例启动 CLI 子进程,传配置与输入文件,检查退出码及 JSON;下一篇再用真实 TCP 请求验证 API。这里“端到端”限定到教学工具的本地文件处理链,不能把它描述成包含所有生产外部系统的验收。
先看同一条状态码读取链:parse_status("99")验证值域;transport替身返回"200"验证调用路径与解析。若继续换成真实网络,HTTP状态、头和字节才进入证据范围,替身绿不能代替这一层。代码长短与文件名称都不能完成扩展。
本例的日志CLI是另一条业务链,却沿用相同的实验设计:由真实子进程触发,观察参数、cwd、环境、退出码和JSON,清理临时文件。规则的内容变了,“前提、触发、观察、恢复”四步仍然适用;不能把它写成状态码网络测试已经完成。
这样划分以后,失败定位也有顺序:值域坏改动先由小范围测试阻止,事务中途提交由真实数据库内容揭露,入口路径错误由跨目录进程测试捕获。不必让每个小测试都启动所有基础设施,但不能让一个窄边界的绿色结果承担宽边界承诺。
图表将在阅读到此处时加载…
图中的连接不是要求测试必须相互依赖执行;每条测试仍独立。它表达证据范围逐渐扩大,而类型检查提供另一类结构证据。不要让端到端测试取代所有小范围检查,否则每次失败都要从整条链反推。
3. Fixture 隔离的是资源,不只是数据表
数据库 fixture 使用 pytest 的 tmp_path 创建每条测试专属临时目录,再打开自己的连接并建立表,yield 把连接交给测试,finally 关闭。默认函数作用域使测试之间不共享连接和文件。两个测试都能使用 id 一,因为它们使用不同数据库;这个条件比每次尝试删除一行更简单、更可靠。
若改成模块或会话级作用域,创建成本可能下降,状态共享却成为新的约束。需要证明每条测试恢复了表内容、事务、连接状态和其他缓存。错误发生时 rollback 不一定恢复已提交的前置数据;把测试全部包在事务里也不自动覆盖业务内部的 commit。选择共享资源前应先解释资源成本是否值得这种复杂度。
资源隔离也包括环境变量、cwd、模块级缓存、事件循环、端口和文件名。修改 os.environ 后必须恢复;更简单的设计是把环境映射作为参数传入。进程级测试使用明确 env,避免运行者的 SERIES_LIMIT 覆盖文件配置。随机端口应让操作系统分配,不能所有测试都固定监听八千端口。
测试数据要表达规则而非复制实现。提交测试验证持久化内容,回滚测试验证一条失败事务不留下第一条插入。若只断言调用了 commit 方法,错误实现也可能先提交部分记录再抛异常,测试却通过。观察真实表内容是这里更直接的不变量。
清理失败也应可见。使用 yield fixture 后的 finally,可在测试断言失败时关闭资源;不能把清理放在断言之后的普通语句,否则提前失败跳过它。异常链篇提醒我们,清理异常可能覆盖主异常;复杂 fixture 应保留两条证据,而不是在 teardown 中捕获所有异常返回成功。
4. 异步测试用事件证明状态,不用 sleep 猜进度
本例不依赖 pytest 的异步插件,而在同步测试中用 asyncio.run 创建并关闭独立事件循环。worker 先设置 started 事件,再等待另一事件;测试等待 started 后取消 task,确认 CancelledError 传播、finally 设置 cleaned、任务结束。这三个验收分别对应已开始、已取消、已清理。
先预测取消后cleaned是否必然为真,再补上前提:取消发生在worker已经进入try之后,才是本测试要验收的场景。轨迹是创建Task、等待started、请求cancel、await收到CancelledError、读取cleaned与task.done。started把取消位置钉在真实执行点,而sleep(0.1)只改变时间,不能保证这个位置已经到达。
因此两秒wait_for只是卡死保护,不是“worker必须两秒内处理完成”的性能指标。把事件检查改回固定sleep,会改变实验前提,却没有改变业务代码;若测试随后偶发失败,先追前提,而不是马上归因于finally或增加重试。
不要用 assert 把所有任务成功完成当成取消正确。本例故意等待取消异常,因为取消就是预期结果。若业务捕获 CancelledError 后继续循环,清理和完成断言应失败;这比检查日志里出现一次“cancelled”更可信。若测试自己在断言失败后留下 task,还应在 finally 取消并等待,避免污染后续事件循环。
复杂服务还需要断开客户端、取消并发子任务、提交副作用与线程工作等测试。asyncio 取消是协作传播,不保证线程立即停止,也不撤销已经提交数据库的写入。当前实验只验证一个协程的取消与 finally,不把它扩写成分布式撤销保证。使用异步 pytest 插件时,还应固定插件版本及 loop fixture 作用域,不能依赖跨版本默认值猜测。
5. 完整测试文件与执行方式
依赖安装使用完整 CPython,嵌入版不用于本篇 pip 环境。Windows 可执行以下命令;类 Unix 平台的虚拟环境解释器位于 .venv/bin/python,本机没有验证该平台。锁定版本来自配套依赖文件,实际验证版本见专题验收记录。
powershell
python -m venv .venv
.venv/Scripts/python.exe -m pip install -r docs/python/examples/capstone/requirements.lock.txt
.venv/Scripts/python.exe -m pytest -q docs/python/examples/27_tests.py完整代码 27_tests.py 包含十个展开后的测试用例:五个状态码参数案例、调用替身、提交、回滚、取消和 CLI。它使用真实 CLI 文件,因此需要保留第二十五篇的配套例子;其余数据每次在临时目录生成,不依赖仓库内历史数据库。
python
"""pytest 测试分层示例;直接运行或 python -m pytest 本文件。"""
import asyncio
import json
import os
from pathlib import Path
import sqlite3
import subprocess
import sys
from unittest.mock import Mock
import pytest
def parse_status(text):
value = int(text)
if not 100 <= value <= 599:
raise ValueError("status outside contract")
return value
def fetch_status(transport):
# 单元替身只证明调用约定,不证明真的存在远程 HTTP 服务。
return parse_status(transport.get("/health"))
@pytest.mark.parametrize("text,expected", [("200", 200), ("500", 500)])
def test_status_valid(text, expected):
assert parse_status(text) == expected
@pytest.mark.parametrize("text", ["slow", "99", "600"])
def test_status_invalid(text):
with pytest.raises(ValueError):
parse_status(text)
def test_transport_contract():
transport = Mock()
transport.get.return_value = "200"
assert fetch_status(transport) == 200
transport.get.assert_called_once_with("/health")
@pytest.fixture
def database(tmp_path):
connection = sqlite3.connect(tmp_path / "events.db")
try:
connection.execute("CREATE TABLE events(id INTEGER PRIMARY KEY, status INTEGER)")
yield connection
finally:
connection.close()
def test_commit(database):
with database:
database.execute("INSERT INTO events VALUES(1,200)")
assert database.execute("SELECT status FROM events").fetchall() == [(200,)]
def test_rollback(database):
with pytest.raises(sqlite3.IntegrityError):
with database:
database.execute("INSERT INTO events VALUES(1,200)")
database.execute("INSERT INTO events VALUES(1,500)")
assert database.execute("SELECT COUNT(*) FROM events").fetchone()[0] == 0
def test_async_cancellation_cleanup():
async def scenario():
started = asyncio.Event()
cleaned = asyncio.Event()
async def worker():
try:
started.set()
await asyncio.Event().wait()
finally:
cleaned.set()
task = asyncio.create_task(worker())
await asyncio.wait_for(started.wait(), timeout=2)
task.cancel()
with pytest.raises(asyncio.CancelledError):
await task
assert cleaned.is_set()
assert task.done()
asyncio.run(scenario()) # 每次有自己的 loop,不依赖异步 pytest 插件。
def test_cli_end_to_end(tmp_path):
config = tmp_path / "config.json"
config.write_text('{"limit": 1}', encoding="utf-8")
(tmp_path / "events.jsonl").write_text('{"at":"2026-01-01T08:00:00+08:00"}\n', encoding="utf-8")
cli = Path(__file__).with_name("25_cli.py")
launch = tmp_path / "launch"
launch.mkdir()
environment = dict(os.environ, PYTHONIOENCODING="utf-8")
environment.pop("SERIES_LIMIT", None)
result = subprocess.run([sys.executable, str(cli.resolve()), "--config", str(config),
"--input", "events.jsonl"], cwd=launch,
env=environment,
capture_output=True, text=True, timeout=10)
assert result.returncode == 0, result.stderr
assert json.loads(result.stdout) == {"total": 1, "times": ["2026-01-01T00:00:00+00:00"]}
if __name__ == "__main__":
raise SystemExit(pytest.main([str(Path(__file__).resolve()), "-q"]))在配套安装环境运行 python -m pytest -q docs/python/examples/27_tests.py,或者直接运行 python docs/python/examples/27_tests.py。预期全部十例通过;具体 pytest 版本、实际运行结果与顺序复测见工程实践与验收手册。不要将未安装 pytest 时的 ImportError 当成业务测试失败,先按解释器与环境确认工具所属环境。
pytest 展开参数化之后的用例数量与函数数量不同。通过 --collect-only -q 可查看发现结果,再用具体 node id 运行单条案例。故障定位时先复现失败最小集合,但不能只留下通过的子集来宣称整个套件正常。修复后应该恢复原触发条件再运行相关套件。
6. 容易踩的坑:替身不证明外部协议,绿色不证明能抓坏改动
Mock 是可记录调用并返回指定结果的替身。transport 测试证明 fetch_status 使用 /health 且正确解析返回文本,不证明 DNS、TLS、HTTP 状态、序列化、超时或真实服务器存在。真实服务返回非二百 HTTP 状态但正文仍有数字时,替身测试并不会覆盖这一风险;需要相应集成或端到端测试。
接口替身应尽量贴近明确协议,必要时用 spec 或 autospec 限制不存在的方法与签名;这仍不能验证远程行为。上一篇Protocol可给业务结构约束,替身可给调用约定,真实实现契约可给存储语义,三者各有范围。没有必要让每条小范围测试都启动所有基础设施,但关键跨边界行为必须有真实证据。
让三条坏改动分别改变一个状态关系,再看哪层断言先失效:
| 只改变的行为 | 运行前预测 | 暴露差异的证据 |
|---|---|---|
| 删除状态码值域检查 | 99不再被拒绝 | 单元非法案例没有得到ValueError |
| 第一次插入后立即commit | 后续重复键失败也撤不回已提交行 | 回滚集成案例的COUNT不再为零 |
| CLI输入改为相对cwd | launch目录找不到配置目录中的日志 | 端到端退出状态或JSON不符 |
这三种故意坏改动的实际捕获范围见本文开头。改动后恢复原实现并相关复测,让测试证明自己对哪一种风险敏感。coverage记录执行范围,而这里的状态差异检验断言是否有用。
覆盖率只告诉我们代码是否执行到,不能告诉我们断言是否观察正确语义。把断言删掉,许多行依旧执行;测试绿并不说明能阻止错误。故意坏改动类似 mutation testing 的思路,即用受控语义变化考察测试敏感性,本篇只做几条有目的的改动,不引入整套变异工具。
7. CI 门禁要记录条件与失败,而不是自动重试到绿
最小门禁先在明确完整 CPython 版本的虚拟环境安装固定依赖,再运行 python -m mypy --strict docs/python/examples/26_protocol.py 和本篇 pytest,最后运行真实 API 端到端示例。使用 python -m 确保工具跟随所选解释器;固定工具版本减少升级导致的规则漂移。依赖锁、可重复构建与部署将由后续工程篇补充。
CI 配置文件本身不等于 CI 已验证。即使 YAML 看起来正确,也可能没有安装依赖、工作目录不对、测试命令永远没有触发。应保存真实执行日志、退出状态与环境版本;远程 CI 没运行就明确写未运行。本篇提供可本地执行的相同门禁命令,不伪造远程流水线状态。
顺序独立性可用显式倒序 node id 再执行一轮,或使用已固定版本的顺序随机化插件。不要新增一个未知插件只为写“支持随机”。如果正常顺序与倒序结果不同,优先查共享资源和清理,不能把一轮重试成功当作修复。并行测试还会引入新的隔离边界,当前顺序独立不证明多进程共享外部系统安全。
8. 独立练习与验收
为 CLI since 扩展添加边界测试,并为仓储写统一分页契约;增加一条异步工作开始后失败仍清理的案例。验收要提交每条测试属于哪层、证明什么、不证明什么;正常顺序和倒序全部通过;故意坏改动在对应层失败;恢复后全部通过。
同时检查数据库文件、任务、环境变量和临时配置没有跨用例残留。为 API 编写后续真实网络验收时,至少区分参数错误、资源不存在和成功分页,不能只打 health。下一篇FastAPI会把这些测试职责落到服务器启动和退出链。
顺序复测与失败定位要保存可读证据
第一次运行套件后,可按收集结果取出两个数据库案例,显式先 rollback 再 commit,之后反过来执行。每次都是新 fixture,若第二种顺序失败,说明存在没有写进 fixture 的状态依赖。当前每个测试各用独立临时路径,顺序不应改变内容;验收关注通过数量和退出状态,不要求机器相关耗时一致。
异步案例也应能单独重复执行。每次 asyncio.run 创建新事件循环,started 与 cleaned 都在该轮内部创建;没有复用上一轮 loop 的 Event 或 Task。若把事件放在模块顶层,让后续测试连接已关闭 loop,就引入另一种隐藏依赖。可重复性来自状态作用域,而不是每次清空全局解释器缓存。
在 CI 中失败后,先保留失败 node id、异常链、解释器身份、工具版本和输入摘要。对于临时目录可保存必要脱敏数据,但不要把全部环境和凭证作为诊断附件。失败重试只能帮助判断是否与时序有关,不能擦掉第一次证据。若只保存最后一次绿,偶发故障会失去最有价值的触发条件。
需要外部服务的集成测试,可明确使用专属数据库或命名空间,并保证清理范围只属于本轮测试。不能在共享环境执行删除全表来获得干净状态。也不能默认所有测试都能被一个事务包住:应用内部提交、独立连接、消息发送可能跨出测试事务。测试层次扩大时,隔离成本要与真实跨边界风险一起设计。
最后检查断言是否表达业务。response is not None、len(rows) >= 0 几乎不限制行为;应检查具体状态、记录集合、顺序、游标和错误代码。对于性能不确定值采用有依据的预算和统计方法;对于本篇确定的功能结果则要求精确。模糊断言不是抵抗环境波动,而可能掩盖错误。本篇故意坏改动实验可以直接检验这点。
一句话总结:可信测试用明确前提触发行为,在正确边界观察结果,并能独立重复地抓住相关坏改动。
- 单元、集成、端到端测试分别证明不同范围,替身不能代表真实外部协议。
- Fixture 和事件同步使资源、顺序与异步状态成为显式条件。
- CI 应记录真实执行与失败证据,类型检查和行为验收共同形成门禁。
参考:pytest fixtures、pytest parametrize、unittest.mock、asyncio。实际版本与运行范围见工程实践与验收手册。