跳到正文
零到全栈 · 卷 8 · 从作品到产品

测试三层

本合集目录
本章目录

单册说明:本文件是卷 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

第三类最容易被漏掉,也最贵。功能全对、数据全泄,通常就是这里没测。

端到端:三条关键路径足够

「读到」只需要三条:

  1. 注册 → 登录 → 存一条摘录 → 列表里能看到;
  2. 登录 → 打两个标签 → 按其中一个标签筛选 → 只剩对应的条目;
  3. 未登录直接访问 /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` 的契约(大小写不敏感、保序去重),改实现时毫秒级报警;接口测试锁住"这个函数真的被创建接口调用了",防止出现这次事故里的情况——函数改对了,但另一个入口没调用它。单测证明零件对,接口测试证明装上了。

下一步

测试锁住了"不改坏",下一章解决"慢"。先量三个数,再决定压什么、缓存什么、加哪个索引。

→ 卷8-03-性能与缓存.md