testcase exec

fushou-agent testcase exec 根据 JSON 配置读取本地 XLSX，执行选中的用例，等待完成并把每条最终结果与执行过程写回源工作簿。

本地交互模式#

请先安装 Node.js 22.19.0 或更新版本。用例在本机执行，默认在终端显示工具调用并接收澄清回答。多个用例同时运行时，终端会依次展示问题及对应会话。

iOS 用例仅支持在 macOS 主机上执行。Windows 和 Linux 主机支持浏览器、本机电脑应用、Android 与 HarmonyOS 用例；包含 iOS 操作的用例请在 Mac 上运行。设备操作前仍需完成对应设备的连接与授权。

自动化脚本使用 fushou-agent testcase exec -p --config PATH。非交互终端自动使用此模式。工作簿、会话和完整执行过程保存在本机；控制台显示任务进度与汇总费用。

命令格式#

fushou-agent testcase exec --config PATH

参数与选项#

配置中的 xlsx 必须是文件绝对路径，不接受目录。文件必须存在、可读取，扩展名为 .xlsx（不区分大小写），大小为 1 字节至 15 MiB。结果逐条写回该文件。命令不读取标准输入。

最小配置：

{
  "xlsx": "/absolute/path/测试用例.xlsx"
}

将 xlsx 替换为实际工作簿的绝对路径，然后执行：

fushou-agent testcase exec --config ./config.json

Windows 文件路径中的反斜杠需要按 JSON 规则转义，例如 "C:\\tests\\cases.xlsx"。

执行前，请在管理后台完成客户端使用所需的账号配置。

长等待与恢复#

验证报表统计、定时处理等结果时，可能需要等待数小时或到次日。等待时间超过阈值后，用例会自动暂停，释放浏览器和设备资源，不占用并发执行名额。等待时间小于或等于阈值时，用例保持执行，等待结束后继续验证。

请在用例、变量或执行规则中提供明确的等待时长或可验证时间，例如“次日北京时间 09:00 后验证报表”。只有“T+1”或“报表生成后”等描述且无法确定具体时间时，用例会记为“无法验证”，并说明缺少的时间信息。

暂停时，源 XLSX 的“测试结果”暂时显示“无法验证”，“测试执行过程”保留已完成的步骤，并记录等待时长、暂停原因和计划恢复时间。暂停用例不计入管理后台的最终结果数量。验证结束后，最终结果会覆盖临时结果，执行过程保留暂停、恢复及重试记录。

等待到期的用例会优先获得空闲的并发执行名额，从暂停处继续验证，不中断正在执行的用例。恢复时可能需要重新登录或进入验证页面。按 dependency、serial 或 module_serial 执行时，受依赖或顺序约束的后续用例仍须等待暂停用例最终完成；其他可执行用例可以继续。

暂停不消耗重试次数。如果到期后结果仍不符合预期，会按正常失败处理，并根据 retry 配置从头重试整条用例，因此可能再次等待。只有用例明确规定了下一段等待时，才会继续暂停。

请保持本次 testcase exec 命令运行。命令退出或被中止后，暂停中的用例不会自动恢复；重新启动命令不能从原暂停位置接续执行。

JSON 配置#

配置文件必须包含一个 JSON 对象，只有 xlsx 必填。顶层、执行范围及范围项的未知字段均会被拒绝。

{
  "xlsx": "/absolute/path/测试用例.xlsx",
  "name": "文章回归",
  "scope": {
    "type": "modules",
    "ranges": [
      {"sheetName": "测试用例", "modules": ["文章"]}
    ]
  },
  "variables": {
    "BASE_URL": "https://example.test",
    "客户名称": "XXX",
    "TIMEOUT": 30,
    "启用验证": true,
    "客户": {"id": 1},
    "备注": null
  },
  "rule": "使用测试账号完成验证。",
  "workers": 4,
  "verbose": true,
  "retry": 0,
  "order": "dependency"
}

顶层字段#

默认执行全部可执行 Sheet 中的用例。已有结果为“跳过”或 skipped 的行不执行。默认依赖顺序要求所有选中的可执行 Sheet 包含“用例编号”和“用例依赖”列，且被引用的前置用例均在选中范围中。

变量与执行规则#

变量先使用 XLSX“变量”Sheet 的非空默认值，再应用 variables。配置中的显式值全部覆盖同名默认值，包括 ""、空白字符串、null、false、0、[] 和 {}。未提供的变量沿用 XLSX 默认值；配置独有变量也会传入执行说明。

例如 XLSX 默认客户名称为“默认客户”时：

{
  "xlsx": "/absolute/path/测试用例.xlsx",
  "variables": {"客户名称": "", "TIMEOUT": 30},
  "rule": "使用测试账号完成验证。"
}

以上配置会将客户名称覆盖为空字符串，并以 30 作为 TIMEOUT 的值。执行时会同时采用 rule 中的说明。

变量名支持中文，去除首尾空白后不能为空，且不能包含花括号、等号或换行。配置重复 key、去除空白后重名以及 XLSX 中重复变量名都会报错。请在 variables 中配置变量，在 rule 中填写操作要求。

命令会在终端打印最终采用的变量，包括显式空值，变量值不会脱敏。字符串中的换行保持原样。变量和规则不设单独的文本长度上限。

变量 Sheet 的默认值按 Excel 显示文本读取，支持富文本、超链接显示文字、数字、日期和百分比格式；字体和颜色不影响取值，使用公式时请先在 Excel 中计算并保存。

缺省值、null 与空值#

name、scope、rule、retry 和 order 的 null 按省略处理。variables、workers、verbose 省略时采用默认值，但顶层 null 会被拒绝；变量 value 中的 null 合法。

显式空白 name 无效；空对象 variables: {} 合法；空白 rule 表示没有补充规则。范围中可选的 sheetName/sheetNames 的 null 按省略处理，只有单个可执行 Sheet 时才可省略名称。

执行范围 scope#

四种范围互斥，只能选择一种。

整个工作簿#

{"type": "all"}

选择所有 Sheet 中的全部可执行用例。

指定 Sheet#

{"type": "sheets", "sheetNames": ["冒烟测试", "回归测试"]}

sheetNames 必须选择至少一个存在的 Sheet。单 Sheet 工作簿可以省略 sheetNames，多 Sheet 工作簿不能省略。

指定模块#

{
  "type": "modules",
  "ranges": [
    {"sheetName": "测试用例", "modules": ["登录", "文章"]}
  ]
}

ranges 至少包含一项；每个 Sheet 最多出现一次，modules 必须包含至少一个该 Sheet 中存在的模块。单 Sheet 工作簿可以省略 sheetName，多 Sheet 工作簿必须填写。

指定用例编号#

{
  "type": "cases",
  "ranges": [
    {"sheetName": "测试用例", "caseIds": ["CASE-001", "CASE-002"]}
  ]
}

ranges 至少包含一项；每个 Sheet 最多出现一次，caseIds 不能为空。按编号选择只检查本次指定的编号：每个编号须在对应 Sheet 的可执行行中恰好匹配一行。其他编号重复或为空、其他 Sheet 存在同名编号，不影响筛选；可选择工作表任意位置的用例。单 Sheet 工作簿可以省略 sheetName。

用例执行顺序#

执行过程与结果#

执行前会检查所需浏览器运行组件；组件缺失时自动安装，安装失败则停止。命令按 scope 选择用例，以 order 和 workers 调度，并按 retry 重试非成功结果。

每条用例的结果与执行过程会写回源 XLSX，暂停时也会更新等待记录。依赖用例等待前置用例最终完成，包括前置最终失败的情况。写回失败会停止执行、返回非零退出码，已完成的本地结果保留。

全部执行及写入结束后，工作簿列宽按内容调整，限定在 10–100。变量和辅助 Sheet、公式及其他格式保留。取消或异常时也会尽力完成格式化。需要中止时可按 Ctrl-C。

任务完成后，终端会显示结果摘要和工作簿位置。可在管理后台查看任务进度与状态，在本地工作簿查看完整结果与步骤。开启 verbose 可查看更详细的进度。

完整执行并保存结果后，会显示一次静音系统通知，包括存在失败或无法验证用例的情况。 简体中文系统显示“赋手智能体：测试用例执行完毕”，其他语言（含繁体中文）显示 Fushou Agent: Test case execution completed.。“执行完毕”不代表所有用例通过，请查看结果摘要。 取消、执行中断或结果保存失败时，不显示完成通知。 首次使用时，macOS 可能请求通知权限。若未看到通知，请检查系统通知权限及专注／勿扰模式设置； 通知未显示不影响已保存的测试结果。 支持点击操作的系统通知可直接打开本次测试用例 XLSX，使用系统默认的表格应用。 macOS 和支持通知按钮的 Linux 桌面还提供“测试用例”按钮，非简体中文系统显示 “Test cases”。 按钮的显示位置由系统决定，可能需要将鼠标移到通知上或展开通知。 如果文件已移动或删除，点击通知不会打开文件，请到新的文件位置查看。

常见配置错误#

• xlsx 必须指向实际存在的文件绝对路径；检查 JSON 中 Windows 路径的反斜杠转义。
• 多个可执行 Sheet 按 Sheet、模块或编号选择时，必须指定 Sheet 名称。
• variables 必须为对象，变量名不能重复；rule 必须为字符串或 null。
• workers 必须是 1–32 的整数，retry 必须是 0–2 的整数，verbose 必须为布尔值。

可以在控制台/测试用例/用例执行页面查看执行记录。

恢复等待澄清的任务#

交互模式仅在澄清工具提问时显示输入框并接收回答；多个用例的问题会依次显示，其余时间不接受输入。使用 -p 或非交互终端时始终不接收输入；需要澄清时保存本地任务会话并以退出码 2 结束。在交互终端使用结果中的 sessionId 恢复，恢复时不要加 -p：

fushou-agent testcase exec --resume 会话ID

恢复会继续原用例会话，保留已完成用例、工作簿结果和任务费用。请保留原工作簿及本地缓存，在同一电脑上恢复。