4***@qq.com
4***@qq.com
  • 发布:2026-10-15 18:33
  • 更新:2026-10-15 18:33
  • 阅读:15

自动化测试,可能与不可用

分类:HBuilderX

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 完成连接
测试执行通过 测试套件和测试用例实际运行,并且指定断言通过
测试环境阻塞 因工具、服务、端口、设备或权限问题,测试没有有效执行
测试脚本无效 测试文件没有正确解析、没有有效断言,或证据不能证明目标行为

如何使用本文档

遇到问题时建议按以下顺序阅读:

  1. 先阅读 01-连接链路与正式状态,确定问题处在哪一层;
  2. 再对照 02-验证环境与场景矩阵,确认当前环境属于哪种场景;
  3. 按 03-排查手册 检查日志、端口和报告;
  4. 使用 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,通常需要满足:

  1. HBuilderX GUI 正在运行;
  2. 使用的 CLI 与当前 HBuilderX 属于同一版本体系或同一安装目录;
  3. CLI 能够找到官方 CLI 程序;
  4. 项目路径有效,并且包含可被 HBuilderX 识别的 uni-app x 工程文件;
  5. HBuilderX 的测试插件已经安装并且没有被禁用;
  6. CLI 项目打开操作没有超时或异常退出。

3.2 官方测试连接运行时的条件

要使页面运行时可被官方测试连接,通常需要满足:

  1. 页面 HTTP 服务已经启动;
  2. h5.url 指向正确的页面地址;
  3. 页面编译时已经配置 Automator WebSocket;
  4. Automator 主机地址可以从测试进程访问;
  5. 页面使用的 Automator 端口与 CLI 使用的端口一致;
  6. 页面服务和 Automator 服务在测试期间保持运行。

3.3 测试结果有效的条件

要把结果报告为通过,还需要满足:

  1. 测试文件可以解析;
  2. 测试套件实际启动;
  3. 测试用例数量大于零;
  4. 测试动作确实通过官方自动化 API 执行;
  5. 官方 JSON 报告已经生成;
  6. 没有把环境阻塞或脚本无效误判为通过。

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

优先检查:

  1. 页面是否只是普通 HTTP 服务;
  2. 页面是否注入了 Automator 地址;
  3. 页面和 CLI 的 Automator 端口是否一致;
  4. Automator 主机是否可访问;
  5. 页面服务是否在测试前已经重启;
  6. 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 赞 关注 分享

要回复文章请先登录或注册