aurora-admin
f1fbfc2ddb
Regression / regression (push) Canceled after 0s
## 品牌标识（本次会话） 起因：品牌此前没有任何图形标识 —— 唯一 favicon 是内联 data-URI 里的字母「A」， 那是 v2.0.0「Aurora Admin → Kole UI」改名漏掉的一处（PC 顶栏也是「A」， 移动端站已是「K」；移动端文档站则完全没有 favicon）。 - 几何：24 网格三个互不接触的笔画（竖 + 两斜），圆头描边； 描边 2.25 → 16px 标签页尺寸下正好 1.5px = 规范原文「描边1.5px」 - 取色分两套（刻意）：favicon 硬编码品牌蓝/白（渲染在浏览器标签栏，不继承 kole-dark）； 顶栏标记走 currentColor（实测暗色下自动转 rgb(20,22,28)） - 新增 theme-color 双条（light #FFFFFF / dark #1C1F26，取 --kole-color-card-bg） - 修 site/app.js hero 标语 KOLE ADMIN → KOLE UI（改名变形残留） - 移动端 7 个模板补 favicon（此前计数 0） 验收：门禁 9 条全 OK（site-routing/site-routes/mobile-docs/mobile-site/isolation/ theme/nav/i18n/icons）；PC 回归 1464/1464 · 移动端 807/807，各连跑 8 次一致； 两端 favicon 405 字节逐字节一致；PC 站控制台错误 1→0。 ## 并行会话成果（本次一并入库） - 图标系统：2576 图标（TDesign/Element Plus，MIT）+ 11 端注入 + 5 个构建门禁工具 + IconPreview 预览页 + ICON-SPEC.md 冻结规格 - 移动端平台：47 组件 × 6 端 + 文档站 53 页 + 隔离门禁 - PC 组件：103 个大后台组件 / 组件11 批次 - uni-app：PC 端试点 + 移动端端实现 + 真实编译验证 ## 工程 - .gitignore 补 .scratch/ 与 .zcode-preexisting-*.txt（会话中间产物，实测 9.1MB，不入库） - CHANGELOG 补品牌标识条目 - ROADMAP 登 S8-P4（品牌标识任务包 + og:image/apple-touch-icon 未做部分）
130 lines
8.5 KiB
Markdown
130 lines
8.5 KiB
Markdown
# 测试说明
|
||
|
||
Kole UI 的测试设计：**零运行时依赖、可视化、可机读**。设计系统包含 **79 个全量组件契约**，每个组件对应 4 个运行端（H5 / React / Vue 2 / Vue 3）以及 CSS 资产；`tests/<slug>.html` 是 H5 回归测试页。
|
||
|
||
## 环境与安装
|
||
|
||
需要 **Node 20+**。`package.json` 的 `dependencies` 必须为空；Playwright 属于 CI/本地验证用 `devDependency`。
|
||
|
||
```bash
|
||
npm ci
|
||
```
|
||
|
||
## Headless 回归
|
||
|
||
```bash
|
||
node site/dev-server.js # 先起站，监听 127.0.0.1:3311
|
||
node tools/verify-dev-server.mjs # 本地服务的畸形请求/穿越防护（含 3 条反例断言）
|
||
node tools/verify-emits-parse.mjs # defineEmits 字面量解析：运行时与构建期双实现等价
|
||
node tools/verify-i18n.mjs
|
||
node tools/verify-site-routing.mjs # 静态：薄壳重定向目标/无 # 残留/SITE_BASE 两处同规则/三处服务器回落
|
||
node tools/verify-site-routes.mjs # 浏览器：深链直开与刷新、前进后退、旧 # 链接改写、file:// 降级（约 10 s）
|
||
node tools/verify-cross-platform.mjs
|
||
node tools/verify-nav-responsive.mjs # 顶栏 ≤1366px 折叠：18 宽度 × 中英双语 + 抽屉交互（约 35 s）
|
||
node tools/run-regression.mjs # 输出 tests/report.json + report-junit.xml
|
||
npm run smoke:site
|
||
```
|
||
|
||
`tools/verify-dev-server.mjs` 会用 `KOLE_PORT`（默认 13311）另起一份服务，因此不会与手工起的 3311 实例抢端口；`tools/run-regression.mjs` 支持 `REG_BASE` 指向别的端口。
|
||
|
||
CI 使用 Node 20、严格 `npm ci` 和 `npx --no-install`，并缓存 Playwright 浏览器。站点服务已启动后，`smoke:site` 会验证文档站语言、路由、详情、目录、主题面板、框架保持和刷新恢复。
|
||
|
||
**部署被测试 gate**：`deploy-pages.yml` 的触发器是 `workflow_run`（等 `Regression` 工作流在 main 上完成）而不是 `push`，作业上另有 `if: conclusion == 'success'` 守卫 —— 测试不通过就不会部署。这样既不重复跑测试，也不需把 Regression 拆成可复用工作流；`workflow_dispatch` 保留为有意的手动逃生口（不受测试门槛限制）。另外部署会通过 `actions/download-artifact` 取**本次 Regression 产出的** `tests/report.json` 放进 Pages 产物（首页通过率卡片的数据源），取不到才回退到提交版并发 `::warning::` —— 避免页面显示「提交里的数字」而不是「刚验过的数字」。
|
||
|
||
无 Playwright 的机器可以打开 `tests/_collect.html`，它把 79 个测试页装入同源 iframe，汇总结果到 `window.__koleCollectResult`；这条浏览器路径适合人工取证，不替代 CI headless 回归。
|
||
|
||
## 当前基线
|
||
|
||
所有数字以当前 `tests/report.json` 为准。当前报告（v2.0.0，2026-09-20 实测）为：79/79 页面通过，**1017 通过、0 失败、34 N/A，共 1051 条断言**；通过率 100%。N/A 不计入通过率分母。
|
||
|
||
> 口径说明：此前记录的 1009 / 35 / 1044 是更早工作树状态下的数字。当前数字来自本仓库工作树连续 10 次回归（9 次连跑 + 1 次独立复跑）的一致结果。
|
||
|
||
`tests/report.json` 是文档站首页测试摘要的数据源。不要手工修改报告数字，必须修复实际问题后重跑生成。
|
||
|
||
## A11y 基线与边界
|
||
|
||
自动化断言将 A11y 作为结构基线，覆盖键盘可达、焦点环、ARIA、文本/图形对比度和 token 使用等规则。通过率不等同于完整 WCAG 2.1 AA 合规声明。以下内容仍需人工或辅助技术实测：
|
||
|
||
- 屏幕阅读器朗读顺序与播报质量（NVDA / VoiceOver）
|
||
- 焦点顺序、焦点陷阱以及弹窗内 Tab 循环
|
||
- 动态内容变更与 `aria-live` 播报时机
|
||
- 表单错误提示和 `aria-describedby` 关联
|
||
- 200% 缩放时的布局可用性
|
||
|
||
## RTL 现状与限制
|
||
|
||
RTL 已纳入样式迁移与验证范围，部分组件使用 CSS 逻辑属性（如 `margin-inline-*`、`padding-inline-*`、`border-inline-*`）。可在宿主页面或场景页设置 `dir="rtl"` 做定向验收。当前仓库没有把 RTL 宣称为 79 个组件全量完成的视觉验收；图标方向、复杂组合布局、溢出和交互顺序仍需逐组件人工复核。
|
||
|
||
## 跨端结构验证
|
||
|
||
```bash
|
||
node tools/verify-cross-platform.mjs
|
||
```
|
||
|
||
脚本从 `site/data.json.meta.version` 记录版本，检查 79 个组件的 H5 / React / Vue 2 / Vue 3 结构和 class 集合，并输出 `tests/cross-platform-report.json`。当前报告有 77 个历史差异；差异本身是信息项，不会导致命令失败。总数不是 79 或读取文件失败会阻断命令。
|
||
|
||
## 断言为什么跑在 iframe 里
|
||
|
||
79 个 H5 演示页的 DOM 由内联脚本渲染，测试页通过 iframe 直载真实演示页，CSS 与脚本真实执行，`_runtime.js` 跨帧读取 `contentDocument` 执行断言。用例节点在帧内自动标注 `data-assert` 和 `data-status`，结果通过 `postMessage` 汇总。
|
||
|
||
## 断言协议与矩阵
|
||
|
||
```html
|
||
<button class="btn btn-primary" data-assert="variant-1" data-status="pass">主按钮</button>
|
||
<button class="btn btn-primary" data-assert="variant-2" data-status="skip" disabled>禁用态</button>
|
||
```
|
||
|
||
每个测试页覆盖以下结构规则：
|
||
|
||
| # | 维度 | 说明 |
|
||
|---|---|---|
|
||
| 1 | 默认态渲染 | 核心节点齐全 |
|
||
| 2 | 尺寸/类型变体 | 代表性尺寸、类型和状态 |
|
||
| 3 | 状态覆盖 | 状态类或状态选择器存在 |
|
||
| 4 | 可见用例 | 至少一个默认态可见用例 |
|
||
| 5 | 键盘可达 | 原生可聚焦元素或 tabindex |
|
||
| 6 | 焦点环可视 | 存在 `:focus-visible` 描边规则 |
|
||
| 7 | ARIA 属性 | 交互节点具备 role / aria-* |
|
||
| 8 | 对比度 | 文本及图形对比度基线 |
|
||
| 9 | token 一致性 | 用例区不硬编码颜色 |
|
||
|
||
## 重新生成测试目录
|
||
|
||
```powershell
|
||
powershell -File run-tests.ps1
|
||
```
|
||
|
||
按 `.design_library/kole-ui/components/index.json` 的 79 项生成测试页。修改测试结构时改 `tests/_template.html` 或 `tests/_index_template.html` 后重跑，不要手改生成的组件页。
|
||
|
||
## 文档站冒烟
|
||
|
||
```bash
|
||
node site/dev-server.js
|
||
npm run verify:i18n
|
||
npm run smoke:site
|
||
```
|
||
|
||
冒烟覆盖默认中文、英语切换、`html[lang]`、`document.title`、导航/详情页/目录、主题面板、`kole-lang` 持久化、框架保持、路由切换、刷新恢复和切回中文。
|
||
|
||
## 顶栏响应式（窄屏折叠）
|
||
|
||
```bash
|
||
node site/dev-server.js
|
||
npm run verify:nav
|
||
```
|
||
|
||
覆盖 18 个宽度（320 → 1600）× 中英双语，共 346 条断言，约 35 秒：
|
||
|
||
- **宽屏（> 1366px）**：顶栏无横向溢出、无链接文字顶出 60px 顶栏、7 条链接单行且全部落在视口内、不显示汉堡。
|
||
- **窄屏（≤ 1366px）**：汉堡出现；点开后 7 条链接全部可达、遮罩出现、页面滚动被锁、`aria-expanded` 同步；Esc 可关闭。
|
||
- **交互序列**：打开时焦点进入抽屉首链接、关闭后焦点还给汉堡；Esc / 点遮罩 / 点链接三种关闭路径；开抽屉会收起语言菜单（避免叠层）；放大回宽屏自动复位（不留滚动锁）。
|
||
|
||
**为什么必须在浏览器里跑**：元素「可见」不等于「点得到」。遮罩层叠（`.topbar` 的 `z-index:100` 形成层叠上下文，抽屉的 `120` 只在顶栏内部生效）与 `visibility` 参与过渡导致的 `focus()` 静默失败，这两类缺陷在矩形与可见性断言下**全部通过**，只有真实点击与焦点检查能抓到 —— 首次接入时即由本脚本发现并修掉。
|
||
|
||
**字体依赖（已实测量化，非不确定项）**：宽度断言依赖字体度量（7 条链接的文字宽度决定顶栏装不装得下）。缺 CJK 字体时中文会退化成豆腐块或拉丁回退，宽度随之改变导致假失败，故 `regression.yml` 装有 `fonts-noto-cjk`。脚本每次运行打印两类基准：
|
||
|
||
- **字体度量基准**（14px 下中文单字 / 4 字标签 / 英文最长标签）——便于把失败快速定位到「字体变了」而不是「布局坏了」。
|
||
- **字体容忍度**：在最窄内联宽度（1367px · 英文）二分测出文字宽度还能再增多少仍不折行、不溢出。**当前实测 17.5%**（该宽度余量 94px）。同一次实测里现实字体的宽度跨度是：Arial / Segoe UI `0.918×`、DejaVu Sans / Liberation Sans `1.000×`、Verdana `1.058×` —— 即最宽的常见字体也远在容忍度内，所以 CI（ubuntu）与开发机（Windows）的字体差异**不会**让这些断言假失败。容忍度低于 5% 时脚本会额外打印告警（余量被吃掉，需要收紧顶栏或提高折叠阈值）。
|
||
|
||
服务未起或页面结构缺失时报 **exit 2**（同 `run-regression.mjs` 的口径），不退化成一串断言失败。
|