HBuilderX 官方自动化测试 CLI 连接与运行指南
文档定位
本文档总结 HBuilderX 官方自动化测试 CLI 在 Web 测试中的完整连接链路,重点说明以下问题:
- CLI 在什么条件下可以连接正在运行的 HBuilderX;
- HBuilderX 官方测试在什么条件下可以连接项目运行时;
- 已运行的 Web 服务在什么条件下可以被复用;
- 什么情况属于 CLI 连接失败、运行时连接失败、编译失败、测试失败或环境阻塞;
- 如何用日志和官方 JSON 报告判断测试结果是否有效。
本文不依赖某个具体业务项目,不包含项目名称、业务页面、项目目录和本机用户信息。
结论摘要
官方 Web 自动化测试不是单一连接,而是连续的多阶段流程:
官方 CLI
│
├── 连接 HBuilderX GUI 和官方 CLI 能力
│
├── 打开或识别测试项目
│
├── 启动或连接 Web 页面服务
│
├── 连接页面对应的 Automator WebSocket 运行时
│
└── 执行测试并生成官方 JSON 报告
只有最后一阶段也得到有效报告,才能说明一次官方测试完整完成。
“CLI 能找到 HBuilderX”不等于“官方测试通过”;“页面能在浏览器中打开”也不等于“Automator 运行时可以连接”。
文档目录
01-连接链路与正式状态
说明 CLI、HBuilderX、Web 服务、Automator 和测试报告之间的关系,并定义“可正常执行”“失败”“阻塞”等正式状态。
02-验证环境与场景矩阵
记录本次实际验证环境,以及已经执行过的正向、负向和边界场景。
03-排查手册
提供从 CLI 连接到测试报告的逐步排查流程、日志关键词和常见误区。
04-验证记录模板
提供可以复制到其他机器或其他版本环境中的验证记录模板。
正式术语
本文尽量不使用“顺利”“不顺利”这类含义不明确的说法,统一使用以下术语:
| 术语 | 含义 |
|---|---|
| CLI 连接成功 | CLI 找到并成功调用目标 HBuilderX 的官方 CLI 能力 |
| 项目打开成功 | CLI 的项目打开操作返回成功,HBuilderX 能识别目标项目 |
| Web 服务启动成功 | 页面 HTTP 服务能够启动并返回页面资源 |
| Automator 连接成功 | 测试运行时与页面内置的 Automator WebSocket 完成连接 |
| 测试执行通过 | 测试套件和测试用例实际运行,并且指定断言通过 |
| 测试环境阻塞 | 因工具、服务、端口、设备或权限问题,测试没有有效执行 |
| 测试脚本无效 | 测试文件没有正确解析、没有有效断言,或证据不能证明目标行为 |
如何使用本文档
遇到问题时建议按以下顺序阅读:
- 先阅读 01-连接链路与正式状态,确定问题处在哪一层;
- 再对照 02-验证环境与场景矩阵,确认当前环境属于哪种场景;
- 按 03-排查手册 检查日志、端口和报告;
- 使用 04-验证记录模板 记录版本、配置、证据和边界。
适用范围
本文主要针对:
- HBuilderX 官方 Web 自动化测试;
uniapp.test web-chrome测试入口;- uni-app x Web 编译服务;
- Playwright Chromium 和 Automator WebSocket 运行时;
- CLI 连接 HBuilderX、连接项目和判断官方测试结果。
本文不替代以下内容:
- 业务页面测试用例设计;
- Android 真机键盘、焦点和生命周期验收;
- Tauri WebView、Rust 宿主和 SQLite 验收;
- 生产环境部署或发布构建说明。
版本边界
本次验证使用的环境和结论见 02-验证环境与场景矩阵。HBuilderX、uni-app x 编译器或官方测试插件升级后,应重新记录版本并复测关键正向、负向场景。
官方参考资料
01. 连接链路与正式状态
1. 完整连接链路
官方 Web 自动化测试应拆成三个阶段。三个阶段的通过标准不同,不能用前一个阶段的结果替代后一个阶段的结果。
阶段一:CLI → HBuilderX
阶段二:HBuilderX 官方测试 → Web/Automator 运行时
阶段三:测试套件 → 有效测试报告
阶段一:CLI 连接 HBuilderX
该阶段确认测试入口能够找到并调用 HBuilderX。
主要检查:
- HBuilderX GUI 是否正在运行;
- CLI 是否找到可用的
cli.exe; - CLI 和 GUI 是否来自同一套 HBuilderX 安装;
- CLI 是否能执行项目打开操作;
- HBuilderX 官方测试插件是否被正确加载;
- 官方测试命令是否真正开始运行。
阶段一通过,只能说明控制入口可用,不能说明页面运行时已经连接。
阶段二:官方测试连接 Web/Automator 运行时
该阶段确认浏览器页面和自动化运行时可以被测试执行器使用。
需要同时检查两条通道:
HTTP 通道: CLI → h5.url → Web 页面
Automator 通道: CLI → WebSocket → 页面运行时
HTTP 通道负责页面和资源访问。Automator 通道负责页面对象查询、点击、输入、路由和断言等自动化操作。
页面能打开而 Automator 不能连接时,仍然不能执行有效的官方自动化测试。
阶段三:测试套件执行并生成有效报告
该阶段确认测试文件确实被解析、执行并产生可信证据。
至少需要确认:
- 测试套件数量大于零;
- 测试用例数量大于零;
- 测试文件没有语法错误;
- 没有运行时连接异常;
- 断言结果符合预期;
- 官方 JSON 报告已经生成。
如果 CLI 找到了 HBuilderX,但测试套件没有执行,不能报告为完整通过。
2. 三种连接结果必须分开描述
2.1 CLI 连接 HBuilderX 成功
表示:
- HBuilderX GUI 已被检测到;
- CLI 找到了对应的官方 CLI 程序;
- 项目打开命令返回成功;
- 官方测试插件开始处理测试命令。
这只是控制层连接成功。
2.2 Automator 运行时连接成功
表示:
- 浏览器已经打开
h5.url指向的页面; - 页面编译结果包含 Automator 连接配置;
- CLI 使用的主机和端口能够访问页面运行时;
- 日志出现
connected或program ready。
这才说明页面具备被官方自动化操作的条件。
2.3 测试报告有效
表示:
- 测试文件已经被 Jest 正确解析;
- 至少一个测试套件和一个测试用例实际执行;
- 报告中的失败和运行异常数量符合预期;
- 通过结果与测试动作和断言一致。
这才可以报告一次完整的官方测试通过。
3. 正常使用条件
3.1 CLI 连接 HBuilderX 的条件
要使 CLI 能够连接 HBuilderX,通常需要满足:
- HBuilderX GUI 正在运行;
- 使用的 CLI 与当前 HBuilderX 属于同一版本体系或同一安装目录;
- CLI 能够找到官方 CLI 程序;
- 项目路径有效,并且包含可被 HBuilderX 识别的 uni-app x 工程文件;
- HBuilderX 的测试插件已经安装并且没有被禁用;
- CLI 项目打开操作没有超时或异常退出。
3.2 官方测试连接运行时的条件
要使页面运行时可被官方测试连接,通常需要满足:
- 页面 HTTP 服务已经启动;
h5.url指向正确的页面地址;- 页面编译时已经配置 Automator WebSocket;
- Automator 主机地址可以从测试进程访问;
- 页面使用的 Automator 端口与 CLI 使用的端口一致;
- 页面服务和 Automator 服务在测试期间保持运行。
3.3 测试结果有效的条件
要把结果报告为通过,还需要满足:
- 测试文件可以解析;
- 测试套件实际启动;
- 测试用例数量大于零;
- 测试动作确实通过官方自动化 API 执行;
- 官方 JSON 报告已经生成;
- 没有把环境阻塞或脚本无效误判为通过。
4. 不正常使用的典型情况
4.1 HBuilderX 没有运行
CLI 无法连接 GUI 控制入口。此时不应把问题归类为业务页面测试失败,应记录为环境阻塞。
4.2 CLI 找到的 HBuilderX 与当前 GUI 不一致
可能出现以下问题:
- CLI 使用了另一套 HBuilderX 的
cli.exe; - 编译器版本与测试插件版本不匹配;
- CLI 打开的项目和 GUI 当前项目不是同一个实例;
- 测试配置被不同版本的插件以不同方式修改。
排查时应记录 GUI 版本、CLI 路径、CLI 输出版本和编译器版本。
4.3 CLI 可以连接 HBuilderX,但项目打不开
这表示控制入口可用,但项目识别或项目路径存在问题。应单独记录项目打开失败,不要直接归类为 Automator 失败。
4.4 CLI 可以连接 HBuilderX,但 Automator 连接失败
这通常表示阶段一通过、阶段二失败。常见原因包括:
h5.url指向普通 HTTP 服务;- 页面没有注入 Automator 地址;
- 页面和 CLI 使用不同的 Automator 端口;
- Automator 主机地址不可达;
- 页面服务已经重启,CLI 仍连接旧端点。
4.5 Automator 已连接,但测试脚本没有有效执行
这通常是阶段三问题,常见原因包括:
- 测试文件语法错误;
- 测试范围没有包含目标文件;
- 测试文件没有有效用例;
- 断言或页面入口本身有问题;
- 报告生成失败。
5. Web 服务复用在完整链路中的位置
“复用已经运行的 Web 服务”只是阶段二的一种运行方式,不是 CLI 连接 HBuilderX 的全部定义。
5.1 CLI 自行编译
CLI 负责启动 Web 编译服务和 Automator 运行时。这种方式中,CLI 的服务生命周期最清晰,适合先验证工具链本身。
5.2 复用带 Automator 的已有服务
已有服务必须同时提供:
- 页面 HTTP 地址;
- 页面编译时注入的 Automator WebSocket 地址;
- CLI 可以访问的主机和端口。
5.3 复用普通 GUI Web 服务
普通 GUI Web 服务可以成功返回页面,但如果没有 Automator 端点,不能直接作为官方自动化测试服务复用。
6. 正式状态定义
建议统一使用以下状态,避免“可用”“不顺利”等表达产生歧义。
| 状态 | 正式含义 | 是否可以报告为通过 |
|---|---|---|
passed |
指定连接检查和测试用例均已实际执行并通过 | 可以,但仅限已覆盖范围 |
failed |
测试已经执行,但连接、代码或断言实际失败 | 不可以 |
blocked |
因 HBuilderX、服务、端口、权限或工具链问题,测试没有有效执行 | 不可以 |
incomplete |
测试能够运行,但覆盖范围或必要验证尚未完成 | 不可以作为完整通过 |
test-invalid |
测试脚本没有有效执行,或证据不能证明目标行为 | 不可以 |
7. 结论表达示例
正确表达
CLI 已成功连接 HBuilderX,项目打开操作返回成功;但 Automator 运行时未完成连接,因此本次 Web 自动化测试记录为
failed,不能报告为完整通过。页面 HTTP 服务访问正常,Automator WebSocket 端口与 CLI 配置一致,测试报告包含一个通过套件和一个通过用例,因此该复用场景在本次环境中验证通过。
HBuilderX GUI 未运行,CLI 测试入口未能建立,测试没有有效执行,因此记录为
blocked。
不建议表达
- “HBuilderX 可以用,所以测试可以用”;
- “页面能打开,所以自动化通过”;
- “CLI 启动了,所以测试已经完成”;
- “没有看到错误,所以应该通过”;
- “compile:false 就会自动复用开发服务”。
02. 验证环境与场景矩阵
1. 本次验证环境
本节记录实际验证环境,帮助读者判断版本差异。文档不记录具体业务项目名称、项目目录和用户信息。
1.1 工具链
- 操作系统:Windows 桌面环境;
- 命令行环境:PowerShell;
- HBuilderX 安装目录:
D:\App\HBuilderX;对外分享时可替换为<HBuilderX-root>; - HBuilderX 官方 CLI:
<HBuilderX-root>\cli.exe;本次验证对应D:\App\HBuilderX\cli.exe; - HBuilderX 内置 Node.js:由
<HBuilderX-root>\plugins\node\node.exe提供; - HBuilderX:
5.31.2026093020-alpha; - HBuilderX 官方自动化测试 CLI:命令行输出版本
5.4.0; - uni-app x 编译器:
5.31,VDOM 模式; - 测试平台:
web-chrome; - 浏览器驱动:Playwright Chromium;
- 浏览器模式:无头模式;
- 页面测试视口:官方运行时默认移动端视口。
1.2 HBuilderX 和 CLI 状态
本次运行入口要求 HBuilderX GUI 已经启动。测试脚本先检查 HBuilderX 进程,再解析与当前安装对应的 cli.exe。
CLI 执行项目打开操作后,再调用官方 Web 自动化测试命令。已实际观察到项目打开命令返回成功,说明控制入口阶段可以建立。
1.3 Web 服务状态
本次验证使用了两类服务:
普通 GUI Web 服务
- 页面地址示例:
http://127.0.0.1:5173/; - HTTP 请求可以得到成功响应;
- 进程参数为普通 uni-app x Web 启动方式;
- 未发现
--auto-port或--auto-host; /main响应中未发现可供测试运行时使用的 Automator 端点。
带 Automator 地址的独立 Web 服务
- 页面地址示例:
http://127.0.0.1:5174/; - Automator 主机:
127.0.0.1; - Automator 端口示例:
9538; - 服务启动时明确注入 Automator 地址;
- 用于验证“官方 CLI 复用带 Automator 端点的已有服务”。
1.4 环境边界
本次矩阵只验证 Web 自动化测试连接链路,不包含:
- Android 真机或模拟器自动化;
- Tauri WebView 和 Rust 宿主;
- 数据库读写和业务数据验收;
- 完整业务页面覆盖;
- 远程机器、局域网和跨主机防火墙验证。
2. 场景矩阵
下表覆盖了判断核心连接条件所需的关键正向和负向场景。它不是所有配置组合的穷举。
| 编号 | 场景 | 阶段一:CLI → HBuilderX | 阶段二:Web/Automator | 阶段三:测试报告 | 结果 |
|---|---|---|---|---|---|
| A | CLI 自行编译并启动 Web 服务 | 成功 | 成功 | 有效通过报告 | 可正常执行 |
| B | 复用带 Automator 的已有服务 | 成功 | 页面地址和端口匹配,连接成功 | 1 个冒烟用例通过 | 可以复用 |
| C | 复用普通 GUI Web 服务 | 成功 | 页面可访问,但 Automator 连接失败 | 运行时异常或无有效用例 | 不能复用 |
| D | 已有服务端口与 CLI 端口不一致 | 成功 | Failed to connect to runtime |
测试未有效开始 | 连接失败 |
| E | compile:false、无 h5.url、绑定地址无效 |
成功 | CLI 自行编译时 EADDRNOTAVAIL |
未生成有效报告 | 环境阻塞 |
| F | compile:false、无 h5.url、本机地址有效 |
成功 | CLI 仍尝试自行编译,未复用 GUI 服务 | 超时或无有效报告 | 环境阻塞 |
| G | 检查 GUI 服务是否自带 Automator | 成功 | 当前 GUI 服务未发现端点 | 不适用 | 普通 Web 服务 |
3. 各场景说明
3.1 场景 A:CLI 自行编译并启动
该场景中,官方 CLI 自己启动编译器和 Automator 运行时。
验证重点:
- 主机地址可以被当前机器绑定;
- 编译服务可以启动;
- CLI 能够打开页面;
- Automator 运行时能够连接;
- 测试报告中存在实际执行的测试用例。
该场景可以证明官方 CLI 自己管理整条链路时能够工作,但不能证明普通 GUI 服务可以被复用。
3.2 场景 B:复用带 Automator 的已有服务
该场景中,先启动页面服务,并在编译时注入 Automator 地址,再让官方 CLI 使用相同的页面地址和 Automator 端口。
成功条件:
页面地址: http://127.0.0.1:5174/
页面 Automator: 127.0.0.1:9538
CLI Automator: 127.0.0.1:9538
本次验证中,运行日志出现了 Automator 连接和 program ready,并且冒烟用例通过。这证明“已有服务复用”本身是可行的,但前提是服务已经具备 Automator 能力。
3.3 场景 C:复用普通 GUI Web 服务
该场景中,页面地址可以访问,但服务只提供普通 HTTP/Vite 能力,没有对应 Automator 端点。
实际表现:
- 浏览器上下文可以创建;
- 页面 URL 可以被访问;
- 运行时连接阶段失败;
- 出现
Failed to connect to runtime; - 测试套件可能没有真正执行。
这说明页面服务可访问和官方自动化可用是两个独立条件。
3.4 场景 D:端口不一致
已有页面服务在编译时使用 Automator 端口 9538,而 CLI 运行时使用动态分配的 9539。
两个进程可能都处于运行状态,但它们不会自动建立同一个 Automator 会话,最终表现为运行时连接失败。
3.5 场景 E:无效绑定地址
在 compile:false 且没有 h5.url 的配置下,CLI 仍尝试启动自己的编译服务。如果 Automator 主机被设置为当前机器不存在的地址,编译器会在监听阶段报:
EADDRNOTAVAIL: address not available
这属于服务启动失败,不属于测试用例断言失败。
3.6 场景 F:compile:false 但没有 h5.url
将绑定地址改为 127.0.0.1 后,CLI 仍尝试启动自己的编译服务。由于 GUI 已占用默认页面端口,CLI 改用其他页面端口,但没有自动复用 GUI 服务,最终测试没有有效完成。
该结果说明:
compile:false不是“自动查找并复用已有 Web 服务”的充分条件。
3.7 场景 G:检查 GUI 服务是否自带 Automator
本次检查包括:
- 查看 Web 服务进程启动参数;
- 查看页面入口响应;
- 检查页面和日志中是否存在 Automator 地址;
- 检查对应 Automator 端口是否监听。
当前 GUI 服务是普通 Web 编译服务,没有发现官方自动化复用所需的 Automator 端点。
4. 环境与结论的边界
4.1 已确认的事实
- 当前版本的官方 CLI 可以连接正在运行的 HBuilderX;
- CLI 可以执行项目打开操作;
- CLI 可以自行编译并运行 Web 自动化测试;
- 带匹配 Automator 地址的已有服务可以被复用;
- 普通 HTTP/Vite 服务不能仅凭页面地址被复用;
- Automator 端口不一致会导致运行时连接失败;
compile:false不足以单独决定复用哪一个已有服务;- 无效主机地址会导致编译服务启动失败。
4.2 尚未穷举的组合
以下内容没有在本次矩阵中全部穷举:
- 其他 HBuilderX 版本的 CLI 与 GUI 组合;
- 不同操作系统下的网络绑定行为;
- 局域网地址和远程测试机之间的连接;
- GUI 中可能新增的 Automator 服务启动选项;
- 所有
compile、h5.url、主机、端口排列组合; - 完整业务页面和多页面测试。
因此,本文应使用“在本次验证环境中确认”这样的表述,不应宣称已经验证了所有版本和所有配置。
5. 复现记录最少应包含的环境信息
- 操作系统和命令行环境;
- HBuilderX 版本;
- 官方 CLI 输出版本;
- uni-app x 编译器版本和渲染模式;
- 测试平台和浏览器驱动;
- HBuilderX GUI 是否正在运行;
- CLI 实际使用的路径;
- 项目打开结果;
- 页面 HTTP 地址和端口;
- Automator 主机和端口;
compile、h5.url和自定义环境变量;- 测试报告路径和套件/用例统计;
- 未覆盖的场景和环境限制。
03. 排查手册
1. 排查原则
排查时不要直接从业务断言开始。应按官方测试的实际连接顺序逐层确认:
HBuilderX GUI
↓
CLI 程序
↓
项目打开
↓
Web 页面服务
↓
Automator WebSocket
↓
测试套件
↓
官方 JSON 报告
前一层没有通过时,不要用后一层的现象解释问题。
2. 第一步:确认 HBuilderX GUI
需要确认:
- HBuilderX 窗口或进程确实正在运行;
- 没有停留在启动失败、更新未完成或插件加载失败状态;
- 当前 HBuilderX 是期望使用的版本;
- 目标项目已经被 HBuilderX 识别。
如果 HBuilderX 没有运行,CLI 通常不能依靠测试命令自行替代 GUI 控制入口。应记录为 blocked,不要报告为业务测试失败。
3. 第二步:确认 CLI 来源
记录 CLI 实际使用的完整路径和输出版本。
重点检查:
- CLI 是否来自当前 HBuilderX 安装目录;
- 是否存在多个 HBuilderX 安装;
- 环境变量是否把 CLI 指向了旧安装;
- CLI 调用的内置 Node、编译器和测试插件是否属于同一套安装。
如果 GUI 和 CLI 不是同一版本体系,首先应排除工具链混用问题。
4. 第三步:确认项目打开
CLI 项目打开操作成功,只能证明项目控制入口可用。
需要记录:
- 项目路径是否存在;
- 项目是否包含有效的 uni-app x 工程文件;
- CLI 项目打开命令的退出码;
- 是否出现“项目未打开”“项目不存在”或超时;
- HBuilderX 是否切换到目标项目。
项目打开失败时,不要继续修改页面测试断言。应先解决工程识别或 CLI 连接问题。
5. 第四步:确认测试配置
至少检查以下配置:
5.1 compile
确认是否让官方 CLI 自己编译,还是准备复用已有服务。
不要把以下两种含义混为一谈:
compile:false:不应简单解释为“自动连接任意已运行服务”;h5.url:只指定页面访问地址,不自动为页面添加 Automator 能力。
5.2 h5.url
如果要复用已有 Web 服务,应确认:
- 地址指向当前实际运行的页面服务;
- 协议、主机、端口和路径都正确;
- 该页面服务在测试期间不会被切换或重启。
5.3 Automator 主机和端口
确认页面编译时使用的 Automator 主机、页面实际连接的端口,以及 CLI 测试运行时使用的端口。
推荐把三者记录在同一张表中:
| 位置 | 主机 | 端口 |
|---|---|---|
| 页面编译配置 | 127.0.0.1 |
9538 |
| 页面实际运行时 | 127.0.0.1 |
9538 |
| CLI 测试运行时 | 127.0.0.1 |
9538 |
页面端口和 Automator 端口可以不同,但页面和 CLI 的 Automator 端点必须指向同一个运行时。
6. 第五步:确认 HTTP 页面服务
先验证页面 HTTP 地址,再验证 Automator。
PowerShell 示例:
Invoke-WebRequest -UseBasicParsing -Uri 'http://127.0.0.1:<web-port>/'
页面请求失败时,检查:
- Web 服务是否已经启动;
- 页面端口是否被其他进程占用;
- 服务是否绑定到正确主机;
- 服务是否在测试过程中退出;
- CLI 日志是否显示了实际使用的 URL。
页面 HTTP 检查成功后,仍必须继续检查 Automator 端点。
7. 第六步:确认 Automator 运行时
重点查看官方测试日志中的以下信息:
automator:launcher
automator:runtime
connected
program ready
Failed to connect to runtime
7.1 出现 connected 或 program ready
说明 Automator 运行时已经建立连接,可以继续判断测试脚本和页面行为。
7.2 出现 Failed to connect to runtime
优先检查:
- 页面是否只是普通 HTTP 服务;
- 页面是否注入了 Automator 地址;
- 页面和 CLI 的 Automator 端口是否一致;
- Automator 主机是否可访问;
- 页面服务是否在测试前已经重启;
- CLI 是否连接到了旧端口或动态分配的新端口。
该错误通常不是业务用例断言失败。
7.3 出现 EADDRNOTAVAIL
说明服务尝试绑定当前机器无法使用的主机地址。应先检查主机配置和网络接口,不要先修改测试脚本。
7.4 页面端口被占用
如果日志显示 Web 服务自动换到其他页面端口,应确认:
h5.url是否仍然指向旧端口;- 页面编译结果中的 Automator 地址是否仍然有效;
- CLI 是否真的连接了新服务;
- 是否因此误把端口变化当成页面测试失败。
8. 第七步:确认测试套件真正执行
Automator 连接成功后,还要确认 Jest 测试本身有效。
重点检查:
- 测试文件是否被纳入
testMatch; - 测试文件是否可以被 Babel/Jest 解析;
- 测试套件数量是否大于零;
- 测试用例数量是否大于零;
- 测试是否在
beforeAll或页面启动阶段失败; - 页面断言是否真正执行。
如果日志显示:
Tests: 0 total
则不能把这次运行报告为功能通过。
如果出现 JavaScript 语法错误,应记录为 test-invalid 或测试脚本失败,而不是 Automator 连接成功。
9. 第八步:确认官方 JSON 报告
官方 JSON 报告是判断测试是否有效的重要证据。至少检查:
- 报告文件是否生成;
numTotalTestSuites是否大于零;numTotalTests是否大于零;numRuntimeErrorTestSuites是否为零;numFailedTestSuites是否为零;numFailedTests是否为零;success字段与详细统计是否一致。
建议不要只看终端最后一行,也不要只看退出码。退出码、日志和 JSON 报告需要相互印证。
10. 错误现象与处理方向
| 错误现象 | 优先判断 | 不应直接判断为 |
|---|---|---|
| 未检测到 HBuilderX | GUI 或 CLI 环境阻塞 | 页面业务失败 |
| 项目打开失败 | 项目路径或 HBuilderX 识别问题 | Automator 断言失败 |
EADDRNOTAVAIL |
绑定主机地址无效 | 测试用例失败 |
Failed to connect to runtime |
Automator 地址、端口或注入缺失 | 页面 HTTP 不可访问 |
| 页面可打开但测试为 0 | 测试范围、脚本或运行时问题 | 功能通过 |
| JavaScript 语法错误 | 测试脚本无效 | Web 服务连接失败 |
| 生成报告但包含运行异常 | 测试没有完整通过 | 仅凭 success 字段通过 |
| 超时且没有有效报告 | 环境阻塞或进程未完成握手 | 业务断言失败 |
11. 常见误区
11.1 CLI 已启动,不代表 HBuilderX 已连接
CLI 进程启动只能说明命令被调用。还需要确认 HBuilderX 检测、项目打开和官方测试插件初始化结果。
11.2 HBuilderX 已连接,不代表页面运行时已连接
控制层和运行时是两个阶段。必须继续查看 Automator 日志。
11.3 页面可访问,不代表页面可自动化
普通 HTTP/Vite 服务可能没有 Automator WebSocket。
11.4 compile:false 不保证复用服务
没有 h5.url 或没有匹配的 Automator 端点时,CLI 可能自行启动编译服务,或者最终无法完成运行时连接。
11.5 动态端口不应未经确认直接使用
页面编译时注入的端口、CLI 运行时端口和页面实际连接端口必须一致。只看到 CLI 分配了端口,不代表页面已经同步使用该端口。
11.6 一个冒烟用例通过不等于完整验收通过
冒烟用例只能证明连接链路和该用例覆盖的行为。完整应用验收仍需独立的测试矩阵和必要的平台验证。
12. 推荐的最小排查命令
以下命令仅用于说明检查顺序,实际路径和端口应替换为当前环境值:
# 检查页面 HTTP 服务
Invoke-WebRequest -UseBasicParsing -Uri 'http://127.0.0.1:<web-port>/'
# 检查 Automator 端口
Test-NetConnection -ComputerName 127.0.0.1 -Port <automator-port>
# 使用 HBuilderX 官方 CLI 打开项目
<hbuilderx-cli> project open --path <project-root>
# 执行官方 Web 自动化测试
<hbuilderx-cli> uniapp.test web-chrome --project <project-root>
如果当前 PowerShell 或 HBuilderX 版本不支持某个检查命令,应记录替代命令和实际输出,不要把未执行的检查写成通过。
13. 清理和恢复
测试工具可能临时修改测试范围、环境配置或生成报告文件。测试结束后应确认:
- 仅保留用户明确需要的配置变化;
- 临时测试文件已经清理;
- 临时编译进程已经退出;
- HBuilderX 原有 Web 服务没有被误停;
- 失败证据、日志和 JSON 报告按需要保留;
- 配置文件差异经过审查。
14. 排查结论模板
可以使用以下格式记录一次结果:
HBuilderX GUI:已运行 / 未运行
CLI 连接:成功 / 失败
项目打开:成功 / 失败
页面 HTTP 服务:可访问 / 不可访问
Automator 运行时:已连接 / 未连接
测试套件:已执行 / 未执行
官方 JSON 报告:有效 / 缺失 / 内容不完整
最终状态:passed / failed / blocked / incomplete / test-invalid
根因:
证据:
未覆盖范围:
0 个评论
要回复文章请先登录或注册