mirror of
https://github.com/jxxghp/MoviePilot-Frontend.git
synced 2026-08-11 00:23:37 +08:00
96 lines
5.2 KiB
Markdown
96 lines
5.2 KiB
Markdown
# 单元测试架构
|
||
|
||
MoviePilot-Frontend 使用 Vitest 运行单元测试和组件测试，使用 jsdom 提供 DOM 环境。测试代码参与 TypeScript 类型检查，但不作为生产构建入口。
|
||
|
||
## 测试类型
|
||
|
||
- 单元测试覆盖纯函数、store、composable、路由规则和独立模块的输入、输出及副作用。
|
||
- 组件测试挂载 Vue 组件或页面，覆盖 props、emits、用户交互、可见 DOM、Router、Pinia、HTTP 请求和生命周期清理。
|
||
- PWA、Service Worker、模块联邦远程入口、真实布局、拖拽和浏览器原生能力由真实浏览器验证，不由 jsdom 测试单独证明。
|
||
|
||
## 目录结构
|
||
|
||
业务 spec 与源码共置在对应责任域的 `__tests__/` 目录中，文件名与被测源码保持一致并使用 `*.spec.ts`：
|
||
|
||
```text
|
||
src/
|
||
├── pages/
|
||
│ ├── recommend.vue
|
||
│ └── __tests__/recommend.spec.ts
|
||
├── stores/
|
||
│ ├── auth.ts
|
||
│ └── __tests__/auth.spec.ts
|
||
├── utils/
|
||
│ ├── permission.ts
|
||
│ └── __tests__/permission.spec.ts
|
||
└── views/dashboard/
|
||
├── MediaRecommend.vue
|
||
└── __tests__/MediaRecommend.spec.ts
|
||
```
|
||
|
||
跨业务 spec 复用的测试设施位于 `tests/`：
|
||
|
||
```text
|
||
tests/
|
||
├── setup.ts
|
||
└── support/
|
||
├── render.ts
|
||
├── factories/
|
||
└── msw/
|
||
├── server.ts
|
||
└── handlers/
|
||
```
|
||
|
||
- `tests/setup.ts` 注册 DOM matcher、MSW 生命周期、浏览器 API stub 和每例清理逻辑。
|
||
- `tests/support/render.ts` 提供带 Vuetify、i18n、Router 和 Pinia 的标准渲染入口。
|
||
- `tests/support/factories/` 按业务对象提供最小有效测试数据工厂。
|
||
- `tests/support/msw/handlers/` 按业务域定义 HTTP handler；`server.ts` 只负责 MSW server 实例。
|
||
- spec 通过 `@tests/*` 访问共享测试设施，通过 `@/*` 访问生产源码。
|
||
|
||
## 工具职责
|
||
|
||
- Vitest 提供 runner、断言、mock、fake timers 和覆盖率执行入口。
|
||
- Vue Test Utils 用于 Vue 特有的 props、emits、slots 和局部组件控制。
|
||
- Testing Library、jest-dom 和 user-event 用于按角色、可访问名称和用户操作验证可见行为。
|
||
- MSW 在 HTTP 边界拦截真实 API 客户端请求。未声明请求会使测试失败，测试不得访问真实后端或外网。
|
||
- `@pinia/testing` 用于依赖 store 的组件测试；store 自身使用真实 `createPinia()` 测试。
|
||
|
||
## 编写规范
|
||
|
||
- 一个 spec 对应一个主要源码文件；测试名称描述可观察行为或业务规则。
|
||
- 组件测试断言可见 DOM、emits、路由、请求和持久化结果，不读取组件私有状态或私有方法。
|
||
- 纯逻辑优先直接调用；依赖生命周期、provide 或 inject 的 composable 通过宿主组件挂载。
|
||
- HTTP handler 和 factory 按业务域拆分，不建立包含所有接口或所有数据字段的全局万能 mock。
|
||
- 只在与当前断言无关或无法由 jsdom 正确执行时 stub 子组件、浏览器能力或第三方重型组件。
|
||
- 每个用例保持独立，不依赖文件执行顺序；timer、mock、storage、DOM 和未完成请求由全局 setup 恢复。
|
||
- 不使用大面积快照或覆盖率占位用例。
|
||
|
||
## 新增测试
|
||
|
||
1. 业务测试在被测源码所在目录的 `__tests__/` 中创建同名 `*.spec.ts`；工具链配置契约测试放在 `tests/config/`。
|
||
2. 纯函数、store 和无渲染模块直接使用 Vitest；Vue 组件使用标准渲染入口。
|
||
3. 需要 HTTP 请求时，在 `tests/support/msw/handlers/<domain>.ts` 增加对应 handler。
|
||
4. 需要结构化业务数据时，在 `tests/support/factories/` 增加最小工厂。
|
||
5. 核心覆盖范围发生变化时，同步更新 `vite.config.ts` 的 `coverage.include`。
|
||
6. 提交前运行测试、覆盖率、类型检查、lint 和生产构建。
|
||
|
||
## 配置边界
|
||
|
||
Vitest 收集 `src/**/__tests__/**/*.spec.ts` 和 `tests/config/**/*.spec.ts`。测试模式保留 Vue、Vue JSX、Vuetify、自动导入、自动组件和 i18n 插件，并禁用 PWA、模块联邦和 top-level-await 构建插件。配置契约测试随全量测试执行，但不加入业务源码覆盖率统计范围。
|
||
|
||
当前核心覆盖范围在 `vite.config.ts` 的 `coverage.include` 中显式维护。聚合门槛为 Lines、Statements、Functions 不低于 85%，Branches 不低于 80%；每个显式核心文件的 Lines、Statements、Functions 不低于 80%，Branches 不低于 75%。覆盖率报告写入 `coverage/`。
|
||
|
||
## 命令与 CI
|
||
|
||
```sh
|
||
yarn test # watch 模式
|
||
yarn test:run # 单次运行
|
||
yarn test:coverage # 单次运行并检查覆盖率
|
||
yarn test:lint-config # 聚焦执行 ESLint 配置契约测试
|
||
yarn typecheck
|
||
yarn lint
|
||
yarn build
|
||
```
|
||
|
||
`Frontend Tests` 工作流使用 Node 24 LTS 和 frozen lockfile，在面向 `v2` 的 Pull Request 和推送到 `v2` 时运行。`typecheck-and-coverage` job 依次执行类型检查和覆盖率门禁；独立的 `lint` job 执行全仓只读 ESLint 检查。变更文件格式检查依赖 Pull Request 的 base/head SHA，因此只在 Pull Request 事件运行。Prettier 和 Node 兼容范围按[前端代码质量工具链演进](code-quality.md)继续渐进接入，新增测试代码不得引入新的 lint 或格式问题。
|