# 前端测试规范 - **功能**:规定前端测试的分层策略、集成测试与逻辑单测写法、覆盖率棘轮和提交前检查,保证测试真实覆盖生产代码。 - **何时用**:新增或修改测试时;补关键用户路径的集成测试时;改覆盖率阈值时;提交前跑检查时。 ## 规则 ### 测试规范(分层策略) 测试按「金字塔」分层组织,新增功能优先补中间层: | 层 | 位置 | 职责 | 风格 | |----|------|------|------| | 逻辑单测 | `src/__tests__/{api,composables,utils,router}/` | 纯函数、composable、request 封装 | 直接调用,快、准 | | **交互式集成测试** | `src/__tests__/integration/` | 页面关键用户路径 | 真实挂载 + 模拟点击 + DOM 断言 | | E2E | `e2e/` | 真实浏览器回归 | Playwright + `page.route` 拦后端 | ### 交互式集成测试要求 - 必须真实挂载组件(不 `shallow`),通过 `trigger('click')`、`setValue()`、`find('…')` 模拟并断言用户可见行为;禁止 `wrapper.vm.xxx()` 直调内部方法作为主要测试手段(历史遗留的 vm 直调在改动到时迁移)。 - 页面关键路径必须有集成测试:登录、学习会话暂停/继续、任务创建/更新、回忆对比等新增关键流程同步补 `integration/*.spec.ts`。 - 只断言应用自身行为(API 调用参数、提示、路由、状态文案),不要重复验证 Element Plus 内部行为;jsdom 下 EP 的 callback 式表单校验不可靠(空表单也可能判有效),「校验拦截」类断言由 e2e 在真实浏览器覆盖。 - 已知兼容问题:`el-tag` 在 jsdom + VTU 全量挂载时 vnode mounted 钩子崩溃(EP 2.8),集成测试统一 `stubs: { ElTag: true }`;依赖 mind-elixir 的 `MindMapViewer` 用可编程 stub(提供 `toOutline`)。 - E2E 定位优先使用角色与可访问名称(`getByRole('button', { name })`、`getByPlaceholder`),仅断言 EP 内部 UI(校验错误、消息弹层)时才用类选择器;改文案不应导致大面积碎测。 ### 逻辑单测要求 - 单元测试必须直接测试真实代码:直接调用 composable、挂载真实组件、使用真实路由;禁止把组件或 composable 的逻辑复制到测试里再自测。 - 测试中可以 mock 外部依赖(API、Element Plus 服务、Audio 等),但被测逻辑本身必须来自生产模块。 - `script setup` 内部状态需要测试访问时,通过 `defineExpose` 暴露,而不是在测试里重写一份相同逻辑。 ### 覆盖率 - `npm run test:coverage` 输出 v8 覆盖率报告(`coverage/`),阈值配置在 `vite.config.ts`,作为棘轮只升不降:任何低于阈值的改动不允许提交。 - 提升覆盖率优先补集成测试与零覆盖模块(当前缺口:Review、ReviewDetail、fetchTitle、markdown 渲染分支),不为凑数写快照式断言。 ### 提交前检查 - 运行 `npm run type-check`、`npm run lint`(0 error 才可提交;`no-explicit-any` 允许存量警告,新代码避免 any)、`npm run test`、`npm run build`。 - **不要用 `npx vue-tsc --noEmit` 作为检查手段**:`tsconfig.json` 是 solution 风格(`files: []` + 仅 `references`),该命令会解析到根配置而检查 0 个源文件,永远假绿。Docker 构建跑的是 `npm run type-check`(`vue-tsc --build --force`,走 project references),只有它才真正校验。 - 提交信息按 Git 提交规范使用中文短句;样式类改动用 `style:`,清理类用 `refactor:` / `chore:`。