• 后端
• 前端
• CMS

本文以 talebook 仓库中的测试文档为骨架，系统梳理了这个个人书库项目（Tornado + calibre 后端、Nuxt/Vue 前端）的完整测试体系：包括测试框架选型、tests/目录结构、运行与覆盖率命令、测试模块分工、测试数据夹具设计，以及后端 pytest 与前端 Playwright/Vitest 的协同方式。读完本文，你将掌握如何在该仓库中快速定位、运行与扩写测试，并理解其测试基建（内存化服务、会话隔离、mock 用户）的底层原理。

测试框架：pytest 7.4.4 为主，unittest 兼容并存

.planning/codebase/TESTING.md明确了 talebook 的测试框架选型：

• pytest 7.4.4— 主测试框架，负责发现与执行测试；
• pytest-cov— 覆盖率统计与报告生成；
• unittest— Python 标准库，部分历史测试仍沿用其类继承与断言风格。

这些依赖并不是凭空声明，而是固化在仓库的依赖清单里。后端测试依赖集中在 requirements-test.txt：

ruff pytest==7.4.4 pytest-cov flake8 PyYAML

而在 pyproject.toml 中，pytest==7.4.4与pytest-cov>=4.1.0被定义为项目可选依赖组test，同时配置了完整的 Ruff 规则集。值得留意的是 pyproject.toml 中对测试文件的专项放行——**/test_*.py允许assert（S101）并豁免文档字符串要求（D100/D101/D102/D103），说明测试代码遵循"行为验证优先、注释可选"的团队约定；而known-first-party = ["webserver", "app", "tools"]则界定了测试导入时的第一方模块边界。

框架双轨制的原因可以在 tests/run.py 中看到：这个标准库入口以from tests.test_admin import *的方式把多个测试模块聚合进unittest.main()，是早期版本遗留的兼容通道。当前仓库的测试主体已经全面转向 pytest，但unittest.TestCase、mock.patch、setUpModule()等标准库设施仍在测试中被大量使用——二者是互补关系，而非互相替代。

测试目录结构：后端tests/与前端app/test/

原文档给出了tests/的骨架，当前仓库与之一致并有所演进：

tests/ ├── __init__.py ├── run.py # 遗留 unittest 聚合入口 ├── cases/ # 测试数据夹具（SQLite 数据库、样书文件、书源 HTML） │ ├── metadata.db │ ├── big-metadata.db │ ├── users.db / users_old.db / legacy_passwords.json │ ├── new.epub / old.epub / import.mobi / book.txt │ ├── title_has_0x00.pdf │ ├── booksource/ # 书源引擎测试用的 HTML/JSON 样本 │ └── comics/ # 漫画测试夹具（images-rar4.rar、images-rar5.rar、encrypted.cbz） ├── library/ # 测试用书库（按"作者/书名"分层，含封面与多格式样书） │ └── [author]/ │ └── [book]/ │ ├── cover.jpg │ └── *.epub / *.mobi / *.pdf / *.txt / *.azw3 └── test_*.py # 各功能域测试模块

除了后端tests/，仓库还维护了一套完整的前端测试体系（app/test/目录，含components/、composables/、stores/、utils/、e2e/等 29+ 个组件测试与多个 Vitest 用例），由 app/package.json 中的pagewright、@playwright/test、vitest、@nuxt/test-utils驱动。因此 talebook 是"后端 pytest 单测 + 前端组件/E2E 测试"的双层测试布局。

运行测试：从单条 pytest 到 Makefile 一键构建

基础 pytest 命令

原文档给出的四组命令是日常开发的高频入口，均可直接在仓库根目录执行：

# 运行全部测试 pytest tests/ # 带覆盖率运行（HTML 报告输出到 htmlcov/） pytest tests/ --cov=webserver --cov-report=html # 运行单个测试模块 pytest tests/test_main.py # 详细输出运行 pytest -v tests/

终端缺行覆盖率

pytest tests/ --cov=webserver --cov-report=term-missing

--cov=webserver表明覆盖率统计对象是后端核心包（Tornado handler、service、models 等），term-missing会在终端直接列出未被覆盖的行号，方便快速定位漏测分支。

Makefile 封装的目标

仓库 Makefile 把测试与质量检查封装为可复用目标，其中与测试直接相关的有：

make init # 安装 requirements.txt + requirements-test.txt 全部依赖 make test # 在 Docker 的 test 阶段镜像中运行 pytest（输出 unittest.log） make pytest # 等价于 pytest tests -v --cov=webserver --cov-report=term-missing make testv # coverage run -m unittest + coverage report（遗留入口） make testvv # 生成 HTML 覆盖率并起本地 http.server:7777 预览 make lint-py # ruff check + ruff format --diff（静态检查，不改文件） make lint-py-fix # ruff check --fix + ruff format（自动修复格式） make check-i18n # 校验前后端 i18n 翻译键的一致性

其中make test走 Docker 的--target test阶段（见 Dockerfile），并追加--log-file=unittest.log --log-level=INFO把日志落盘，适合 CI 环境排障。make testv/testvv则是与 tests/run.py 配套的遗留 unittest 覆盖通道。make check-i18n调用 scripts/check_i18n_translation_missing.py 与 scripts/check_i18n_translation_useless.py，从测试侧保障前后端翻译键对齐。

测试模块速览：以功能域划分的测试矩阵

原文档列出了一份模块清单，其中test_douban.py、test_tomato_novel.py在当前的仓库中已被拆分/更名。以当前仓库实际文件为准，测试模块按功能域可归为以下几类：

可以看到，测试矩阵已经从原文档时期的"基础功能覆盖"演进为覆盖书源、插件、有声书、升级、安全、CI 的纵深体系，例如 test_scan.py 中针对 PDF 元数据书名异常（issue #770）、重复哈希去重（issue #855）、扫描批次窗口等缺陷都建立了专门的回归测试类。

测试基建：读懂 test_main.py 就掌握了整个测试台

绝大多数测试模块都from tests.test_main import ...，因此 tests/test_main.py 是全仓库测试的"地基"。它提供了以下几项关键设施：

1. 运行时环境装配（setup_server）

shutil.copyfile(testdir + "/cases/users.db", testdir + "/library/users.db") shutil.copyfile(testdir + "/cases/metadata.db", testdir + "/library/metadata.db") main.options.with_library = testdir + "/library/" main.CONF["scan_upload_path"] = testdir + "/cases/" main.CONF["ALLOW_GUEST_PUSH"] = False main.CONF["ALLOW_GUEST_DOWNLOAD"] = False main.CONF["user_database"] = "sqlite:///%s/library/users.db" % testdir main.CONF["AUDIOBOOK_RUNNER_ENABLED"] = False

其作用包括：把cases/里的干净数据库复制到library/隔离副本，避免污染源夹具；把所有路径型配置项（上传、HTML、设置、进度、解压目录）重定向到/tmp/；显式关闭来宾推送、有声书后台任务等会引入副作用的开关。这是"每个测试模块都能拿到确定性初始状态"的关键。

2. 进程级会话与数据库隔离（get_db）

def get_db(): session = _app.settings["ScopedSession"] session.rollback() # 结束当前事务，释放快照与写锁 return session

handler 使用独立 session，测试 session 必须通过rollback()结束当前事务才能读到 handler 刚提交的数据——这正是 tests/test_scan.py 中每个断言前反复出现self.session.rollback()的原因。对 DB 的修改也要求测试代码"改完立即 commit"。

3. Mock 用户与会话

• setup_mock_user()用mock.patch.object(BaseHandler, "user_id", return_value=1)模拟登录态；
• setup_mock_sendmail()打桩calibre.utils.smtp.sendmail，避免测试触发真实邮件发送；
• setup_mock_service()控制AsyncService.async_mode，用于区分同步/后台执行路径（见 tests/test_scan.py 的test_scan_background：断言threading.active_count()增加并轮询队列直到任务完成）。

4. Tornado 测试宿主

TestApp(testing.AsyncHTTPTestCase)将 tornado 的异步测试框架接入 pytest，通过self.json("/api/...", method="POST", body=...)直接驱动真实 HTTP 路由；FakeHandler则把 handler 从 HTTP 栈中剥离出来做纯逻辑级测试。配合temporary_book_scope、temporary_static_host、enabled_builtin_plugin等上下文管理器，测试可以在不污染全局配置的前提下临时切换书库作用域、静态域名或启用某个内置插件。

测试数据与夹具：样例库 + 合成文件双轨

原文档指出"测试夹具在多个测试模块间复用"，仓库实际提供了三层数据：

1. SQLite 数据库夹具（tests/cases/）：metadata.db、big-metadata.db、users.db、users_old.db、legacy_passwords.json（旧密码哈希兼容性测试）、title_has_0x00.pdf（针对文件名含\x00的极端用例）。
2. 样书文件（tests/cases/）：new.epub、old.epub、import.mobi、book.txt——book.txt是 GB18030 编码的真实中文网络小说片段，tests/test_txt.py 用它验证get_file_encoding的编码探测与TxtParser的目录解析（章节起止偏移）。
3. 按作者分层的书库（tests/library/）：严歌苓、海明威、加西亚·马尔克斯、陀思妥耶夫斯基等十余位作者目录，每本样书配cover.jpg与一种格式（EPUB/MOBI/PDF/TXT/AZW3），支撑书库扫描、封面生成、格式转换等场景。

除静态夹具外，测试还大量使用tempfile.TemporaryDirectory()现场合成文件。例如 tests/test_scan.py 的write_supported_media()会按扩展名生成 epub/pdf/cbz/cbr 等受支持媒体，甚至构造PK\x03\x04broken这样的损坏 zip 来验证损坏容器被标记为FAILED并写入analysis_error；漫画夹具放在 tests/cases/comics，用于验证media_type: "comic"的识别逻辑。

扫描状态机（ScanFile.NEW / READY / INDEXED / IMPORTED / FAILED / EXIST）与三种导入模式（copy/move/index）在这些测试中被系统性验证，例如test_import_index_mode_records_original_path_in_calibre断言 index 模式下 Calibre 中记录的是原始路径、删除索引书后源文件依然保留——这些是理解导入语义的"活文档"。

覆盖率：量化后端代码的测试充分度

除文档中的两条命令外，仓库还提供了完整覆盖工作流：

pytest tests/ --cov=webserver --cov-report=term-missing # 终端缺行报告 pytest tests/ --cov=webserver --cov-report=html # HTML 报告（htmlcov/index.html） make testv # 遗留 unittest 覆盖 make testvv # 生成 HTML 并在 7777 端口预览

覆盖率目标集中在webserver/包，因为后端是数据一致性与权限安全的关键区。make testvv将报告输出到.htmlcov/并启动python3 -m http.server 7777，便于在浏览器中按文件、按函数逐行审查未覆盖分支，是定位测试盲点的实用手段。

前端测试：Playwright E2E 与 Vitest 组件测试

后端之外，前端app/拥有独立的测试资产（app/test）：

• 组件/单元测试：app/test/components/（29 个用例）、app/test/composables/、app/test/stores/、app/test/utils/，基于 Vitest +@vue/test-utils+@nuxt/test-utils，配置文件为 app/vitest.config.ts；
• E2E 测试：app/test/e2e/（含 30 个.ts用例与截图断言），基于@playwright/test，配置见 app/playwright.config.ts 与 app/playwright.library.config.ts；
• 统一入口：npm run test执行npx pagewright test，app/package.json 中还提供npm run lint进行 ESLint 检查。

前端测试与后端 pytest 相互独立又共享同一份 i18n 字典与 API 契约，构成完整的"后端逻辑正确性 + 前端交互可用性"双保险。

快速上手：为 talebook 新增一个测试

结合上面的体系，为仓库新增测试的推荐路径是：

1. 选对模块：按功能域找到对应tests/test_*.py（如书库扫描 →test_scan.py，格式解析 →test_txt.py）；
2. 复用基建：通过from tests.test_main import TestWithUserLogin, testdir, get_db继承登录态与 session 管理，必要时用mock.patch打桩邮件、异步服务或 Calibre 后端；
3. 准备夹具：优先使用tempfile.TemporaryDirectory()合成临时文件，或在tests/cases/、tests/library/中追加静态样书；
4. 验证运行：pytest tests/test_xxx.py -v单跑调试，全量回归用pytest tests/ --cov=webserver --cov-report=term-missing，CI 环境则直接make test。

这套"文档 + 源码 + Makefile + 双前端测试层"的组合，让 talebook 的每个功能域都有可独立运行、可验证、可扩展的测试抓手，是理解该项目工程质量与演进历史的理想入口。

• 后端
• 前端
• CMS