企业官网建设流程全解析

IELTS-practice 是一个纯前端的雅思阅读与听力练习系统，支持题库浏览、套题练习、成绩记录、错题分析与本地数据备份。由于没有后端和服务器环境，传统意义上的"接口测试"在这里行不通——该项目选择用静态CI检查 + 单元/集成测试 + E2E端到端测试的三道质量门禁来守护每次改动。本手册带你从零看懂这套体系如何运转。

一、先看全局：三层质量门禁总览

项目的测试资产集中在 developer/tests/ 目录，整体架构可以概括为"由轻到重"的三层防线：

统一入口 developer/tests/run_all_tests.py 会按顺序执行三层测试并生成综合报告，支持--only-ci、--skip-e2e等参数按需裁剪，日常开发可以先跑轻量层，提交前再全量验证。

二、静态CI：不启动浏览器的"结构护栏"

静态CI的核心是 developer/tests/ci/run_static_suite.py（用法见 developer/tests/ci/README.md），它用正则与HTML解析器对仓库做"体检"，检查项非常贴近前端项目的真实痛点：

• 入口骨架校验：index.html必须包含<!DOCTYPE html>、按预期加载 4 个核心 bundle、禁止内联脚本与内联事件，防止启动逻辑被悄悄改坏；
• 构建一致性：校验 bundle 中不得残留已删除的旧模块引用、可选听力资源不得被误打包进核心 bundle；
• 懒加载与启动守卫：确认 js/app/main-entry.js 保持严格按需加载、无阻塞式预加载片段；
• 发布包审计：当存在构建产物 zip 时，逐条检查其中的 bundle 清单，并拒绝模板文件、Office 临时文件、视频等大体积"杂质"进入发布包。

静态层还配了几个专项数据质检脚本，例如 developer/tests/ci/check_reading_data_integrity.py 会扫描全部阅读题库 JS 文件，检测重复题目与PDF 引用失效（已知重复通过 reading-duplicate-allowlist.json 白名单放行）；check_reading_explanation_quality.py 则把关解析内容的质量。

💡 对纯前端项目的启示：没有后端，恰恰意味着"文件即接口"——HTML 里引了哪些脚本、题库数据引用是否完整，都可以（也应当）在静态阶段被机械地验证。

三、单元与集成测试：Vitest 驱动的核心逻辑验证

JavaScript 测试由 Vitest 驱动，配置见 developer/vitest.config.js（匹配tests/js/**/*.test.js），依赖声明在 developer/package.json 中，常用命令包括：

npm run test:unit # 运行全部单元测试 npm run test:property # 仅运行属性测试

测试文件位于 developer/tests/js/，共 40 余个用例，覆盖练习核心、成绩存储、数据一致性、备份恢复、词库调度等模块。一个典型例子是 practiceCore.test.js：它用 Node 的vm沙箱加载真实源码，再挂上内存版的仓储实现来验证练习记录的上报与落库逻辑——不依赖浏览器、不依赖真实存储，跑得又快又稳。

更值得注意的是项目引入了fast-check 属性测试（见 developer/package.json 中的 devDependencies）：不枚举具体输入，而是让框架随机生成海量数据，反复验证"任意合法输入下答案比对、数据序列化都不应破坏不变量"这类性质。

四、E2E 测试：让真实浏览器走完一次完整练习

最重量级的门禁是 E2E 测试，全部位于 developer/tests/e2e/，使用 Playwright 驱动真实 Chromium（环境准备与调参技巧见 RUN_E2E_TESTS.md）。

统一入口 e2e_runner.py 串行执行三条主流程，任何一条失败即整体判负：

1. 浏览偏好流程browse_preference_toggle_flow.py——开关偏好项并验证持久化；
2. 阅读单题流程reading_single_flow.py——打开题目、作答、提交、核对成绩；
3. 套题练习流程suite_practice_flow.py——完整走一遍"进入套题→完成 3 篇→查看练习记录→打开记录详情"，并截取屏幕留证。

此外还有听力练习流程、路径兼容性、拖拽回归、往返恢复回归等专项脚本，每个脚本都会输出 JSON 报告与截图到developer/tests/e2e/reports/，失败时可以对照截图快速定位。测试通过标准在 developer/docs/testing-guide.md 中有明确清单，例如"题库列表正常渲染、无关键控制台错误、截图成功保存"。

五、新手实践清单：如何为自己的纯前端项目抄作业

• 第一步：给仓库写静态护栏。定义好"哪些文件必须存在、哪些片段绝不能出现、哪些数据引用必须有效"，用脚本机械检查——这正是 run_static_suite.py 的做法，几秒内就能拦下大量低级回归；
• 第二步：把核心逻辑抽出来做单元测试。纯前端项目最难测的往往就是存储与状态，参考 developer/tests/js/ 的"内存仓储 + vm 沙箱"模式即可低成本落地；
• 第三步：用 Playwright 固化 2~3 条黄金路径。不要追求覆盖率，只测"用户每天必走"的流程，配合截图与 JSON 报告保证失败可追溯；
• 第四步：统一入口 + 报告。用 run_all_tests.py 这种聚合脚本把三层门禁串起来，报告统一落盘，随时可以diff前后两次结果做回归对比。

六、常见问题速查

• Playwright 报错 No module named 'playwright'？执行pip install playwright后运行playwright install chromium；
• 测试超时？优先检查应用本身能否正常打开，再考虑调大 timeout；
• 想边看边调？把headless改为False并加slow_mo=1000，每一步都看得清清楚楚；
• 报告去哪找？基线报告在developer/tests/baseline/reports/，E2E 报告与截图在developer/tests/e2e/reports/，综合摘要在developer/tests/reports/。

总结：IELTS-practice 证明了纯前端项目完全不需要"自降标准"——静态CI守住结构与数据，Vitest 守住逻辑，E2E 守住体验。三层各司其职、由轻到重，既能在日常开发中秒级反馈，又能在提交前完成一次完整的"真实用户演练"。