# CSV 参数文件使用手册

[项目首页](../../README.md) · [使用说明](使用说明.md) · [完整文档](../README.md)

想让同一条测试换几组数据运行，可以把会变化的内容放进 CSV，把测试过程写成用例模板。插件先把数据填入模板，展示每个实例的计划；你批准后，它才逐个执行。

第一次使用，可以直接照着第二节创建两个文件。示例检查 GitLab 登录页上的三个控件，不需要测试账号。

## 1. CSV 和用例模板各自负责什么

| 文件 | 保存什么 | 示例 |
| --- | --- | --- |
| CSV 参数文件 | 每次运行需要替换的数据；第一行是参数名，后面每行是一组数据 | GitLab 地址、要检查的控件名称 |
| TXT 或 Markdown 用例模板 | 做什么、检查什么；用 `${参数名}` 标出要替换的位置 | 访问 `${base_url}`，检查 `${control}` |

`${base_url}` 这样的文字叫“占位符”：执行前，它会被 CSV 中 `base_url` 这一列的值替换。两个文件配合使用，CSV 本身不会自动变成测试用例。

开始前需要已启用本插件的 DSH、可用模型和原生计划审核能力；标准 Web preset 提供审核入口。网页用例还需要专用 Playwright MCP 和 Chromium。插件安装和工具配置见[安装与运维](../deployment/安装与运维.md)。

GitLab 需要能从 DSH 宿主访问。部署由 [GitLab 官方 Docker 文档](https://docs.gitlab.com/install/docker/)负责；本项目的[测试指南](GitLab测试要求与本地调试.md)说明被测系统条件和账号要求。

## 2. 先复制一套完整示例

### 2.1 准备文件夹

在你的 DSH 工作区下面新建 `.local/csv-demo/`，把两个文件放进去：

```text
你的工作区/
└── .local/
    └── csv-demo/
        ├── data.csv
        └── cases.md
```

在这个工作区内新建或打开 DSH 对话。下文命令中的 `.local/` 都相对于这个对话的工作区；添加另一个工作区不会改变旧对话的目录。

### 2.2 创建 data.csv

用文本编辑器新建 `data.csv`，复制下面的内容，保存为 **UTF-8**：

```csv
base_url,control
http://127.0.0.1:8929,用户名输入框
http://127.0.0.1:8929,密码输入框
http://127.0.0.1:8929,Sign in 登录按钮
```

将三行中的地址都换成自己的 GitLab 地址。这个模板会在地址后追加 `/users/sign_in`，因此这里填写根地址，末尾不要加 `/`。

第一行定义两个参数：`base_url` 和 `control`。后面有三行数据，分别检查用户名输入框、密码输入框和登录按钮。

### 2.3 创建 cases.md

用文本编辑器新建 `cases.md`，复制下面的内容，也保存为 UTF-8：

```markdown
# GitLab 登录页控件检查

- 访问 ${base_url}/users/sign_in，断言页面存在${control}。
```

注意用例正文开头的 `- `。Markdown 中，每个**最外层列表项**是一条用例；只有标题和普通段落时，插件找不到用例。嵌套步骤需要缩进，留在所属列表项内。TXT 则每个非空行是一条用例。

### 2.4 提交命令

在 **DSH 对话框**中输入，不能在系统终端执行：

```text
/test-data .local/csv-demo/data.csv --file .local/csv-demo/cases.md
```

读取后应该得到：**1 条原始用例、3 行 CSV 数据、3 个执行实例**。

| 顺序 | 替换后的任务 |
| --- | --- |
| 1 | 访问 http://127.0.0.1:8929/users/sign_in，断言页面存在用户名输入框。 |
| 2 | 访问 http://127.0.0.1:8929/users/sign_in，断言页面存在密码输入框。 |
| 3 | 访问 http://127.0.0.1:8929/users/sign_in，断言页面存在 Sign in 登录按钮。 |

表中的地址是示例地址；审核时应看到你在 CSV 中填写的实际地址。

## 3. 两种提交方式

### 使用保存好的用例模板

需要长期维护或包含多条用例时，使用 `--file`：

```text
/test-data .local/csv-demo/data.csv --file .local/csv-demo/cases.md
```

用例文件支持 `.txt`、`.md` 和 `.markdown`。

### 直接在命令后写任务模板

临时检查一条任务时，可以省去用例文件：

```text
/test-data .local/csv-demo/data.csv 访问 ${base_url}/users/sign_in，断言页面存在${control}。
```

两种方式是替代入口，选择一种即可；连续提交会启动两轮测试。`/test-data` 后只有 CSV 路径而没有任务模板或 `--file`，会提示用法。

## 4. 怎样审核和执行

`/test-data` 始终先进入原生计划审核。批准前不会访问被测目标。

审核时依次核对：

1. **来源**：CSV 和用例文件是不是你刚保存的文件。
2. **数量**：原始用例数、数据行数、执行实例总数是否正确。
3. **参数与原文**：每个实例使用了哪一行数据；地址、输入内容和预期是否正确。
4. **展开后的任务**：`${参数名}` 是否已经替换成需要的值。
5. **步骤与检查点**：操作顺序和预期是否符合原始要求。

确认后批准，插件在同一对话中逐实例串行执行。需要修改文字步骤，可以在审核中提出修改意见；模型不能自行删除实例、合并实例或修改 CSV 值。

**修改 CSV 或用例文件后，要取消当前草案，再重新提交命令。** 本轮已经读取的内容是快照，后续保存文件不会自动改变正在审核或执行的任务。需要中途停止，使用 DSH 原生停止按钮。

## 5. CSV 文件怎么写

### 基本规则

| 项目 | 规则 |
| --- | --- |
| 文件类型 | 保存为 `.csv`，不要保存成 `.xlsx` 或隐藏扩展名的 `.csv.txt` |
| 编码 | 使用 UTF-8；支持带 BOM 的 UTF-8 文件 |
| 分隔符 | 使用英文逗号 `,`；中文逗号、分号或制表符不能替代 |
| 第一行 | 填参数名，不能有空参数名，不能重复；前后空格会被去掉 |
| 后续数据 | 至少一组数据，每条记录的字段数量必须与第一行一致 |
| 参数值 | 按字符串原文保留；不会自动转成数字、布尔值或日期 |
| 空行 | 完全为空的行忽略；只有空格的行可能成为数据或引发列数错误 |

推荐使用 `base_url`、`project_id`、`expected_count` 这样的列名，也支持中文列名。CSV 没有注释行语法，不要加入 `# 说明`、表格标题或额外的 `sep=,` 行。

### 逗号、双引号、换行和空值

字段中含有英文逗号、双引号或换行时，用英文双引号把整个字段包起来。字段里的一个双引号写成两个双引号：

```csv
编号,说明
001,"检查标题包含逗号，例如：需求,设计"
002,"检查标题包含双引号，例如：""功能说明"""
003,"第一行
第二行"
004,
```

| 数据记录 | 实际读取的值 |
| --- | --- |
| 001 | 编号保留为 `001`；说明包含英文逗号 |
| 002 | 说明包含一个正常的 `"功能说明"` |
| 003 | 说明包含真实换行；虽然占两行文字，仍是一条数据记录 |
| 004 | 说明为空字符串；这一条数据仍会展开并执行 |

反斜杠不能代替 CSV 的双引号转义。空字段可以留空，也可以写成 `""`；表示的是空字符串，不是自动跳过该实例。只有逗号的合法记录也会保留，例如：

```csv
a,b
,
```

它包含一组数据，`a` 和 `b` 都为空字符串。

### 前导零和空格

`001` 不会被插件改成 `1`。字段前后的空格也会保留，例如：

```csv
编号,说明
001," 两侧有空格 "
```

使用表格软件准备数据时，先将需要保留前导零的列设为文本，再输入数据；导出为 UTF-8、逗号分隔的 CSV。保存后用文本编辑器检查一次，确认中文、前导零、引号和分隔符仍然正确。插件会保留文件实际内容，无法找回被表格软件提前改变的值。

## 6. 占位符怎样替换

| 写法或情况 | 实际行为 |
| --- | --- |
| `${base_url}` | 替换成当前数据行的 `base_url` 值 |
| `${控件}` | 可以使用中文列名，但 CSV 必须有名为 `控件` 的列 |
| 同一参数出现多次 | 每个位置都会替换 |
| 大小写或名称不同 | `page` 和 `Page` 是两个名字；找不到对应列时提示缺少参数 |
| 占位符内有空格 | `${ page }` 会查找名为 ` page ` 的列；应写成 `${page}` |
| CSV 有额外列 | 可以保留，审核时会展示；不会因此多运行一条用例 |
| 参数值本身包含 `${其他参数}` | 保留为原文，不再进行第二次替换 |

占位符也可放在 Markdown 的共享背景、用例名称和预期结果中，都会按当前行替换。

替换只是在文字中填值，不计算表达式，不自动读取环境变量或其他配置文件，也不自动进行 URL 编码。例如不要用 `${page+1}` 计算下一页，应在 CSV 增加 `next_page` 列并填写所需的值。拼接接口地址时，需要事先准备适用于该 URL 的参数值。

CSV 没有内置的“是否执行”字段。即使有一列叫 `enabled`、填了 `false`，这一行仍会展开；暂时不用的数据应从本次提交的 CSV 中移除。

## 7. 多条用例配多行数据，会运行几次

执行实例总数为：**原始用例数 × CSV 数据记录数**，不包含第一行表头。

假设模板中有 A、B 两条用例，CSV 有三行数据，将得到六个实例，顺序为：

| 执行顺序 | 来源用例 | CSV 数据行 |
| --- | --- | --- |
| 1 | A | 1 |
| 2 | A | 2 |
| 3 | A | 3 |
| 4 | B | 1 |
| 5 | B | 2 |
| 6 | B | 3 |

每条用例都会使用全部数据行，不会将第一条用例只配第一行数据，也不会自动选择某些行。所有模板需要的参数列都必须存在。如果不同用例需要不同的数据集合，把它们拆成不同模板和 CSV，分别提交。

Markdown 先识别用例边界，再填入参数；参数值中的换行或列表符号不会额外创建一条用例。

## 8. 文件路径和工作区

CSV 与用例模板都必须位于**发起命令的当前对话工作区**内。

- 相对路径：从当前对话工作区根目录开始找，例如 `.local/csv-demo/data.csv`。
- 绝对路径：可以使用，但文件仍需位于当前对话工作区内。
- 含空格的路径：用英文单引号或双引号包住完整路径。
- 指向工作区外部的符号链接：会被拒绝，不能用它绕过目录范围。

例如，把文件放到工作区中的 `.local/CSV 示例/` 后，可以这样提交：

```text
/test-data ".local/CSV 示例/data.csv" --file ".local/CSV 示例/cases.md"
```

如果文件存在但提示不存在，先看错误中实际查找的路径和工作区。把正确目录加入 DSH 后，还要进入该目录的对话；原对话不会自动切换。无工作目录信息的历史会话才回退到插件配置的 `workspace`。

## 9. 使用项目已有的 GitLab 分页样例

已经完成入门示例后，可以练习接口参数化。项目提供一条[分页用例模板](../../examples/gitlab/pagination-parameterized.md)和四行[CSV 示例](../../examples/gitlab/parameters.example.csv)。

先按[GitLab 测试指南的 CSV 章节](GitLab测试要求与本地调试.md#8-体验-csv-参数化与审核)准备专用数据。它创建的公开接口项目应有固定的 alpha、beta、gamma 三条 Issue；分页每次读取一条，所以固定预期是：

| `page` | `expected_count` | 含义 |
| --- | --- | --- |
| 1 | 1 | 第一页一条 |
| 2 | 1 | 第二页一条 |
| 3 | 1 | 第三页一条 |
| 4 | 0 | 第四页为空 |

将 CSV 示例复制到本轮私有目录，填写以下两列：

- `base_url`：你实际使用的 GitLab 根地址。
- `project_id`：本次准备的**接口项目数字 ID**，可以从生成的 `api.md` 的项目搜索预期中找到；四行都填写相同 ID。

保留 `page` 和 `expected_count` 的固定规则。公开示例里的 `<本次接口项目ID>` 是提示文字，必须替换后再运行。预期来自预先准备的数据，不根据本轮实际响应倒推。

以插件源码根目录作为当前对话工作区，在 DSH 对话框执行：

```text
/test-data .local/gitlab/本次标记/pagination.csv --file examples/gitlab/pagination-parameterized.md
```

把“本次标记”替换成准备脚本打印的真实目录。复制到其他工作区运行时，CSV 和模板都要在该工作区内。

一条模板配四行数据得到四个实例，每例检查 HTTP 状态码和响应数组长度。这个模板执行无认证 GET JSON 请求，不操作浏览器，报告中也不会显示浏览器画面或录像区域。它用于体验参数化；完整业务字段检查见 [GitLab 用例指南](GitLab复杂用例.md)。

包含账号、密码等私有数据的 CSV 应保存在不提交的本机目录。当前项目忽略 `.local/`；使用自己的 Git 仓库时，也要将相应私有目录加入忽略配置。

## 10. 查看结果和复用用例

输入框上方的进度区展示当前步骤、已结算数量和耗时。最终回复提供测试报告链接，报告按执行实例记录结果，可以按来源用例和数据行筛选；“用例来源与参数”展示该实例的模板、参数和展开后的任务。

实际采集、断言结果、失败及重试记录在报告中查看。需要把测试交给其他执行人时，可以下载 Markdown 手工用例：原始用例保留参数模板，实际步骤包含真实操作和输入。手工用例的具体内容见[实际步骤与手工用例](实际步骤与手工用例.md)，报告保存与重建见[使用说明](使用说明.md#查看报告)。

## 11. 常见错误速查

| 现象或提示 | 先检查什么 | 怎样处理 |
| --- | --- | --- |
| 文件不存在 | 错误里实际查找路径是否正确 | 在正确工作区的对话提交，核对文件名和扩展名 |
| 输入文件必须位于项目工作区 | 文件是否属于另一个目录，或链接到了工作区外部 | 将 CSV 和模板放入当前工作区，或进入对应工作区的对话 |
| 输入文件必须使用 UTF-8 编码 | 是否导出了其他编码的 CSV | 重新保存为 UTF-8 |
| 参数文件必须是 `.csv` | 是否误用了 `.xlsx`、`.txt` 或 `.csv.txt` | 导出真正的 CSV 文件，再提交 |
| CSV 表头不能为空 | 首行是否缺失、首行有空字段，或末尾多了逗号 | 每列填写一个参数名，去掉多余字段 |
| CSV 参数名重复 | 参数名在去掉前后空格后是否重复 | 改成不重复的列名，并同步模板 |
| CSV 至少需要一条数据记录 | 是否只有表头和空行 | 增加至少一组数据 |
| CSV 缺少模板参数列 | 列名与 `${参数名}` 是否完全一致 | 补列或改占位符，注意大小写和空格 |
| CSV 格式错误或列数不一致 | 引号是否闭合，字段中的逗号是否未加引号 | 用双引号包住包含逗号或换行的字段，保证每条记录字段数一致 |
| 没有找到用例 | Markdown 是否只有标题和普通段落 | 用最外层列表项写用例，或改用 TXT 非空行 |
| 运行实例比预期多 | 原始用例数是否被误拆，是否误解了全部数据展开规则 | 检查 Markdown 缩进和“用例数 × 数据记录数”，必要时拆分文件 |
| 修改文件后任务没变 | 是否还在审核或执行旧草案 | 取消旧草案，保存文件后重新提交命令 |
| 没有原生计划审核能力 | 是否用了缺少计划服务的自定义 preset | 使用标准 Web preset，或按[安装说明](../deployment/安装与运维.md#原生计划审核依赖)配置审核服务 |
| 新运行被环境未释放阻止 | 旧运行是否已停止、是否有残留 | 按[环境恢复指南](测试环境卡住怎么办.md)在设置页处理，再重新提交 |

需要进一步查看命令、输入和报告规则时，阅读[使用说明](使用说明.md)；安装、预览和环境相关问题见[常见问题速查](../deployment/常见问题速查与处理.md)。