# 浏览器录像与报告

[项目首页](../../README.md) · [使用说明](使用说明.md) · [浏览器首次配置](浏览器实时预览一步一步配置.md) · [故障速查](../deployment/常见问题速查与处理.md#f16-录像无法生成或播放)

本文描述 0.12.3 的本机浏览器录像与报告。录像就像给测试网页装一台小摄像机：测试时记录网页的变化，测试结束后在报告中回看。默认关闭，需要你自己打开。

## 1. 先安装能录视频的 Browscreen

在**运行 DSH 的电脑**上打开终端，复制下面整段命令并执行：

```sh
uv tool install --force --python 3.14 'browscreen[video]==0.3.0' \
  -i http://mirrors.aliyun.com/pypi/simple/ \
  --trusted-host mirrors.aliyun.com
browscreen version
```

看到 `browscreen 0.3.0`，说明命令可用。`[video]` 很重要：它会安装录视频需要的 PyAV。只安装 `browscreen==0.3.0` 可以预览，但不保证能录像。插件支持稳定版本 `>=0.3.0,<0.4.0`，不接受旧的 0.2.x。

已经装过旧版本，也执行上面的命令；`--force` 会重新准备独立的工具环境。插件不会替你安装或升级依赖。

终端找不到 `uv` 时，先按 [uv 安装说明](https://docs.astral.sh/uv/getting-started/installation/)安装。Python 不可用时可先执行 `uv python install 3.14`。镜像尚未同步时，从 [PyPI 0.3.0 文件页](https://pypi.org/project/browscreen/0.3.0/#files)下载 wheel，用实际 wheel 路径替换包名并加上 `[video]`，保留镜像参数。例如使用 `'./browscreen-0.3.0-py3-none-any.whl[video]'`。

## 2. 打开录像开关

1. 打开并登录 DSH。
2. 点击左侧底部 **设置**，再点击 **测试插件**。
3. 找到 **浏览器预览与录像**。
4. 勾选 **录制浏览器操作视频**。
5. 点击 **检测安装**，核对命令位置和版本。
6. 选择专用于测试的 **Playwright 浏览器**。没有可选项时，按[首次配置指南](浏览器实时预览一步一步配置.md#24-确认已经有-playwright-mcp)先注册 MCP。
7. 点击 **保存设置**，看到“已保存”后关闭设置。

检测只查询 CLI 版本，**不会试录，也不能证明 PyAV 已安装**。真正开始录制时，插件才会检查视频依赖；缺失时，当前测试进度会显示原因和完整安装命令。

如果终端能运行，设置页却找不到：执行 `uv tool dir --bin`，复制输出目录，加上 `/browscreen`，填入“高级设置：Browscreen 命令路径”。Windows 使用对应的 `browscreen.exe`。填程序的完整路径，不填源码目录或启动参数。

两个开关各管一件事：

| 实时预览 | 录像 | 实际效果 |
| --- | --- | --- |
| 关闭 | 关闭 | 正常测试，不启动采集服务 |
| 开启 | 关闭 | 浮窗显示实时画面，不保存视频 |
| 关闭 | 开启 | 不弹浮窗，后台录制，结束后看报告 |
| 开启 | 开启 | 同一个采集进程同时提供画面和录像 |

这些设置在**下一次测试**生效。保存不需要重启 DSH；安装新的插件代码后需要正常重启宿主并刷新网页。

## 3. 像平常一样执行测试

在 DSH 对话框输入，例如：

```text
/test 访问 http://127.0.0.1:8929/users/sign_in，断言页面存在用户名输入框、密码输入框和 Sign in 登录按钮
```

先确认 GitLab 已可用，并满足[测试要求](GitLab测试要求与本地调试.md)。这个入门检查不需要账号。复杂用例可使用本次准备生成的 `ui.md`。不用加“开始录制”，不用另外开终端启动 Browscreen。`/test-plan`、`/test-run` 和 `/test-data` 也使用保存的录像设置。

规划阶段还没有网页，不会录像。实际测试拥有兼容浏览器并取得当前页面 CDP 后，插件才启动录制；第一张有效画面到达后才有视频帧。浏览器启动、等待首帧和录制准备可能花时间，视频长度不一定等于整个测试的总耗时。

隐藏浮窗、切换对话或关闭 DSH 网页都不会停止后台录制，**DSH 宿主服务必须保持运行**。想结束测试，使用原生“停止生成”，等待清理和报告。直接强制杀掉宿主可能导致 MP4 来不及收尾，插件不会把这种文件标成完整录像。

同批多个浏览器实例分别保存视频；重新打开浏览器或切换采集目标可能产生多个片段。当前仍串行运行，不增加多对话并行支持。采集只支持单活动页面，多标签时无法继续提供确定归属的画面。

## 4. 在报告里看视频

1. 等测试结束，点击最终回复中的 **查看测试报告**。
2. 左侧选择你要看的浏览器用例实例。
3. 右侧点击 **操作录像**。
4. 点播放器的三角按钮开始播放，拖动时间轴跳到想看的位置。
5. 需要单独保存时，点击 **下载视频**。

报告列出每段视频的时长、结束时间、文件名和 SHA-256 摘要。切换用例或选项卡会暂停正在播放的视频。测试取消后成功收尾的视频会注明本次测试已取消；视频存在不代表断言通过。

| 报告里的情况 | 说明 |
| --- | --- |
| 已保存录像 | 收到完整收尾摘要，MP4 文件经过检查 |
| 部分录制 | Browscreen 提前终止，但已保存可播放的片段，报告保留原因 |
| 录像提示 | 依赖、写入、收尾或文件检查失败；没有可播放文件时不放空播放器 |
| 没有操作录像入口 | 没开录像、没有有效视频帧、没有可用归档，或该实例不使用浏览器 |

**接口测试不会出现视频、截图对话框或“等待浏览器”的占位内容。** 混合批次也一样：浏览器实例有自己的录像，接口实例只有步骤、断言和响应附件。没有 CDP 的 App 或其他任务不会因为开启录像而增加界面媒体；本功能没有新增 App 测试能力。

录像问题只影响媒体展示，不修改已计算的业务断言，也不会解除资源隔离。测试通过与否仍要看实际值、预期、断言和清理结果。

## 5. 搬走报告时，把整个文件夹一起带走

视频单独放在运行目录，不塞进 HTML：

```text
run-…/
  report.html
  results.json
  events.jsonl
  evidence/
    browser-….mp4
    其他证据文件
```

复制或压缩**整个 `run-…` 目录**，再打开其中的 `report.html`。只复制 HTML，视频会丢失；独立账本下载也需要目录内的 events.jsonl。HTML 中的结论、步骤、断言和内嵌截图仍可单独查看。原报告和“重建报告”都引用同一批 MP4；重建只使用已保存的事实，不会重新操作浏览器或补录视频。

在线报告需要 DSH 登录。为了在报告的隔离页面里播放，服务仅给该视频签发有效期 24 小时的只读地址；过期或重启服务后，重新打开报告即可取得新地址。本地文件不含这种临时地址，完整目录可离线播放。

## 6. 缺依赖或没有视频，怎么办

看到 **视频录制依赖不可用** 时，按第 1 节安装 `browscreen[video]==0.3.0`，核对设置中选的是这个入口，保存后重新执行测试。不能给已经结束的测试补录。

如果同时开了实时预览，插件在确认录制准备失败后只尝试一次关闭录像参数的预览启动，画面可继续展示，录像安装提醒保留。只开录像时不悄悄打开浮窗。普通聊天和纯接口测试不会收到全局依赖警告。

播放器打不开、没有操作录像入口、文件丢失或收尾失败的逐项处理见 [F16 录像无法生成或播放](../deployment/常见问题速查与处理.md#f16-录像无法生成或播放)。