271 lines
13 KiB
Markdown
271 lines
13 KiB
Markdown
# FMS Vue 前端测试规范（AI 全权测试版）
|
||
|
||
本文档是 fms-vue 前端测试的**唯一权威约定**。测试工作（编写、运行、补覆盖）默认全权交给 AI 执行，本文档保证 AI 在任何时候都能：
|
||
|
||
- 知道**测什么**（每个对象的测试清单）
|
||
- 知道**怎么写**（mock 模板与装配方式）
|
||
- 知道**怎么跑**（按文件/页面/全部/覆盖率）
|
||
- 知道**什么时候算完**（覆盖率门槛与验收标准）
|
||
|
||
## 1. 测试命令速查
|
||
|
||
| 场景 | 命令 |
|
||
| --- | --- |
|
||
| 跑全部测试（CI 风格，一次性） | `pnpm test`（同 `pnpm test:all`） |
|
||
| 只测一个文件 | `pnpm test:file tests/views/login.spec.js` |
|
||
| 只测一个页面/功能对应的测试文件 | `pnpm test:file tests/views/<页面>.spec.js` |
|
||
| 只测一个目录（如全部 store） | `pnpm test:file tests/stores` |
|
||
| 带覆盖率跑（检查缺口） | `pnpm test:coverage` |
|
||
| 监听模式（改代码自动重跑） | `pnpm test:watch` |
|
||
|
||
注意：`pnpm test` 与 `pnpm test:coverage` 的区别——**只有 `test:coverage` 会检查 60% 阈值**。普通 `pnpm test` 只看用例红绿，不看覆盖率。
|
||
|
||
## 2. 目录与命名约定
|
||
|
||
```
|
||
tests/
|
||
setup.js # 全局环境：jsdom polyfill、nprogress mock（已就绪，勿删）
|
||
helpers/
|
||
app.js # 统一装配：createTestPinia / createTestRouter / mountPage（已就绪）
|
||
unit/ # 纯函数/工具测试（无 DOM 或极轻 DOM）
|
||
utils-*.spec.js # 对应 src/utils/*
|
||
theme.spec.js # 对应 src/theme/*
|
||
ui-utils-*.spec.js # 对应 src/components/ui/utils/*
|
||
stores/ # pinia store 测试
|
||
auth.spec.js
|
||
app.spec.js
|
||
preferences.spec.js
|
||
components/ # UI 组件测试（冒烟 + 核心交互）
|
||
input.spec.js
|
||
select.spec.js
|
||
... 每个组件一个文件
|
||
views/ # 页面测试
|
||
login.spec.js # 已存在
|
||
dashboard.spec.js
|
||
...
|
||
services/ # http 拦截器/请求层测试
|
||
http.spec.js
|
||
router-auth.spec.js # 路由守卫集成测试（已存在，留在根目录）
|
||
permissions.spec.js # store 测试（已存在，留在根目录，不强制迁移）
|
||
```
|
||
|
||
规则：
|
||
|
||
- 测试文件一律 `*.spec.js`，与源码文件同名（`login/index.vue` → `tests/views/login.spec.js`）。
|
||
- **每个被测源码文件最多对应一个 spec**，禁止把多个对象的测试堆进一个文件。
|
||
- `describe` 第一层用中文描述被测对象（如 `describe('登录页')`）；用例名用中文描述业务场景。
|
||
- 新测试按上表归类；**已存在的测试文件（permissions.spec.js、router-auth.spec.js、views/login.spec.js）不必迁移**，保持原位即可，新增的按新约定放。
|
||
|
||
## 3. 编写模板
|
||
|
||
### 3.1 页面测试（用 mountPage）
|
||
|
||
所有请求都收敛在 `@/services/api`，页面测试只需 mock 这一个模块：
|
||
|
||
```js
|
||
import { describe, it, expect, beforeEach, vi } from 'vitest'
|
||
import { nextTick } from 'vue'
|
||
import { flushPromises } from '@vue/test-utils'
|
||
import LoginPage from '@/views/login/index.vue'
|
||
import { useAuthStore } from '@/stores/auth'
|
||
import { mountPage } from '../helpers/app.js'
|
||
|
||
// —— 单一接缝：mock 业务 API 层，确定性驱动页面状态 ——
|
||
vi.mock('@/services/api', () => ({
|
||
loginApi: vi.fn(),
|
||
loadDataApi: vi.fn(),
|
||
}))
|
||
|
||
// 命令式组件（Message 等）需要 mock，避免 jsdom 下创建 DOM 容器
|
||
vi.mock('@/components/ui/message/message-manager.js', () => {
|
||
const m = { success: vi.fn(), error: vi.fn(), warning: vi.fn(), info: vi.fn() }
|
||
return { Message: m, default: m }
|
||
})
|
||
|
||
import { loginApi } from '@/services/api'
|
||
|
||
// 子组件用 shallowMount 自动打桩；需要触发子组件事件时给一个稳定 name
|
||
const formStub = { name: 'Form', template: '<form class="stub"><slot /></form>' }
|
||
|
||
beforeEach(() => {
|
||
localStorage.clear()
|
||
sessionStorage.clear()
|
||
loginApi.mockReset()
|
||
})
|
||
|
||
describe('登录页', () => {
|
||
it('登录成功：调用 loginApi、写入会话、跳转 redirect', async () => {
|
||
loginApi.mockResolvedValue({
|
||
data: { token: 'TK', user: { id: 1, account: 'admin' }, orgid: 'ORG1' },
|
||
code: 0, success: true,
|
||
})
|
||
const { wrapper, router } = await mountPage(LoginPage, {
|
||
location: '/login?redirect=/dashboard',
|
||
stubs: { Form: formStub },
|
||
})
|
||
await wrapper.findComponent({ name: 'Form' }).vm.$emit('submit', { orgId: 'ORG1', account: 'admin', password: 'secret' })
|
||
await flushPromises()
|
||
await nextTick()
|
||
|
||
expect(loginApi).toHaveBeenCalledWith('ORG1', 'admin', 'secret')
|
||
expect(useAuthStore().isAuthenticated).toBe(true)
|
||
expect(router.currentRoute.value.fullPath).toBe('/dashboard')
|
||
})
|
||
})
|
||
```
|
||
|
||
要点：
|
||
|
||
- `beforeEach` 里必须清理 `localStorage` / `sessionStorage`（persist 插件会写它们，跨用例泄漏）。
|
||
- 用 `flushPromises()` + `nextTick()` 冲刷异步，不要用固定 `setTimeout`。
|
||
- 需要路由参数时用 `mountPage(Comp, { location: '/detail/123' })`。
|
||
|
||
### 3.2 store 测试
|
||
|
||
```js
|
||
import { describe, it, expect, beforeEach, vi } from 'vitest'
|
||
import { useAuthStore } from '@/stores/auth'
|
||
import { createTestPinia } from '../helpers/app.js'
|
||
|
||
vi.mock('@/services/api', () => ({ loadDataApi: vi.fn() }))
|
||
|
||
beforeEach(() => {
|
||
localStorage.clear()
|
||
})
|
||
|
||
describe('auth store', () => {
|
||
it('setSession 写入会话', () => {
|
||
createTestPinia() // 内部已 install，persist 插件真实注册（见 helpers/app.js 注释）
|
||
const auth = useAuthStore()
|
||
auth.setSession({ token: 't', user: { id: 1 } }, 'ORG')
|
||
expect(auth.isAuthenticated).toBe(true)
|
||
})
|
||
})
|
||
```
|
||
|
||
**必须用 `createTestPinia()`，不要手动 `createPinia()`**：
|
||
|
||
- pinia 4 中 `pinia.use()` 在未安装 app 前只把插件放入队列，直接 `setActivePinia(createPinia())` 会让 persist 插件静默失效，store 上缺 `$hydrate`/`$persist`。
|
||
- `createTestPinia()` 内部用假 app 触发 `install()`，行为与页面测试（经 @vue/test-utils 挂载）一致。
|
||
|
||
### 3.3 纯函数测试（unit）
|
||
|
||
```js
|
||
import { describe, it, expect } from 'vitest'
|
||
import { buildTree, sortTree } from '@/utils/tree'
|
||
|
||
describe('utils/tree', () => {
|
||
it('buildTree 按 parentKey 构建树', () => {
|
||
const list = [
|
||
{ b_id: 1, b_parent_id: null },
|
||
{ b_id: 2, b_parent_id: 1 },
|
||
]
|
||
const tree = buildTree(list)
|
||
expect(tree).toHaveLength(1)
|
||
expect(tree[0].children).toHaveLength(1)
|
||
})
|
||
})
|
||
```
|
||
|
||
纯函数测试**不需要** mountPage / pinia / mock，直接 import 断言即可。
|
||
|
||
### 3.4 UI 组件测试（components）
|
||
|
||
```js
|
||
import { describe, it, expect } from 'vitest'
|
||
import { mount } from '@vue/test-utils'
|
||
import Input from '@/components/ui/input/input.vue'
|
||
|
||
describe('Input 组件', () => {
|
||
it('渲染输入框并转发 update:modelValue', async () => {
|
||
const wrapper = mount(Input, { props: { modelValue: '' } })
|
||
const input = wrapper.find('[data-slot="input"]')
|
||
await input.setValue('abc')
|
||
expect(wrapper.emitted('update:modelValue')[0]).toEqual(['abc'])
|
||
})
|
||
})
|
||
```
|
||
|
||
组件测试用 `mount`（组件自身逻辑需要真实渲染）；页面测试用 `shallowMount`（经 mountPage）。定位元素优先用组件已有的 `data-slot`、`aria-label`、`role` 等稳定属性，**不要依赖 CSS class 或文本**。
|
||
|
||
## 4. 每个对象的测试清单（AI 补测试时逐项对照）
|
||
|
||
### 4.1 services（最高优先级，当前 0%）
|
||
|
||
`tests/services/http.spec.js` 必须覆盖：
|
||
|
||
- [ ] 请求拦截器：有 token 时注入 `Authorization: Bearer <token>`；无 token 不注入
|
||
- [ ] 响应拦截器：`code === 0` → success
|
||
- [ ] 响应拦截器：`code === 401` → 清会话 + 跳 `/login?reason=expired`
|
||
- [ ] 响应拦截器：`code === 40101` → 清会话 + 跳 `/login?reason=session-replaced`
|
||
- [ ] 响应拦截器：业务错误码 → 抛 `Error` 且带 `code`/`data`
|
||
- [ ] 响应拦截器：网络异常/超时 → 抛中文错误信息
|
||
- [ ] 已在 `/login` 页时不重复跳转
|
||
|
||
### 4.2 utils（纯函数，零成本高收益）
|
||
|
||
- [ ] `src/utils/tree.js`：`buildTree`（空数组/孤儿子节点/多根/自定义 key 名）、`sortTree`（b_xh 排序/递归子节点/兜底 b_id）
|
||
- [ ] `src/theme/index.js`：`applyPrimaryColor` 写 CSS 变量、`applyDarkMode` 切换 `dark` class
|
||
- [ ] `src/components/ui/utils/*.js`：`focus.js` / `scroll.js` / `drag.js` / `position.js` 按导出函数逐一声明测试
|
||
|
||
### 4.3 stores
|
||
|
||
- [ ] `auth`：setSession 兼容 `token`/`access_token`、`orgid`、`user`/`user_info`；clearSession；sessionStorage 旧会话迁移
|
||
- [ ] `app`：cachedViews 去重；addVisitedTab 去重；removeVisitedTab / closeOthers / closeLeft / closeRight / closeAll 的页签与 routeRefreshKeys 联动；refreshRoute / getRouteRefreshKey
|
||
- [ ] `preferences`：saveLastLogin 写入、持久化 key 为 `fms-preferences`
|
||
- [ ] `permissions`：已有 5 个用例，继续补充 `resolvePageId` / `canPower` 分支
|
||
|
||
### 4.4 UI 组件（冒烟 + 核心交互，20+ 个）
|
||
|
||
每个组件最少 3 个用例：**默认渲染、关键交互、禁用/边界**。按复杂度从低到高：
|
||
|
||
- [ ] 简单组件：`button` / `tag` / `switch` / `radio` / `checkbox` / `spin` / `col` / `row`
|
||
- [ ] 输入类：`input`（default/password/number/textarea 四种模式）、`select`、`date`（date-picker/range-picker/time-select/calendar-panel）
|
||
- [ ] 布局类：`tabs` / `splitter` / `grid` / `tree` / `dropdown` / `menu` / `popover` / `tooltip`
|
||
- [ ] 反馈类：`modal` / `drawer` / `message` / `notification` / `pagination` / `form` / `form-item`
|
||
|
||
### 4.5 页面
|
||
|
||
- [ ] `login`：已有 7 个用例，补充"记住上次登录"回填
|
||
- [ ] `dashboard`：渲染、菜单/权限入口
|
||
- [ ] `detail`：id 渲染、计数交互
|
||
- [ ] `demo`：各组件演示区基本渲染
|
||
|
||
### 4.6 集成
|
||
|
||
- [ ] `router-auth.spec.js`：已有 5 个用例（保持全绿）
|
||
- [ ] 布局：`DefaultLayout` / `AppSidebar` / `AppTopbar` / `AppTabs` / `NavMain` / `NavMenuItem` 菜单渲染与折叠逻辑
|
||
|
||
## 5. 覆盖率策略
|
||
|
||
- 门槛：**lines/functions/branches/statements 均 ≥ 60%**（见 `vitest.config.js`）。
|
||
- `pnpm test:coverage` 输出会列出每个文件的未覆盖行号（`Uncovered Line #s`），这是 AI 补测试的**路线图**：按行号定位，按第 4 节清单补齐。
|
||
- 当前基线约 5%（UI 组件几乎全空），**先做第 4.1–4.3 节（services/utils/stores）**，这些是纯逻辑、无 DOM 依赖、成本最低，可快速把全局覆盖率拉到接近 60%；再做组件冒烟补齐剩余。
|
||
- 阈值检查只在 `--coverage` 时生效，普通 `pnpm test` 不会因覆盖率失败。
|
||
|
||
## 6. 常见坑（写测试前必读）
|
||
|
||
1. **pinia 必须用 `createTestPinia()`**，否则 persist 插件不生效（详见 3.2）。
|
||
2. **persist 的存储格式**：插件 v4 存的是纯 state JSON（`{"token":...}`），**不是** `{state, version}` 旧格式；测试里预置 localStorage 时按 v4 格式写。
|
||
3. **跨用例泄漏**：凡是测试里创建过 store 或挂载过页面，`beforeEach` 必须 `localStorage.clear()` + `sessionStorage.clear()`。
|
||
4. **mock 工厂提升**：`vi.mock` 工厂不能引用外部变量，需要的数据要么内联、要么在 `mockImplementation` 里再取。
|
||
5. **`vi.mock('@/services/api')` 时**要提供被测代码用到的**所有**导出（`loginApi`、`loadDataApi`、`pageDataApi` 等），缺一个就报 undefined。
|
||
6. **异步断言**：`flushPromises()` + `nextTick()`；不要用 `setTimeout` 猜时序。
|
||
7. **不 mock 的东西**：`nprogress` 已在 `tests/setup.js` 全局 mock；`ResizeObserver`/`IntersectionObserver`/`matchMedia`/`scrollTo` 已有 polyfill，组件测试直接可用。
|
||
8. **jsdom 不实现布局**：`offsetHeight`/`getBoundingClientRect` 返回 0，涉及拖拽/滚动/尺寸的断言改为验证状态与事件，不验证像素值。
|
||
|
||
## 7. AI 工作流（每次测试任务的固定步骤）
|
||
|
||
1. **先跑基线**：`pnpm test` —— 确认现有用例全绿再动手。
|
||
2. **定位范围**：根据任务（测一个功能/页面/全部）用第 1 节命令锁定目标测试文件。
|
||
3. **对照清单**：按第 4 节对应对象的清单逐项写用例，不遗漏边界。
|
||
4. **写测试**：遵循第 3 节模板与第 6 节坑位。
|
||
5. **跑目标文件**：`pnpm test:file <目标>`，红了就修，直到绿。
|
||
6. **跑全量 + 覆盖率**：`pnpm test` 全绿、`pnpm test:coverage` 达 60%（或说明缺口与下一步）。
|
||
7. **汇报**：列出新增测试文件、覆盖提升幅度、未达标项与原因。
|
||
|
||
## 8. 与开发规范的关系
|
||
|
||
`../开发规范.md` 第 2 节"不主动执行构建、测试"约束的是**改业务代码时**的默认行为；
|
||
**当任务本身是"测试"时**（如本文档适用的场景），测试命令必须执行，且以本文档第 7 节流程为准。
|