# 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`：各组件演示区基本渲染
- [ ] `test/TestPage`：基本渲染

### 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 节流程为准。