# 测试与验收

本清单是验收目录，早期未勾选项不代表当前未实施。计划、历史执行与精确候选观察
见tasks/progress及 [契约覆盖索引](contract-coverage.md)，不能以总通过数代替契约验证。

核心/chapter 的 Node TS 覆盖率使用 `yarn test:coverage`。源映射防伪验证、关键生命周期门槛、报告位置及资源/性能实施状态见 [覆盖率与性能维护说明](coverage-performance.md)。

## 测试层次

浏览器验收采用连接的 @Chrome 交互检查与仓库自动回归相结合；具体操作断言、证据范围和真机边界见 [多轮复盘与 npm 准入](release-reviews.md)。浏览器已连接不代表播放器用例已通过。

| 层 | 内容 | 运行位置 |
| --- | --- | --- |
| 单元 | Emitter、配置、转换、索引、排序、选择状态、消息解析、时钟算法 | 保留 node:test；新工具需单独决策 |
| 生命周期 | 初始化失败、重复销毁、切源并发、过期响应、资源清理和 Promise 结算 | 可控时钟/媒体 adapter；关键流程再到真实浏览器 |
| 浏览器集成 | 完整播放器、插件 DOM、真实媒体、seek、字幕、鼠标/键盘/触控 | Playwright Chromium/Firefox/WebKit |
| 产物 | 由正常脚本构建的 tarball，UMD/AMD/global/require/ESM/legacy/i18n | 隔离消费者项目，不能靠 workspace 源码链接通过 |
| 类型 | 正向样例、错误断言、类型推断、插件扩展、JS 用户、声明入口 | 明确版本的 tsc，bundler 和 Node 模块解析分别检查 |
| 设备/供应商 | Safari 真机、PiP、Chromecast、IMA、模型和实际 codec | 有能力的设备/外部环境，记录真实版本和限制 |
| 性能/资源 | 初始化、交互、帧调度、反复装卸、CPU/内存/事件资源 | 固定设备、媒体和测量流程，多次运行 |

## 基线与差分

优先复用仓库现有 HTML 和在线编辑器，入口清单及任务归属见 [docs 页面与编辑器测试](docs-browser-testing.md)。执行前固定 prod 存储状态、实际脚本路径和构建来源；现有文档 smoke 不代替异步媒体断言。

正式浏览器基础设施建成前，BASE 任务以固定旧包、最小可重跑探针和已有页面采集，再由 ENG 接入自动化；具体启动、契约覆盖映射和文档包验收分类见 [执行门槛](execution-gates.md)。

1. 基线产物来自 BASE-01 固定的发布版本，保存 tarball integrity、源码 SHA、工具版本和样本信息。
2. 同一测试对旧产物和候选产物运行，比较公开结果、事件 trace、属性描述符和 DOM 状态。
3. 不使用整个 minified bundle 的文本相等作为 API 兼容证据。
4. 已确认缺陷使用单独用例记录“旧版本复现，候选修复”；差分例外必须有变更记录，不能一键更新全部快照掩盖回归。
5. 接口、类型与行为三项分别验收。只有类型检查通过不能证明运行时正确。
6. 起步先验证核心与试点，各包迁移前补齐自身发布基线。历史失败、候选回归和缺少环境分开，执行 ENG-10 的失败台账及逐模块门槛，不以全仓库初始全绿作为启动条件。

## 核心测试清单

- [ ] 正常初始化、useSSR、配置错误、无容器、重复容器、初始化中途失败。
- [ ] play/pause/toggle、自动播放拒绝、内部播放触发不产生未处理拒绝。
- [ ] currentTime/seek、switchUrl/switchQuality、同 URL、连续切换、切换中销毁、错误重试。
- [ ] ready/restart/destroy 次数和状态，video 原生事件转发参数及顺序。
- [ ] 一个实例销毁两次、多个实例互斥、销毁监听器重入/抛异常、removeHtml=false。
- [ ] 控件/设置 add/update/remove、selector 高亮、重复名称、mounted/beforeUnmount。
- [ ] 字幕载入、失败、切换顺序、cue 数组、偏移、URL 回收。
- [ ] fullscreen/fullscreenWeb/PiP/mini 进入退出和异常，移动端方向、手势和安全区域。
- [ ] 热键、焦点、document 重绑、全局监听器及组件清理。
- [ ] i18n、图标、主题、样式注入及用户 CSS 覆盖。
- [ ] 每个内置插件：autoPlayback、autoOrientation、fastForward、lock、miniProgressBar。
- [ ] 键盘可达性、可访问名称、设置菜单焦点、模式退出后的焦点返回和字幕可用性；保留原快捷键与自定义 DOM/CSS 用法。

此清单是验收目录；具体任务状态仍只记入 tasks.json。

## 媒体样本

优先复用仓库中许可明确的本地 MP4/WebM/VTT/SRT/ASS；补充短 HLS/DASH、音轨/清晰度变化、无音轨、空字幕、损坏内容、慢响应和中断样本。媒体服务支持 Range 与受控错误。不要让公共直播 URL 的可用性决定 PR 是否通过。

浏览器不能解码特定样本时，要区分浏览器/codec 能力和播放器回归。需要实际支持的路径不能静默 skip；可选能力的 skip 必须有原因，设备验收在发布清单中保持待完成。

## CI 分层

用户已明确要求增强 GitHub CI/CD，当前 workflow 问题、目标矩阵、报告和实现任务见 [GitHub CI/CD 规范](github-ci-cd.md)。本地测试通过、workflow 静态检查、真实 Actions 通过分别记录。

| 触发 | 内容 |
| --- | --- |
| 每次 PR | 固定安装、只读 lint、类型、受影响单元/生命周期、核心浏览器 smoke、受影响发布包检查 |
| 核心或共享构建改变 | 全部 22 包构建/类型检查，旧插件对候选核心的回归，扩展浏览器矩阵 |
| 定期或候选发布 | 完整浏览器组合、压力/资源、性能、外部 SDK 与真机清单 |
| 发布前 | 干净环境完整 CI、tarball 消费、新旧组合、文档站、回退演练 |

快速检查必须存在依赖映射；无法确定受影响范围时运行完整核心及生态检查，不仅按文件名选择测试。

ENG-02 先交付仓库内可执行的 CI 配置；GitHub required checks 的实际设置属于外部状态，在发布准入时核实，不能把没有仓库管理权限变成本地测试框架建设的前置阻塞。尚未迁移的包保留历史失败台账，迁移包严格验收，所有受影响公开路径的候选回归仍阻止交付。

不要在媒体测试中靠固定 sleep 等待。优先受控事件/状态条件、固定样本和故障注入；对重试、偶发失败及 trace 有明确记录。真实设备缺失不阻止无关文档/本地候选准备，但始终阻止缺证据的相关能力通过发布验收。

## 证据要求

每次记录命令、HEAD、运行时与浏览器版本、样本、通过/失败/跳过数、报告路径和限制。报告持久化到可追溯的 CI artifact 或仓库中适量文本摘要，不只给开发机器临时路径。不提交大型录像/媒体/trace 到源码仓库。

必要门槛：没有新增未解释的失败，没有已知合法旧调用失效，关键资源在销毁后停止增长，发布路径存在且可加载。覆盖率报告先建立真实基线，再在 ENG 阶段按模块制定分支覆盖门槛；禁止用无意义测试堆数字。

性能门槛在 BASE-06 固定设备和统计方式后登记。若候选包 gzip 大小增长超过基线 5%，或主要测量中位数退化超过 10%，作为初始审查阈值触发调查，不能以一次波动判定回归，也不能以无测量声称优化。

## 本计划不代表已有测试

以上目录源自初始计划，部分命令、测试和矩阵已实施；当前事实及范围见 [progress.md](progress.md)。