root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
aurora-admin/TESTING.md
T
aurora-admin 5ee5d829a4
Regression / regression (push) Canceled after 0s
Details
refactor(详情页+S8): 详情页减重(导航互斥/入口去重/i18n去重) + 品牌标识入库 
本提交含两条并行工作线，因互相咬合（package.json scripts、regression.yml、
npm run build 链）无法按文件干净拆分，故合并为一次自洽提交。

## 详情页减重（本轮主任务：修复「AI 干太重」）

- 导航收敛：宽屏只用右侧目录、≤1200px 只用页内 sticky 导航，纯 CSS 媒体查询
  实现（不引入 JS 宽度监听）。此前两套导航同时可见，active 状态互相打架。
- 入口去重：标题区由「查看示例/在线测试/契约 JSON」三个减为「在线测试」一个；
  契约 JSON 归入实现资源；删除示例底部重复的「在线测试」。
- 示例工具栏：删除与目录锚点重复的示例下拉选择器；「全部展开代码」只在
  示例数 >1 时出现（103 个组件里 49 个仅 1 个示例，此前恒显示）。
- 重复文案：示例区两句同义导语合并为一句。
- 首页 CTA 由 5 个减为 2 个（浏览组件/快速开始），测试总览入口挂到已有的
  通过率统计卡上，不再另占 Hero 按钮。
- 统一详情取数：抽出 fetchDetail/loadDetail 作为 details/*.json 的唯一路径，
  FAQ 不再自行 fetch 一遍，与组件页共用缓存与失败兜底。

## i18n

- 删除 12 组重复键（含整段 FAQ 说明），字典 604 → 585 唯一键。
- 删除本次改动产生的 6 个死键。
- verify-i18n.mjs 新增 `unique dictionary keys` 断言：重复键在对象字面量里
  是静默的后值覆盖，此前无从发现；现由门禁拦住。

## 文档事实修正（实测为准）

- TESTING/CONTRIBUTING：79 → 103 组件；旧断言数改为回指 tests/report.json。
- PLATFORMS：移动端 108 文件/18 端 → 282 文件/47 端；契约 5 → 47；
  令牌 17 → 15；uni-app SFC 21 → 50。
- AGENTS：断言 1405/18 页 → 1464/103 页（PC）、807/47 页（移动端）。
- package.json：YOUR-ACCOUNT 占位 → gitea 实址与 kole-ui.mymoyu.top。

## 品牌标识（并行会话成果，一并入库）

- brand-mark.json 收归真源，build:brand 生成 favicon 与单色 SVG；
  PC 与移动端共用资产，verify:brand 24 条断言。
- regression.yml 增加 verify:brand 步骤。

## 门禁与验收

新增工具：verify-component-page.mjs（86 条真实浏览器断言，随详情页改造同步
更新为「只允许一套导航可见」）、verify-brand-mark.mjs、lib/i18n-dead-keys.mjs
（只读诊断）。

回归：PC 100%（1464/1464，103 页，N/A 50）· 移动端 100%（807/807，47 页）。
门禁：component-page 86 · i18n 17 · brand 24 · routes all · smoke all ·
theme OK · isolation 31 · nav all · examples 9 · api-docs 10 · mobile-docs 12。

已知未做：i18n 另有约 44 条历史死键（非本次产生），已记为 ROADMAP S8-P6；
顶栏与悬浮区的两个主题入口为刻意设计（verify-theme 断言其互斥），未删。
2026-09-22 23:56:05 +08:00

8.7 KiB
Raw Permalink Blame History

测试说明

Kole UI 的测试设计：零运行时依赖、可视化、可机读。设计系统包含 103 个全量组件契约，每个组件对应 4 个运行端（H5 / React / Vue 2 / Vue 3）以及 CSS 资产；tests/<slug>.html 是 H5 回归测试页。移动端另有 47 个组件、tests/mobile/ 测试页与 tests/mobile-report.json（两平台物理隔离，见 PLATFORMS.md）。

环境与安装

需要 Node 20+。package.json 的 dependencies 必须为空；Playwright 属于 CI/本地验证用 devDependency。

npm ci

Headless 回归

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，它把 103 个测试页装入同源 iframe，汇总结果到 window.__koleCollectResult；这条浏览器路径适合人工取证，不替代 CI headless 回归。移动端对应 tests/mobile/_collect.html。

当前基线

所有数字以 tests/report.json 为准（不要手抄进文档）。当前报告为：103/103 页面通过，1464 通过、0 失败、50 N/A，共 1514 条断言；通过率 100%（N/A 不计入分母）。移动端 tests/mobile-report.json：47/47 页面通过，807 通过、0 失败、10 N/A，共 817 条。

历史数字（79 页 / 1017 条 / 34 N/A 等）对应 103 组件扩展之前的组件集，已不代表当前工作树。

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 宣称为 103 个组件全量完成的视觉验收；图标方向、复杂组合布局、溢出和交互顺序仍需逐组件人工复核。

跨端结构验证

node tools/verify-cross-platform.mjs

脚本从 site/data.json.meta.version 记录版本，检查 103 个组件的 H5 / React / Vue 2 / Vue 3 结构和 class 集合，并输出 tests/cross-platform-report.json。当前报告有 77 个历史差异；差异本身是信息项，不会导致命令失败。总数不是 103 或读取文件失败会阻断命令。

断言为什么跑在 iframe 里

103 个 H5 演示页的 DOM 由内联脚本渲染，测试页通过 iframe 直载真实演示页，CSS 与脚本真实执行，_runtime.js 跨帧读取 contentDocument 执行断言。用例节点在帧内自动标注 data-assert 和 data-status，结果通过 postMessage 汇总。

断言协议与矩阵

<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 -File run-tests.ps1

按 .design_library/kole-ui/components/index.json 的 103 项生成测试页。修改测试结构时改 tests/_template.html 或 tests/_index_template.html 后重跑，不要手改生成的组件页。

文档站冒烟

node site/dev-server.js
npm run verify:i18n
npm run smoke:site

冒烟覆盖默认中文、英语切换、html[lang]、document.title、导航/详情页/目录、主题面板、kole-lang 持久化、框架保持、路由切换、刷新恢复和切回中文。

顶栏响应式（窄屏折叠）

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 的口径），不退化成一串断言失败。

Reference in New Issue View Git Blame Copy Permalink