本提交含两条并行工作线,因互相咬合(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 断言其互斥),未删。
This commit is contained in:
+8
-8
@@ -1,6 +1,6 @@
|
||||
# 测试说明
|
||||
|
||||
Kole UI 的测试设计:**零运行时依赖、可视化、可机读**。设计系统包含 **79 个全量组件契约**,每个组件对应 4 个运行端(H5 / React / Vue 2 / Vue 3)以及 CSS 资产;`tests/<slug>.html` 是 H5 回归测试页。
|
||||
Kole UI 的测试设计:**零运行时依赖、可视化、可机读**。设计系统包含 **103 个全量组件契约**,每个组件对应 4 个运行端(H5 / React / Vue 2 / Vue 3)以及 CSS 资产;`tests/<slug>.html` 是 H5 回归测试页。移动端另有 47 个组件、`tests/mobile/` 测试页与 `tests/mobile-report.json`(两平台物理隔离,见 PLATFORMS.md)。
|
||||
|
||||
## 环境与安装
|
||||
|
||||
@@ -31,13 +31,13 @@ CI 使用 Node 20、严格 `npm ci` 和 `npx --no-install`,并缓存 Playwrigh
|
||||
|
||||
**部署被测试 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 回归。
|
||||
无 Playwright 的机器可以打开 `tests/_collect.html`,它把 103 个测试页装入同源 iframe,汇总结果到 `window.__koleCollectResult`;这条浏览器路径适合人工取证,不替代 CI headless 回归。移动端对应 `tests/mobile/_collect.html`。
|
||||
|
||||
## 当前基线
|
||||
|
||||
所有数字以当前 `tests/report.json` 为准。当前报告(v2.0.0,2026-09-20 实测)为:79/79 页面通过,**1017 通过、0 失败、34 N/A,共 1051 条断言**;通过率 100%。N/A 不计入通过率分母。
|
||||
所有数字以 `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 条**。
|
||||
|
||||
> 口径说明:此前记录的 1009 / 35 / 1044 是更早工作树状态下的数字。当前数字来自本仓库工作树连续 10 次回归(9 次连跑 + 1 次独立复跑)的一致结果。
|
||||
> 历史数字(79 页 / 1017 条 / 34 N/A 等)对应 103 组件扩展之前的组件集,已不代表当前工作树。
|
||||
|
||||
`tests/report.json` 是文档站首页测试摘要的数据源。不要手工修改报告数字,必须修复实际问题后重跑生成。
|
||||
|
||||
@@ -53,7 +53,7 @@ CI 使用 Node 20、严格 `npm ci` 和 `npx --no-install`,并缓存 Playwrigh
|
||||
|
||||
## RTL 现状与限制
|
||||
|
||||
RTL 已纳入样式迁移与验证范围,部分组件使用 CSS 逻辑属性(如 `margin-inline-*`、`padding-inline-*`、`border-inline-*`)。可在宿主页面或场景页设置 `dir="rtl"` 做定向验收。当前仓库没有把 RTL 宣称为 79 个组件全量完成的视觉验收;图标方向、复杂组合布局、溢出和交互顺序仍需逐组件人工复核。
|
||||
RTL 已纳入样式迁移与验证范围,部分组件使用 CSS 逻辑属性(如 `margin-inline-*`、`padding-inline-*`、`border-inline-*`)。可在宿主页面或场景页设置 `dir="rtl"` 做定向验收。当前仓库没有把 RTL 宣称为 103 个组件全量完成的视觉验收;图标方向、复杂组合布局、溢出和交互顺序仍需逐组件人工复核。
|
||||
|
||||
## 跨端结构验证
|
||||
|
||||
@@ -61,11 +61,11 @@ RTL 已纳入样式迁移与验证范围,部分组件使用 CSS 逻辑属性
|
||||
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 或读取文件失败会阻断命令。
|
||||
脚本从 `site/data.json.meta.version` 记录版本,检查 103 个组件的 H5 / React / Vue 2 / Vue 3 结构和 class 集合,并输出 `tests/cross-platform-report.json`。当前报告有 77 个历史差异;差异本身是信息项,不会导致命令失败。总数不是 103 或读取文件失败会阻断命令。
|
||||
|
||||
## 断言为什么跑在 iframe 里
|
||||
|
||||
79 个 H5 演示页的 DOM 由内联脚本渲染,测试页通过 iframe 直载真实演示页,CSS 与脚本真实执行,`_runtime.js` 跨帧读取 `contentDocument` 执行断言。用例节点在帧内自动标注 `data-assert` 和 `data-status`,结果通过 `postMessage` 汇总。
|
||||
103 个 H5 演示页的 DOM 由内联脚本渲染,测试页通过 iframe 直载真实演示页,CSS 与脚本真实执行,`_runtime.js` 跨帧读取 `contentDocument` 执行断言。用例节点在帧内自动标注 `data-assert` 和 `data-status`,结果通过 `postMessage` 汇总。
|
||||
|
||||
## 断言协议与矩阵
|
||||
|
||||
@@ -94,7 +94,7 @@ node tools/verify-cross-platform.mjs
|
||||
powershell -File run-tests.ps1
|
||||
```
|
||||
|
||||
按 `.design_library/kole-ui/components/index.json` 的 79 项生成测试页。修改测试结构时改 `tests/_template.html` 或 `tests/_index_template.html` 后重跑,不要手改生成的组件页。
|
||||
按 `.design_library/kole-ui/components/index.json` 的 103 项生成测试页。修改测试结构时改 `tests/_template.html` 或 `tests/_index_template.html` 后重跑,不要手改生成的组件页。
|
||||
|
||||
## 文档站冒烟
|
||||
|
||||
|
||||
Reference in New Issue
Block a user