113 lines
4.3 KiB
Markdown
113 lines
4.3 KiB
Markdown
# 测试说明
|
||
|
||
Aurora Admin 组件库的测试设计：**零依赖、可视化、可机读**。每个组件都有一份独立的测试页 `tests/<slug>.html`，加上 `tests/index.html` 总览入口。
|
||
|
||
## headless 回归（v1.2.0 起）
|
||
|
||
```bash
|
||
node site/dev-server.js # 先起站
|
||
node tools/run-regression.mjs # 需 npm i playwright；输出 tests/report.json + report-junit.xml
|
||
```
|
||
|
||
- `tests/report.json` 是首页「测试通过率」的数据源；无报告时首页静默隐藏该数字。
|
||
- 当前基线：812 条断言，通过率 **75.1%**。失败项集中在演示页真实缺口：状态变体（states）52、ARIA 51、键盘可达 35——这是演示页的改进 backlog，不是 runner 的误报。
|
||
- 注意：测试页断言节点由 `_runtime.js` 运行期自动标注（`.row → .demo → .demo-block → 首层` 启发式）；重建测试页后无需额外处理。
|
||
- 本地快速复跑（不装 playwright）：起站后用浏览器控制台跑一遍 79 页即可（见 git 历史中的收集脚本）；重建 data.js 后浏览器需 Ctrl+F5。
|
||
|
||
## 测试矩阵（每个组件都跑这 8 项）
|
||
|
||
| # | 维度 | 说明 |
|
||
|---|---|---|
|
||
| 1 | 默认态渲染 | 核心节点齐全（容器 + 标签 + 图标位等） |
|
||
| 2 | 尺寸/类型变体 | 大/中/小；主/次/文字/链接/危险等 |
|
||
| 3 | 状态覆盖 | default / hover / active / focus / disabled / loading |
|
||
| 4 | 键盘可达 | Tab 进入、Space/Enter 触发、Esc 关闭 |
|
||
| 5 | 焦点环可视 | `:focus-visible` 描边不被覆盖 |
|
||
| 6 | ARIA 属性 | role / aria-disabled / aria-expanded / aria-controls |
|
||
| 7 | 对比度 | 正文 ≥ 4.5:1；大字号 ≥ 3:1 |
|
||
| 8 | token 一致性 | 所有颜色 / 间距 / 圆角都从 `--au-*` 取，不硬编码 |
|
||
|
||
## 断言协议
|
||
|
||
每个测试用例在 DOM 上加两个属性：
|
||
|
||
```html
|
||
<button class="btn btn-primary" data-assert="btn-primary-default" data-status="pass">主按钮</button>
|
||
<button class="btn btn-primary" data-assert="btn-disabled" data-status="pass" disabled>禁用态</button>
|
||
```
|
||
|
||
- `data-assert`：唯一断言 ID（slug + 用例名）
|
||
- `data-status`：当前结果（`pass` / `fail` / `skip`）
|
||
|
||
测试页右下角浮动按钮「运行断言」会逐个执行 JS 断言（DOM 属性、计算样式、键盘事件），并把 `data-status` 写回。失败项自动写 `localStorage[aa-test-log]`，方便后续导出。
|
||
|
||
## 如何跑测试
|
||
|
||
### 方式一：浏览器手动
|
||
|
||
1. 打开 `tests/index.html`
|
||
2. 点击任一组件 → 进入该组件的测试页
|
||
3. 观察渲染快照与断言列表
|
||
4. 点击「运行断言」得到 PASS/FAIL
|
||
5. 顶部「导出日志」按钮下载 JSON
|
||
|
||
### 方式二：自动化（Playwright）
|
||
|
||
```javascript
|
||
const { chromium } = require('playwright');
|
||
const browser = await chromium.launch();
|
||
const ctx = await browser.newContext();
|
||
const page = await ctx.newPage();
|
||
await page.goto('http://127.0.0.1:3311/tests/index.html');
|
||
const slugs = await page.$$eval('.t-card', els => els.map(e => e.dataset.slug));
|
||
for (const slug of slugs) {
|
||
await page.goto('http://127.0.0.1:3311/tests/' + slug + '.html');
|
||
await page.click('#run-asserts');
|
||
const fails = await page.$$eval('[data-status="fail"]', els => els.map(e => e.dataset.assert));
|
||
if (fails.length) console.log(`FAIL ${slug}:`, fails);
|
||
}
|
||
```
|
||
|
||
未来 v1.2 计划：直接输出 JUnit XML，集成 CI。
|
||
|
||
## 重新生成测试目录
|
||
|
||
```powershell
|
||
powershell -File run-tests.ps1
|
||
```
|
||
|
||
会按 `components/index.json` 的全量 79 项生成 `tests/<slug>.html`，并刷新 `tests/index.html` 总览。
|
||
|
||
## 日志格式
|
||
|
||
`localStorage[aa-test-log]` JSON 结构：
|
||
|
||
```json
|
||
{
|
||
"ts": 1757232000000,
|
||
"slug": "button",
|
||
"page": "tests/button.html",
|
||
"assertions": [
|
||
{ "id": "btn-primary-default", "status": "pass", "durationMs": 12 },
|
||
{ "id": "btn-disabled", "status": "pass", "durationMs": 8 }
|
||
],
|
||
"errors": []
|
||
}
|
||
```
|
||
|
||
控制台输入 `aaLogger.export('test')` 导出当前所有日志。
|
||
|
||
## 与文档站的关系
|
||
|
||
- 文档站 `site/app.js` 详情页有「测试页」按钮直达 `tests/<slug>.html`
|
||
- 测试页头部有「← 返回文档站」按钮回 `site/index.html`
|
||
- 两者共用 `colors_and_type.css`，主题色随主题切换实时同步
|
||
|
||
## 不在本轮范围
|
||
|
||
- React 单元测试（Jest / Vitest）
|
||
- 视觉回归（像素对比）
|
||
- E2E 流程测试（点击 → 跳转）
|
||
|
||
这些会在 v1.2.0 之后考虑。
|