测试三层
本合集目录
本章目录
单册说明:本文件是卷 8 的第 2 章,可独立阅读。前置:第 1 章(主线已收敛)。本章给「读到」的主线装上 9 条自动化测试:5 条单元测试、4 条接口测试,其中一条专门验证越权。全部代码可直接运行。
| 项 | 内容 |
|---|---|
| 所属卷 | 卷 8 · 从作品到产品(第 2 / 6 章) |
| 前置章节 | 8.1 需求收敛与 MVP |
| 本章产出 | backend/tests/ 下 9 条测试 + 一套"每次测试用独立库"的 fixture |
| 对应代码 | tests/conftest.py、tests/test_keywords.py、tests/test_notes_api.py |
| 配图 | 无(后续统一制图) |
| 读完的判定 | 能在不启动服务器、不碰开发库的情况下,一条命令跑完主线回归 |
8.2.1 一句话结论:测试不是证明你对,是让你敢改
上线第三周,你改了标签的规范化逻辑:输入统一转小写、去掉首尾空格。改动只有三行,你手工点了一遍"新建摘录 → 输入标签 → 保存",正常。部署。
十分钟后,日志开始刷:
sqlite3.IntegrityError: UNIQUE constraint failed: tags.name
原因是另一个入口——批量导入——没走同一个规范化函数,Python 和 python 被当成两个标签插入,第二个撞上唯一约束,整个请求 500。你手工测的那条路径,恰好只输入了一个标签。
一句话结论:测试的价值不在"证明现在是对的",而在"下次改动时,能在 30 秒内知道有没有弄坏别的路径"。
没有测试的项目,改一行代码要靠"回忆 + 手点 + 祈祷";有测试的项目,改完跑一条命令,红绿分明。前者会让人越来越不敢动,后者才谈得上迭代。
8.2.2 原理与方法
三层各测什么
| 层 | 测的对象 | 「读到」里的例子 | 一条的成本 | 跑一次 | 失败时能否直接定位 |
|---|---|---|---|---|---|
| 单元测试 | 纯函数:给定输入,输出是否确定 | 关键词切分、标签去重与规范化 | 5–15 分钟 | 毫秒 | 能,直接指向函数 |
| 接口测试 | 一个 HTTP 端点:状态码、权限、边界 | POST /api/notes、越权读别人的摘录 |
20–40 分钟 | 几十毫秒 | 能,指向路由 + 依赖 |
| 端到端 | 真实浏览器里的完整路径 | 注册 → 登录 → 存摘录 → 按标签筛选 | 1–2 小时 | 几秒到几十秒 | 难,只能知道"这一步挂了" |
三层不是按"重要性"分的,是按反馈速度与定位精度分的。越往下越接近真实用户,越往上越接近出错的那一行。
测试金字塔为什么不能倒过来
倒金字塔是:少量单测 + 大量端到端。它看起来"更真实",实际有三个具体代价:
| 代价 | 表现 | 数字感 |
|---|---|---|
| 慢 | 每次提交都等浏览器启动、登录、点按 | 单测毫秒级,E2E 每条 5–20 秒 |
| 脆 | 改一个按钮文案、换一个选择器就红 | 一个 UI 改动可能连带 10 条失败 |
| 定位难 | 只看到"第 3 步超时",不知道是路由、SQL 还是前端 | 排查时间常常超过写测试的时间 |
正确的比例大致是:大量单测打底,接口测试覆盖主线的每个端点,端到端只留 3 条最关键路径。端到端的作用不是"覆盖功能",是"确认这些零件真的装在一起还能转"。
单元测试:只测纯逻辑
判断标准很简单:这个函数不碰数据库、不发网络请求、不看当前时间,就适合单测。「读到」里有三类函数值得测:
| 函数 | 输入 | 输出 | 为什么值得测 |
|---|---|---|---|
tokenize(text) |
一段摘录 | 词元列表 | 中英文混排、停用词、单字,规则多且容易改坏 |
top_keywords(text, limit) |
文本 + 上限 | [(词, 次数)] |
排序规则(次数相同按字典序)是隐性契约 |
normalize_tags(names) |
用户输入的标签数组 | 去重后的规范标签 | 大小写、空格、空串、超长,边界最多 |
不要在这层测"路由是否返回 200",那是接口层的事;也不要在这层连数据库,那会让每条测试慢十倍,还得清理数据。
标签规范化的测试可以短到两行,价值却很高:
def test_normalize_tags_is_case_insensitive_and_ordered():
assert normalize_tags(["Python", " python ", "SQL", "python"]) == ["python", "sql"]
它锁住两个契约:大小写不敏感、保留首次出现顺序。以后谁改实现,只要破坏这两点就会红。
接口测试:状态码、权限、边界
接口层是投入产出比最高的一层。一条接口测试同时穿过:路由匹配、Pydantic 校验、鉴权依赖、SQL 语句、响应序列化。换句话说,它用一条测试覆盖了五处可能出错的地方。
每条接口至少写四类断言:
| 类型 | 例子 | 期望 |
|---|---|---|
| 未认证 | 不带 Cookie 调 POST /api/notes |
401,且不写库 |
| 正常路径 | 登录后创建,再读回 | 201 / 200,字段一致 |
| 越权 | 用户 B 读用户 A 的摘录 id | 403(或 404,但必须稳定) |
| 边界 | 空标题、超长标题、不存在的 id | 422 / 404,不是 500 |
第三类最容易被漏掉,也最贵。功能全对、数据全泄,通常就是这里没测。
端到端:三条关键路径足够
「读到」只需要三条:
- 注册 → 登录 → 存一条摘录 → 列表里能看到;
- 登录 → 打两个标签 → 按其中一个标签筛选 → 只剩对应的条目;
- 未登录直接访问
/notes→ 跳转到登录页,登录后回到原页面。
这三条覆盖了"人能不能完成主线"。其余细节(按钮颜色、错误提示文案)交给接口测试和肉眼,不要写进 E2E。
fixture 与临时数据库
fixture(测试夹具)就是"测试前把环境准备好、测试后收拾干净"的那段代码。测试最怕两件事:污染开发库、测试之间互相影响。前者会让你某天发现本地账号全没了,后者会让测试"单跑通过、一起跑失败"。
解决办法是两层:
| 机制 | 作用 |
|---|---|
tmp_path |
pytest 内置 fixture,每个测试给一个全新的临时目录,测完自动清理 |
dependency_overrides |
FastAPI 官方钩子,把 get_db 换成指向临时库的版本,业务代码一行不改 |
数据库文件的路径必须每个测试一个,不能共用。共用会有顺序依赖:A 测试插入的用户,让 B 测试的"邮箱唯一"断言失败。
fixture 的作用域也要选对:
| 作用域 | 生命周期 | 适合什么 |
|---|---|---|
function(默认) |
每个测试一次 | 数据库、客户端——要隔离就用它 |
module |
每个文件一次 | 只读的配置、昂贵的解析结果 |
session |
整个测试过程一次 | 启动一次就很慢的外部资源 |
数据库 fixture 永远用 function。 快的那点时间,不值得用"测试互相污染"来换。
钱花在接口层
如果时间只够写 10 条测试,分配应该是:2 条单测(最容易被改坏的两个纯函数)+ 7 条接口测试(主线四个端点 × 正常/异常)+ 1 条端到端(完整走一遍)。理由:
- 单测再快,也只能证明函数对,证明不了它被正确调用;
- E2E 再真,也只能告诉你"挂了",不能告诉你"哪挂了";
- 接口测试正好卡在中间:够真实,又够精确。
覆盖率:看缺口,不看数字
覆盖率(coverage)回答的是"哪些代码从没被执行过",不是"断言写得对不对"。「读到」这种规模,大致区间如下:
| 覆盖率 | 含义 | 该做什么 |
|---|---|---|
| 30% 左右 | 只覆盖了主线的一部分 | 先补越权和错误路径,别急着加新功能 |
| 70% 左右 | 主线的正常 + 异常都走过了 | 够了,把时间还给性能和安全 |
| 95% 以上 | 很可能有大量"只调用、不断言"的测试 | 抽查断言,别用数字安慰自己 |
一条 assert resp.status_code == 200 就能让整段路由算作"已覆盖",但它没有验证返回内容。覆盖率高不等于测试有用,这是这一节唯一要记住的话。
8.2.3 动手:九条测试
第一步:装依赖
cd backend
python -m pip install pytest httpx
# 把 pytest 与 httpx 两行写进 requirements-dev.txt,不要整份 freeze
httpx 是 TestClient 的底层依赖,不装会在导入时报 ModuleNotFoundError。生产依赖(requirements.txt)里不需要它。
本章假设卷 6 的分层结果是:app/storage/db.py 暴露 connect(path)、init_db(conn)、get_db();app/main.py 暴露 app;鉴权用 sid Cookie。若你的函数名不同,只需改 conftest.py 顶部两行 import,测试本身一字不动。
第二步:写 tests/conftest.py
import sys
from pathlib import Path
import pytest
from fastapi.testclient import TestClient
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
from app.main import app
from app.storage.db import connect, get_db, init_db
@pytest.fixture()
def db_path(tmp_path):
"""每个测试一个全新的库文件,测完即弃。"""
path = tmp_path / "test.db"
conn = connect(path)
init_db(conn)
conn.close()
return path
@pytest.fixture()
def make_client(db_path):
"""按需创建多个客户端,用于模拟不同用户。"""
opened = []
def _make():
def override_get_db():
conn = connect(db_path)
try:
yield conn
finally:
conn.close()
app.dependency_overrides[get_db] = override_get_db
client = TestClient(app)
client.__enter__()
opened.append(client)
return client
yield _make
for client in opened:
client.__exit__(None, None, None)
app.dependency_overrides.clear()
@pytest.fixture()
def client(make_client):
return make_client()
@pytest.fixture()
def auth():
"""注册并登录,返回同一个客户端(Cookie 已在里面)。"""
def _auth(client, email="[email protected]", password="correct-horse-9"):
client.post("/api/auth/register", json={"email": email, "password": password})
resp = client.post("/api/auth/login", json={"email": email, "password": password})
assert resp.status_code == 200, resp.text
return client
return _auth
三个细节值得说清:
client.__enter__():TestClient作为上下文管理器会触发应用的 startup 事件(初始化连接池、加载配置)。直接实例化不进入上下文,某些项目会在第一个请求时报"资源未初始化"。make_client而不是单个client:越权测试需要两个"浏览器",各自持有自己的 Cookie。app.dependency_overrides.clear()放在yield之后:即使测试失败也会执行,避免污染下一个测试文件。
第三步:5 条关键词单测
from app.services.keywords import tokenize, top_keywords
def test_tokenize_lowercases_and_drops_stopwords():
assert tokenize("The Quick API and the api") == ["quick", "api", "api"]
def test_tokenize_chinese_uses_bigrams():
tokens = tokenize("读到是个人知识小站")
assert tokens[:2] == ["读到", "到是"]
assert len(tokens) == 8
def test_top_keywords_sorts_by_count_then_name():
result = top_keywords("api api api test test zzz")
assert result == [("api", 3), ("test", 2), ("zzz", 1)]
def test_top_keywords_respects_limit():
assert len(top_keywords("api test zzz", limit=2)) == 2
def test_top_keywords_handles_empty_text():
assert top_keywords("") == []
这五条对应五种真实会坏的地方:大小写没统一、中文被整段当成一个词、并列次数的顺序不稳定(导致同样的输入每次显示不同)、limit 被忽略、空文本抛异常。第二条尤其重要——中文没有空格,按空格切会得到一整段,关键词统计直接失效。
第四步:4 条接口测试
def test_create_note_requires_login(client):
resp = client.post("/api/notes", json={"title": "未登录", "content": "应该被拦"})
assert resp.status_code == 401
def test_create_then_read_own_note(client, auth):
auth(client)
created = client.post(
"/api/notes",
json={"title": "闭包", "content": "函数记住定义时的作用域", "source_url": "https://example.com/a"},
)
assert created.status_code == 201
note_id = created.json()["id"]
fetched = client.get(f"/api/notes/{note_id}")
assert fetched.status_code == 200
assert fetched.json()["title"] == "闭包"
def test_cannot_read_other_users_note(make_client, auth):
alice = auth(make_client(), email="[email protected]")
bob = auth(make_client(), email="[email protected]")
note_id = alice.post("/api/notes", json={"title": "私有", "content": "只给 alice 看"}).json()["id"]
resp = bob.get(f"/api/notes/{note_id}")
assert resp.status_code == 403
def test_blank_title_rejected(client, auth):
auth(client)
resp = client.post("/api/notes", json={"title": " ", "content": "有内容但没标题"})
assert resp.status_code == 422
第三条是这一章最值钱的一条。它同时验证了两件事:查询没有漏掉 user_id 条件,以及越权时返回的是明确的拒绝而不是 404 或 200。很多人只测"我能看到自己的",不测"他看不到我的"——后者才是漏洞。
第五步:跑
python -m pytest -q
输出形如:
......... [100%]
9 passed in 2.00s
常用参数:
| 命令 | 用途 |
|---|---|
pytest -q |
安静模式,只看结果 |
pytest -x |
遇到第一个失败就停,改代码时用 |
pytest -k note |
只跑名字含 note 的测试 |
pytest --lf |
只重跑上次失败的(last failed) |
pytest -vv |
显示每条测试名,定位断言差异时用 |
9 条测试两秒跑完,意味着你可以每改一次代码就跑一次。这就是"敢改"的来源。
8.2.4 三个坑
坑 1:测试连上了开发库
症状:跑完测试,本地登录不上;打开 data/dudao.db,users 表空了。
成因:conftest.py 直接用了 get_db 的默认路径,测试里的"清空表"操作打在开发库上。
修法:数据库路径必须由 fixture 注入,且断言它不等于开发库路径。可以在 db_path 里加一行:assert "dudao.db" not in str(path),让错误在第一时间暴露。
坑 2:把端到端当主力
症状:CI 跑 18 分钟,随机红一条,重跑就过;改了按钮文案,挂了 6 条 E2E。 成因:倒金字塔 + 用例之间共享登录状态和数据,彼此干扰。 修法:把断言下沉到接口层——"存了能读回"用接口测,"点按钮有反应"用肉眼测。E2E 只保留三条主线,每条用独立账号,互不依赖。
坑 3:只测 happy path
症状:上线后才发现未登录能创建、别人能读自己的摘录、空标题写进了库。 成因:写测试时复制成功用例,只改输入不改断言;或者觉得"异常路径不会发生"。 修法:每个端点强制配一条"不该成功"的用例(401 / 403 / 422 三选一),并把这条写进验收清单。数量上,异常用例至少要和正常用例一样多。
本章验收
-
pytest -q能在 5 秒内跑完,且 9 条全绿 - 测试全程不写
data/dudao.db(跑完检查文件修改时间不变) - 有一条测试专门验证"用户 B 读不到用户 A 的摘录",且断言 403
- 单测不连数据库、不发网络请求
- 新增一个接口时,能照着模板补上正常 + 异常两条用例
- 知道
-x、-k、--lf三个参数各自什么时候用
自测
Q1:为什么数据库 fixture 要用 function 作用域,而不是 session?
看答案
因为测试之间必须隔离。`session` 作用域下所有测试共用一个库,A 插入的用户会让 B 的"邮箱唯一"断言失败,而且失败顺序依赖执行顺序,极难排查。`function` 每条测试新建一个临时文件,代价是几毫秒,换来的是"任意单跑、任意排序都稳定"。Q2:接口测试里,越权为什么断言 403 而不是 404?两种都可以吗?
看答案
两种都能堵住漏洞,但要选一个并保持一致。403 明确表示"你登录了,但无权访问";404 则隐藏资源是否存在,能减少枚举信息。「读到」的约定是 403,因为调试更直观。关键是:不能一处 403、一处 200,也不能对"不存在"和"不属于你"返回不同结构,否则等于告诉攻击者哪些 id 真实存在。Q3:一条单元测试和一条接口测试都能发现"标签没转小写",应该写哪条?
看答案
两条都写,但目的不同。单测锁住 `normalize_tags` 的契约(大小写不敏感、保序去重),改实现时毫秒级报警;接口测试锁住"这个函数真的被创建接口调用了",防止出现这次事故里的情况——函数改对了,但另一个入口没调用它。单测证明零件对,接口测试证明装上了。下一步
测试锁住了"不改坏",下一章解决"慢"。先量三个数,再决定压什么、缓存什么、加哪个索引。