ArtPlayer/refactor/changes/2026-09-12-PKG-ADS-02-tests.md

# PKG-ADS-02：Ads 行为、错误和真实媒体基线

起点 c6b82c33；本步建立测试基线，不修改 Ads 生产源码、公开声明、样式或产物。
使用实际 npm 1.0.6、Git 冻结的未发布工作区 2.1.0，以及当前源码构建；不使用虚构的
npm 2.1.0。完整来源见 [01 契约](../baselines/ads-contract.md)。

## 交付与验收

新增窄范围时钟/宿主 helper 与 58 项 Node 测试：14 项共享行为在三实现运行，8 类
历史缺陷仅在两个冻结实现运行。实际 option-validator 校验配置，包含浅 i18n、参数
身份、互不干扰的实例、首次播放、倒计时暂停、跳过、restart、媒体错误与 destroy。
默认 test:unit 接入，并提供 yarn test:ads；没有新依赖或 lockfile 变动。

新增 66 项三引擎浏览器测试，全部通过、无重试/跳过。每个引擎 16 项为核心
5.4.1/候选 × Ads 1.0.6/候选的四种正常行为组合，另 6 项为两个核心上的三种历史
问题观察。正常组合包含 HTML 图片实际加载、视频解码颜色/时间、静音点击、跳过阈值、
自动完成、实际 404 恢复、计时暂停和切换主视频。截图中广告画面、倒计时与静音/全屏
控件可见；已查看候选核心/候选 Ads 的实际视频截图。

播放拒绝通过精确的媒体 play 注入复现：广告启动拒绝后计时继续；主片恢复拒绝后广告
隐藏并 emit skip，两者均产生未处理拒绝。仅捕获指定错误，其他未处理错误仍导致失败。
这不是设备自动播放认证。零阈值用例暂停倒计时观察真实按钮首 tick 前状态。

完整本地 CI 806 项通过（747 单元、14 工程、45 基线），262 个生产 TS 文件严格检查，
核心 37 份声明无漂移。保留一条既有生成编辑器声明的 unused eslint-disable warning，
没有新增 lint 错误。执行日志与最终结论记录在 [执行证据](../baselines/ads-validation.json)。
生产源码和类型未改，严格检查复用现有项目；完整包分发和原生设备验收仍由后续任务负责。

## 原始失败与修正

- 首轮 Chromium 2 通过、16 失败：给浏览器全局加 window 时误改了事件名字符串，
  监听到错误的名字，修复夹具字符串。原始 trace/报告完整保留。
- 第二轮三引擎 45 通过、9 失败：5 个暂停测试在广告初始化前调用方法；补真实 DOM
  出现条件。4 个 WebKit 视频测试错误要求 videoWidth=320，而 Windows WebKit 报
  布局宽度 640；改为读取实际解码帧的黄/蓝/青色像素，所有引擎使用相同断言。
- 第三轮新增主片拒绝/零阈值观察后 66 项全部通过。没有增加超时、重试或跳过。
- 初始 Node 文件的 lint 换行、多语句和正则规范问题已按仓库规则修正。

## 兼容边界和后续

API-01/04/05/06/08 的可控行为与真实页面用例已经固定。这里没有改变用户调用、
事件顺序、DOM/CSS 或时长规则，也没有把历史缺陷定义为新实现必须保留的行为。
ADS-LIFE-01、ADS-MEDIA-01、ADS-UI-01 从源码观察提升到复现，保持 open；其中
metadata 竞态、真实隐藏页行为和全屏状态仍待验证，不能因部分复现视为整个风险已解决。

03 按配置、计时状态、视图、媒体和生命周期所有权拆分，并为历史缺陷增加候选修复断言；
04 严格 TS/准确声明/旧类型入口；05 保留旧核心 4.5.5 和实际设备、销毁媒体资源等验证；
06 完整产物消费和 demo。正常 play/pause 只管理倒计时的已有语义要保留。
测试文件地图、命令与限制见 [Ads 验证说明](../ads-validation.md)，包内架构说明随 03
实际拆分交付，避免提前记录尚不存在的模块。

## 提交与回退

独立本地提交主题：test(ads): [PKG-ADS-02] cover legacy timing and real media contracts。
回退该提交移除本步测试、脚本接入、文档和状态变化，生产行为不受影响。
没有 push、tag、publish 或 merge；全项目重构和发布复盘目标继续。