> ## 文档索引
> 获取完整文档索引： https://fushouagent.com/docs/llms.txt
> 先阅读此索引，了解所有可用页面。

# testcase exec

> 从本地 XLSX 发起测试用例执行，自动并发执行并逐条写回结果。

`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`。非交互终端自动使用此模式。工作簿、会话和完整执行过程保存在本机；控制台显示任务进度与汇总费用。

## 命令格式

```bash title="Terminal"
fushou-agent testcase exec --config PATH
```

## 参数与选项

| 参数 | 必填 | 说明 |
| --- | --- | --- |
| `--config PATH` | 是 | 已存在的 UTF-8 JSON 配置文件；支持相对或绝对路径，相对路径基于命令启动目录。 |
| `--help` | 否 | 显示帮助。 |

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

最小配置：

```json title="config.json"
{
  "xlsx": "/absolute/path/测试用例.xlsx"
}
```

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

```bash title="Terminal"
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` 必填。顶层、执行范围及范围项的未知字段均会被拒绝。

```json title="config.json"
{
  "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"
}
```

### 顶层字段

| 字段 | JSON 类型 | 必填 | 缺省值 | 约束与行为 |
| --- | --- | --- | --- | --- |
| `xlsx` | string | 是 | 无 | 已存在且可读取的 `.xlsx` 文件绝对路径，大小为 1 字节至 15 MiB。 |
| `name` | string | 否 | `执行用例:<XLSX 文件名>` | 显式值至少包含一个非空白字符，最多 64 个字符；自动名称超长时保留扩展名并截断至 64 字符。 |
| `scope` | object | 否 | `{"type":"all"}` | 支持 `all`、`sheets`、`modules`、`cases`，结构见下文。 |
| `variables` | object | 否 | `{}` | 每个 key 是变量名，value 支持字符串、数字、布尔值、数组、对象及 `null`。 |
| `rule` | string | 否 | 无补充规则 | 普通执行说明，可以包含多行文本。 |
| `workers` | integer | 否 | `4` | 并发用例数，1–32。 |
| `verbose` | boolean | 否 | `false` | 在终端显示详细进度、用例内容和执行结果。 |
| `retry` | integer | 否 | `0` | 用例未通过时的额外重试次数，范围 0–2；关闭恢复的长等待用例不重试。 |
| `order` | string | 否 | `dependency` | 支持 `serial`、`module_serial`、`dependency`、`max_parallel`。 |

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

### 变量与执行规则

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

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

```json
{
  "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`

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

### 整个工作簿

```json
{"type": "all"}
```

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

### 指定 Sheet

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

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

### 指定模块

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

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

### 指定用例编号

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

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

## 用例执行顺序

| 值 | 行为 |
| --- | --- |
| `serial` | 按工作簿中的稳定顺序逐条执行。 |
| `module_serial` | 同名模块内串行，包括跨 Sheet 的同名模块；不同模块之间可以并行。 |
| `dependency` | 按 XLSX“用例依赖”列中的用例编号等待直接依赖完成；客户端创建任务前校验缺失、歧义和循环依赖。这是 CLI 的默认值。 |
| `max_parallel` | 不增加顺序依赖，在配置的并发数内尽量并行。 |

## 执行过程与结果

执行前会检查所需浏览器运行组件；组件缺失时自动安装，安装失败则停止。命令按 `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`：

```bash
fushou-agent testcase exec --resume 会话ID
```

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