如何用 Hoppscotch CLI 的 iteration-count 与 iteration-data 选项运行数据驱动集合测试

如何用 Hoppscotch CLI 的 iteration-count 与 iteration-data 选项运行数据驱动集合测试

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch

当你的 Hoppscotch 集合（collection JSON 文件）需要用多组不同的参数重复执行时——例如对 3 个不同的回显地址各发一次请求、或用一组 CSV 数据行驱动同一组测试断言——Hoppscotch CLI 提供了两个直接服务于该场景的选项：--iteration-count指定集合要重复执行的轮数，--iteration-data指定一个 CSV 数据文件，让每一轮迭代从该文件中取一行数据替换进环境变量。两者都作用于hopp test命令，属于 hoppscotch-cli README 中列出的命令选项。

准备条件

安装 CLI 前先按平台装好编译依赖，README 给出了各平台的依赖安装方式，例如 Debian/Ubuntu 系：

sudo apt-get install python g++ build-essential

Alpine Linux 对应sudo apk add python3 make g++，Amazon Linux、Arch、RHEL/Fedora 的对应命令同样列在 README 的 Install 一节。依赖就绪后从 npm 全局安装：

npm i -g @hoppscotch/cli

安装完成后，需要准备三类文件：

• 一个 Hoppscotchcollection.json文件（或工作区中的集合 ID）；
• 一个可选的环境变量 JSON 文件（通过-e, --env传入），内容为"KEY": "value"形式的键值对，例如：

{ "ENV1": "value1", "ENV2": "value2" }

• 一个用于--iteration-data的 CSV 文件（下一节说明格式）。

准备 iteration-data 使用的 CSV 数据文件

--iteration-data <file_path>接受 CSV 文件路径，文件第一行是表头，后续每行是一组迭代数据。README 给出的格式示例为：

key1,key2,key3 value1,value2,value3 value4,value5,value6

替换规则是：每一轮迭代，对应行的各值会作为同名 key 写入环境；第 1 轮用value1,value2,value3，第 2 轮用value4,value5,value6，以此类推。仓库的 e2e 测试夹具提供了一个真实示例 iteration-data-export.csv：

URL,BODY_KEY,BODY_VALUE https://echo.hoppscotch.io/1,,body_value1 https://echo.hoppscotch.io/2,,body_value2 https://echo.hoppscotch.io/3,,body_value3

注意第二列BODY_KEY在数据行中是空值：解析逻辑会忽略空字符串值的列，空出来的 key 回退到-e环境文件里提供的值（见 test.ts 的 CSV 转换代码）。对应的环境文件 iteration-data-envs.json 为：

{ "v": 0, "name": "Iteration data environments", "variables": [ { "key": "URL", "value": "https://httpbin.org/get" }, { "key": "BODY_KEY", "value": "overriden-body-key-at-environment" }, { "key": "BODY_VALUE", "value": "overriden-body-value-at-environment" } ] }

测试夹具集合 iteration-data-tests-coll.json 展示了这些 key 如何被消费：请求的endpoint写成<<URL>>，JSON body 写成{"<<BODY_KEY>>":"<<BODY_VALUE>>"}，每轮迭代时这些变量会被当前行（或环境）中的值替换。

用 iteration-count 重复执行集合

基本命令形式：

hopp test <collection.json> --iteration-count 3

--iteration-count <no_of_iterations>接受一个正整数，把整个集合重复执行 N 轮。e2e 测试 对成功行为的断言是：标准输出中依次出现Iteration: 1/3、Iteration: 2/3、Iteration: 3/3，且进程无错误退出。也就是说，多轮执行时每一轮都会打印形如Iteration: n/N的迭代头（具体打印逻辑见 collections.ts）。两个边界行为值得注意：

• --iteration-count 1时输出中不会出现Iteration: 1/1迭代头，集合按普通单次执行走；
• 取值非法会直接报INVALID_ARGUMENT：漏写数值（--iteration-count后无参数）、非数字（如NaN）、小于 1 的数（如-5）都会触发该错误码，源码中的错误信息为 "The value must be a positive integer"。

用 iteration-data 做数据驱动执行

hopp test <collection.json> --iteration-data ./data.csv

不提供--iteration-count时，迭代轮数会从 CSV 的数据行数推断（collections.ts 中resolvedIterationCount = iterationCount ?? iterationData?.length ?? 1），即上面 3 行数据的 CSV 会执行 3 轮，输出Iteration: 1/3到Iteration: 3/3。

结合环境文件时命令为：

hopp test <collection.json> --iteration-data ./data.csv -e ./envs.json

数据优先级规则（同样由 test.ts 与 collections.ts 实现，并有 e2e 用例断言）：

1. CSV 行数据优先于环境变量：当 CSV 与-e环境文件存在同名 key 时，使用 CSV 当前行的值；
2. 缺失项回退到环境：CSV 中为空的列不会覆盖环境文件里同名的值；
3. 每轮迭代开始时环境会重置为本轮初始状态，上一轮的变更不会带入下一轮；
4. 迭代数超过 CSV 行数时，最后一行数据会被重复使用（源码中取Math.min(count, iterationData.length - 1)行）。

同时提供两个选项时谁生效

如果命令里同时出现--iteration-data和--iteration-count，迭代次数以--iteration-count为准，而不是按 CSV 行数推断。e2e 测试明确验证了这一点：3 行数据的 CSV 加上--iteration-count 5时，输出中出现的是Iteration: 1/5到Iteration: 5/5。超出 CSV 行数的第 4、5 轮会沿用最后一行数据。

验证结果与错误判定

一次执行完成后，可以从三处判断结果：

• 迭代头：多轮执行时 stdout 中的Iteration: n/N行应覆盖全部轮次；
• 测试与报告：集合内请求的 test script（如夹具中的pw.expect(...)断言）执行结果会随报告输出，最终进程按结果以 0 或 1 退出，失败时 stderr 打印Exited with code 1；
• JUnit 报告（可选）：追加--reporter-junit [path]可将 JUnit 报告导出到指定路径，便于接入 CI。

CLI 参数层的错误码在 e2e 测试 中有完整覆盖，可作为排错对照：

限制

• --iteration-data只接受.csv扩展名的文件，其他格式（哪怕内容相同）会被直接拒绝；
• CSV 中空字符串的单元格会被忽略并回退到环境变量，全空行会被整体跳过；
• Hoppscotch CLI 目前处于 alpha 阶段，遵循 pre-1.0 语义化版本约定，选项行为在 1.0 之前可能随版本变化（见 README 的 Versioning 一节）。

如果需要把数据驱动执行的结果纳入 CI 流水线，下一步就是加上--reporter-junit生成 JUnit 报告；更多命令选项可参考 hoppscotch-cli README 的 Options 一节。

【免费下载链接】hoppscotchOpen-Source API Development Ecosystem • https://hoppscotch.io • Offline, On-Prem & Cloud • Web, Desktop & CLI • Open-Source Alternative to Postman, Insomnia项目地址: https://gitcode.com/GitHub_Trending/ho/hoppscotch