handwriting-web 测试体系深度解析:pytest 单元测试 + Playwright E2E 端到端实战
handwriting-web 测试体系深度解析:pytest 单元测试 + Playwright E2E 端到端实战
handwriting-web 是一个把文本转换为模拟手写文字的网页版开源项目。本文带你从三层拆解它的完整测试体系:pytest 单元测试、Playwright 端到端测试、桌面版集成测试——从配置文件到用例设计,帮新手看懂一个手写生成项目如何搭建"测试安全网",并能直接在自己机器上复现。
一、三层测试体系架构:一图看懂
项目把测试按"离真实用户越近、成本越高"的原则分成几层:
| 层级 | 位置 | 工具 | 守护目标 |
|---|---|---|---|
| 后端单元测试 | backend/tests/ |
pytest + unittest | 边距识别、排版、PDF 导出等核心算法 |
| 前端单元测试 | frontend/tests/ |
node + assert | 书信排版纯函数逻辑 |
| E2E 端到端 | e2e/tests/ |
Playwright | 真实前后端渲染的主流程 |
| 桌面版 E2E | e2e/desktop-tests/ |
Playwright _electron |
打包后的 Electron 真实产物 |
| 压测 | backend/tests/locustfile.py | Locust | 生成任务队列的并发能力 |
核心思路:能 mock 的绝不起浏览器,必须起浏览器的用例才付 E2E 的成本。
二、pytest 单元测试:用合成图测 OpenCV 识别
后端测试入口配置在 backend/pytest.ini,只有一行关键逻辑:
markers =
load: 需要真实后端在跑的压测,默认不跑
addopts = -m "not load"
-m "not load" 让标了 load 标记的并发压测默认被跳过——CI 里没有服务在跑,这些用例必然失败。需要时先启动 5005 端口的服务,再用 pytest -m load 显式运行。而 backend/tests/conftest.py 则把 backend/ 根目录注入 sys.path,让测试可以直接 import app、import identify。
合成图片 + 容差断言:边距识别测试的巧思
test_identify.py 测试"上传扫描页、自动识别四周边距"功能。它没有用真实扫描件,而是用 PIL 程序化画一张 合成页面:800x1000 白纸、左右边距 60、行距 70 的通栏长横。
三个细节非常值得学:
- 留出容差:
assertAlmostEqual(left, 60, delta=4)。因为opencv-python没钉版本,不同 CI 机器形态学结果会差一两像素,写死相等必挂; expectedFailure当缺陷台账:行距被错算成笔画厚度、纯白图导致接口 500 两个已知缺陷,直接用@unittest.expectedFailure标出来(见 test_identify.py#L67-L85),修好后删掉标记即可,比维护一份"已知问题文档"诚实得多;- 和 E2E 共用一份数据:这张合成图与
e2e/fixtures/sample-page.png用同一套几何参数生成,前后端两个用例盯的是同一份数据。
Fake 字体引擎:排版与 PDF 导出测试
test_text_layout.py 用 FakeFont / FakeTemplate 假对象替换 handright 排版引擎的字体接口,专测落款右对齐、手动分页标记、负字距换行等边界;而 test_pdf_export.py 有一个反直觉但聪明的设计:
# 写死期望值:跟着 PDF_JPEG_QUALITY 走的话,常量被改回高位时用例还是会过
EXPECTED_JPEG_QUALITY = 75
期望值写死而不是引用常量——这样有人把 JPEG 质量悄悄调回 95(导致 PDF 体积翻倍)时,用例才会真正拦住它。
并发方面,test_generate_concurrency.py 用 ThreadPoolExecutor 向真实后端的 /api/generate_handwriting 发并行请求统计耗时;更重的场景则由 Locust 脚本 承接,命令行模式一键压测:
locust -f locustfile.py --host=http://127.0.0.1:5005 --headless -u 20 -r 5 --run-time 60s
三、Playwright E2E 配置:前后端自动拉起,零手动准备
e2e/playwright.config.js 是这套 E2E 的"发动机",几个配置都解决过真实痛点:
webServer自动起服务(playwright.config.js#L85-L106):跑测试时自动启动 uvicorn 后端(5005)和npm run serve前端(8080),并轮询/api/fonts_info确认就绪。你不需要手动开任何服务;- 智能探测 Python 解释器:
resolvePython()会挨个尝试 venv、python3等候选,只认能import fastapi/handright/cv2/fitz的那个(playwright.config.js#L45-L64),避免系统 Python 依赖冲突把 E2E 搞挂; - 禁用 Service Worker:
serviceWorkers: "block"——应用注册的 SW 会在测试中途 confirm + reload 页面,直接断言失败; - 失败保留现场:
trace: "retain-on-failure"+ 失败截图,CI 红了不用猜; - 抬高 CPU 阈值:
CPU_USAGE_LIMIT: "100"防止测试机 CPU 被 dev server + 浏览器占满时,触发应用自身的过载保护(429)误伤用例。
共享 fixtures:小画布让真实渲染只要 2 秒
e2e/tests/fixtures.js 抽出了所有用例共用的动作:openHome 等字体列表加载完、fillText 填文本、useSmallCanvas 把画布缩到 400x300——真实渲染照样走,只是小画布下约 2 秒就出图,而不是等一张 A4 尺寸的大图。另外 blockThirdParty 拦截了 GA、Sentry 等第三方脚本,既不拖慢首屏也不污染真实监控数据。
主流程断言到"文件头"级别
home-generate.spec.js 的主流程用例断言之精细,值得逐条看:
- 生成 ZIP:下载
images.zip后直接校验前两个字节是PK(真实压缩包头),且体积大于 1000 字节; - 生成 PDF:断言文件以
%PDF-开头(不是套着 PDF 的 zip),且体积 < 24 KB——注释里写明了质量 95 时同一页约 27 KB,这条线就是"导出体积预算",质量参数被调回高位会立刻红; - 前端拦截:字号 200 > 行距 100 时点击预览,断言出现"字体大小不能大于行间距"提示,并且用
page.route拦截确认请求根本没发出。
websocket-task.spec.js 则盯住一个平时看不见的降级路径:任务状态本应走 WebSocket 推送,连不上时前端会静默退化成轮询。用例监听 /api/generate_handwriting/ws/ 的帧,验证收到 completed 帧且没有触发轮询接口——"两条路径出图效果一样"的隐患就是这么被抓住的。
而 error-paths.spec.js 展示了 E2E 里该 mock 的时候别客气:队列满 503(要凑满 8 个排队任务)、后端 400 这些真实后端很难触发的分支,用 route.fulfill 直接伪造响应,验证前端倒计时提示和按钮禁用。
还有一个"零框架"思路:i18n.spec.js 不用翻译表副本,而是用 Node 的 vm 模块直接求值 frontend/src/i18n.js 源文件,检查中英文案键的一致性——检查的是真实源码,永远不会"测试副本和实现脱节"。
四、桌面版 E2E:驱动真实的 Electron 打包产物
桌面版走独立的 e2e/playwright.desktop.config.js:不启浏览器、不起 webServer,直接驱动 desktop/build/installer/ 里构建出来的真实 Electron 应用。因为起一个实例要十几秒且都抢固定端口,这里强制 workers: 1 串行执行、单用例超时给到 3 分钟,并开启失败保留 trace。CI 里桌面版测试不过就不发 Release,相当于给安装包上了一道"冒烟闸门"。
五、前端单元测试:没有框架,照样能测
前端刻意没引入测试框架——chineseLetterFormatter.test.js 就是原生 node + assert,一个手写的 test() 注册函数加 import() 动态加载 .mjs 源码:
cd frontend && npm run test:letter-format
它测的正是书信排版核心:自动识别末尾署名和日期、段落首行缩进、>>> 右对齐标记、保留手动分页符。够用、零依赖,就是最好的选型。
六、跑起来:全部测试的运行命令清单
克隆仓库(首次需要):
git clone https://gitcode.com/gh_mirrors/ha/handwriting-web
cd handwriting-web
后端单元 / 负载测试(先建 venv):
python -m venv venv
venv/bin/python -m pip install -r backend/requirements.txt
cd backend && ../venv/bin/python -m pytest # 默认单测
../venv/bin/python -m pytest -m load # 需先启动 5005 后端
E2E 端到端(Playwright 会自动拉起前后端):
cd e2e
npm install && npx playwright install chromium
npm test
桌面版 E2E(需先构建打包产物):
bash desktop/build.sh --app-only
cd e2e && npm run test:desktop
七、这套测试体系给新手的 4 个启发 🎯
- 分层控成本:算法边界用 fake 对象单测,行为正确性留给 E2E,真实浏览器只跑必须跑的用例;
- 期望值写死,别引用常量:预算类指标(JPEG 质量、PDF 体积)引用常量等于"自己给自己放水";
- 配置里注释为什么:
CPU_USAGE_LIMIT、serviceWorkers: "block"每条配置背后都是踩过的坑,注释就是文档; expectedFailure是诚实的缺陷台账:已知问题先标出来跑绿,修好即删,比口头承诺可追踪。
更多架构细节与 CI 约定,可参阅仓库根的 AGENTS.md 与 docs/development.md。


