test(chapter): [PKG-CHAPTER-HOVER-01] wait for stable fullscreen geometry

2026-10-16 09:36:16 -08:00 · 2026-09-14 18:28:07 +08:00
1 parent 492e58a345
commit d89728c0a6
@@ -0,0 +1,57 @@
+# PKG-CHAPTER-HOVER-01 全屏悬停测试同步
+
+## 问题与边界
+
+CI-BROWSER-01 的已安装四包检查曾实际出现 224 通过、1 失败：Chromium 中
+5.4.0 核心搭配候选 Chapter，原生全屏后的章节标题先通过文本断言，再隐藏，
+opacity 从 0.279 降到 0。原始报告、trace 和截图保留在
+`refactor/.cache/ci-browser-installed-full-report`，不改写为通过。
+
+旧测试在 `art.fullscreen === true` 后立即读取进度条 boundingBox 并移动鼠标。
+核心 bottom.less 的进度条/控件有 transform transition；全屏布尔状态不代表
+几何已稳定。原 trace 的鼠标位置为 (640, 665.9921875)，终态截图的进度条已
+移动。仅靠后来通过不能证明原因，因此另建受控移动实验。
+
+## 实现与责任
+
+- `test/browser/chapter-hover.ts` 统一几何读取：先通过 Playwright locator 的
+  `hover({ trial: true })` actionability/stability 检查，再读取 box 并实际移动鼠标。
+  trial 不发送实际 hover；没有增加固定 sleep、断言超时或 test retries。
+- `chapter-combinations.spec.js` 复用该函数；标题、透明度、缩略图、边界及全屏
+  退出断言保持原样。
+- `chapter-hover.spec.js` 在真实原生全屏中用原生 Web Animation 让进度条移动
+  600ms，结束后通过真实 hit-test 验证指针仍在进度条内，再验证 Middle/opacity。
+  这是故意注入的几何移动，不是宣称产品 transition 实际持续 600ms。
+- `ARTPLAYER_CHAPTER_HOVER_BASELINE=1` 可恢复旧的立即读取路径，保留可重跑的
+  反例。默认必须使用稳定路径；诊断模式的失败不能豁免正式验收。
+- 新 TS helper 纳入严格工具类型检查；安装浏览器范围显式加入该回归文件。
+
+API-08 仅涉及测试如何操作 DOM；生产源码、公开接口/事件/声明/CSS 和安装包
+字节都未修改。包架构文档记录入口和边界。本任务不需要重建生产运行时或引入依赖。
+
+## 证据与限制
+
+完整结果、报告摘要、浏览器版本、实际安装入口及 SHA 见
+[chapter-hover-validation.json](../baselines/chapter-hover-validation.json)。
+先前立即读取路径在受控移动中 4 失败、2 通过；等待稳定后同样 6 项全部通过。
+Chromium/Firefox 的失败是最终指针已离开移动后的进度条。首版 WebKit 旧路径
+通过，但审查附件发现其 hit-test 与最终矩形不一致。因此补上最终 x/y 矩形范围
+断言：最终 baseline 三引擎 6 项全部失败；默认稳定路径在 main/legacy 各 6 项
+通过。首版的 2 项通过仍留档，不能把只依赖 hit-test 的结果当作几何正确。
+原有组合与首版新增移动回归在 main/legacy 各 66 项
+通过，均无重试、跳过或失败。严格 TS、专项 ESLint、根 lint（0 错误/1 个既有
+warning）、4 项 browser runner 测试和固定工具链检查通过。
+
+实验确认旧测试的几何竞态及针对该机制的修正，原失败符合相同症状；不能重新播放
+原 run 的精确调度，也不能据此声称所有全屏生产缺陷已排除。新旧包字节保持一致，
+本次修复归类为测试同步问题。CHAPTER-TIMING-01 的 WebKit restart 观察耗时、
+真机、完整发布/分发验收仍由 Chapter-05/06 负责。
+
+验证使用 Node 24.21.0、Yarn 1.22.22、实际安装产物及桌面三引擎。没有远端 CI、
+真机、全量 source suite 或 npm 发布；不把模拟触摸称为手机证据。
+
+## 回退与接续
+
+诊断时设置 baseline 环境变量并运行 README 所列命令，可比较真实指针与终态
+矩形。交付回退可还原本任务的 helper、回归测试、scope 和文档/状态；不要删除
+历史失败报告或把 opacity 断言放宽。后续 UI/CSS 改动须继续运行这两个浏览器文件。