# 测试与自证

## 测试放在哪

```text
src/test/
├── setup.ts        # jsdom + jest-dom 注册
├── unit/           # 纯逻辑：lib/ 下的函数
├── components/     # 组件：Testing Library 渲染 + 交互
└── e2e/            # Playwright：真实浏览器里的整体行为
```

业务目录不并排放测试，`src/tsconfig` 也把测试排除在应用构建之外。

## 三个层次各测什么

| 层次   | 工具                             | 适合                                                            |
| ------ | -------------------------------- | --------------------------------------------------------------- |
| 单元   | Vitest                           | 纯函数：树扁平化、分页、密码强度、日期区间、指标、i18n key 扫描 |
| 组件   | Vitest + Testing Library + jsdom | 组件的渲染与交互逻辑，例如表格排序、状态徽标语义色              |
| 端到端 | Playwright（真实 Chromium）      | 整站行为：布局模式、命令面板、拖动、持久化、对比度              |

```bash
pnpm test          # 单元 + 组件（--maxWorkers=2）
pnpm test:e2e      # 端到端；会自动起 pnpm dev（已在跑则复用）
pnpm test -- tree  # 只跑名字匹配的用例
```

## 端到端覆盖了什么

| 文件                    | 覆盖                                                                                                                                                                                                                                                                          |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `console.spec.ts`       | 外壳导航、深色模式写入根元素、列表分页与详情跳转                                                                                                                                                                                                                              |
| `design-system.spec.ts` | 分类页可打开且无未翻译 key、排序 / 列管理 / 密度、列顺序拖拽与持久化、行内展开与列宽持久化、虚拟滚动只渲染可视窗口、树搜索与表格树、验证码与密码强度、弹窗拖动、多选与日期区间、上传校验与图片预览、图标搜索复制、固定列、⌘K 命令面板（⌘⇧S 兼容）、无障碍跳转、灰色与色弱模式 |
| `notifications.spec.ts` | 通知角标与已读同步、筛选、搜索区展开收起、通知设置保存、**顶栏通知默认排第二**、刷新不播进入动画、筛选预设、储物箱增删改、侧栏宽度 / 圆角 / 过渡、布局模式、日期视图切换                                                                                                      |
| `auth.spec.ts`          | 登录校验与进入控制台、两处退出入口、注册的手机 / 邮箱验证、找回密码提交态                                                                                                                                                                                                     |

跑一个文件：

```bash
pnpm test:e2e src/test/e2e/design-system.spec.ts
```

## 并行与产物目录

Playwright 的 `outputDir` 默认是 `test-results/`。多个进程同时跑会互相覆盖，出现"本地假失败"：

```bash
pnpm test:e2e -- --output=/tmp/pw-admin-out
```

CI 与本地钩子都用默认目录，人工并行验证时记得加参数。

## 截图评审

`src/test/e2e/_screenshots.spec.ts` 不是回归用例，默认跳过，需要显式开启：

```bash
pnpm screenshots        # SCREENSHOTS=1，截图写入 /tmp/admin-design-shots
```

改动布局或视觉后，先看截图再提交，比逐页点开快得多。

## 三件套

新增或修改公共组件时，**三件套缺一不可**：

1. 组件总览里加可交互示例（`src/pages/design-system/` 对应分类页）；
2. 至少一处真实落点（标准页型里真的用上）；
3. 单元 / 组件 / 端到端测试至少覆盖一条关键路径。

## 提交前清单

- [ ] `pnpm check` 全绿（格式、类型、lint、单测、构建）
- [ ] 有交互或视觉改动时 `pnpm verify` 全绿
- [ ] 新增能力有总览示例与测试
- [ ] 中英文案同步，没有未登记的 key
- [ ] 没有引入新的运行时依赖（图表、动效、图标库）
- [ ] 示例数据没有写进 `lib/` 或组件默认值