handwriting-web 测试体系深度解析:pytest 单元测试 + Playwright E2E 端到端实战

原创2026-10-11 15:06:151,632 阅读

handwriting-web 测试体系深度解析:pytest 单元测试 + Playwright E2E 端到端实战

handwriting-web 是一个把文本转换为模拟手写文字的网页版开源项目。本文带你从三层拆解它的完整测试体系:pytest 单元测试、Playwright 端到端测试、桌面版集成测试——从配置文件到用例设计,帮新手看懂一个手写生成项目如何搭建"测试安全网",并能直接在自己机器上复现。

一、三层测试体系架构:一图看懂

handwriting-web 手写生成效果页:输入文本生成手写体图片

项目把测试按"离真实用户越近、成本越高"的原则分成几层:

层级 位置 工具 守护目标
后端单元测试 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 的通栏长横。

pytest 合成测试页:通栏长横模拟手写稿行距

三个细节非常值得学:

  • 留出容差: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,相当于给安装包上了一道"冒烟闸门"。

handwriting-web 桌面版应用截图:Electron 打包后的手写生成界面

五、前端单元测试:没有框架,照样能测

前端刻意没引入测试框架——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 个启发 🎯

  1. 分层控成本:算法边界用 fake 对象单测,行为正确性留给 E2E,真实浏览器只跑必须跑的用例;
  2. 期望值写死,别引用常量:预算类指标(JPEG 质量、PDF 体积)引用常量等于"自己给自己放水";
  3. 配置里注释为什么:CPU_USAGE_LIMIT、serviceWorkers: "block" 每条配置背后都是踩过的坑,注释就是文档;
  4. expectedFailure 是诚实的缺陷台账:已知问题先标出来跑绿,修好即删,比口头承诺可追踪。

更多架构细节与 CI 约定,可参阅仓库根的 AGENTS.md 与 docs/development.md。

登录后查看全文
handwriting-web