留给客户的 API 测试套件,几个文本文件就够了
Hurl 既能在你的笔记本上跑,也能放进客户的 CI 流水线,对方团队每一行都看得懂。
要点速览
- Hurl 是用 Rust 编写的轻量级二进制程序,读取描述 HTTP 请求的纯文本文件并执行
- --test 参数可并行运行多个文件并输出汇总;--report-junit 和 --report-html 可生成供 CI 使用的报告
- 对 FDE 来说,最大的价值是给客户留下一套对方团队能看懂、能修改的冒烟测试
在客户现场的第一周,你会调用对方的 API 上百次:获取 token、创建记录、查看状态。这些调用通常散落在你的终端历史或某个人的请求集合里。等到交接时,客户团队手里没有任何可以重新运行的东西。
Hurl 正好填补这个空白。据官网介绍,它是一款运行纯文本格式 HTTP 请求的命令行工具,是用 Rust 编写的轻量级二进制程序,以 libcurl 作为 HTTP 引擎。
该项目托管在 GitHub 的 Orange-OpenSource 组织下,采用 Apache-2.0 许可证。如果客户对开源软件有审批流程,尽早确认这个许可证是否在允许名单上。
对前线部署工程师(FDE)来说,价值不在速度,而在于一个文本文件可以提交到客户的代码仓库,在拉取请求(PR)里评审,并在对方的 CI 中用一条命令运行。
一个文件,覆盖一条完整业务流程
假设你在对接客户的任务编排 API,要验证的流程是:创建任务,拿到它的 id,再确认任务正在运行。用 Hurl 写成的 integration/create_job.hurl 大致如下:
# 创建新任务
POST https://{{host}}/api/jobs
Content-Type: application/json
{
"name": "nightly-sync"
}
HTTP 201
[Captures]
job_id: jsonpath "$.id"
# 检查刚创建的任务
GET https://{{host}}/api/jobs/{{job_id}}
HTTP 200
[Asserts]
jsonpath "$.state" == "running"
每个块是一个请求,加上预期的状态行。[Captures] 段从响应中取值,供后续请求复用。Hurl 的 README 用 XPath 举例,从 HTML 页面的 meta 标签中提取 CSRF token。[Asserts] 段检查返回内容,例如官方示例文档中用 JSONPath 比对某个 JSON 字段。
值得留意的是 {{host}}。文件里不写死预发或生产环境的地址,同一套测试就能在客户的每个环境上运行。
从笔记本到 CI,只差一个参数
调试时,正常运行文件即可看到最后一个响应。要做测试时,加上 --test 参数。按 Hurl 文档的说法,这种模式会增加运行汇总,不再打印最后一个响应,断言照常执行。多个 .hurl 文件也会并行运行,以缩短耗时。
官方的 CI/CD 集成指南给出了一条几乎拿来就能用的命令:
hurl --variable host="$1" --test integration/*.hurl
加上 --report-junit report.xml,大多数 CI 系统就能读取结果,显示哪些测试失败。Hurl 还能导出文本、TAP 和 HTML 报告;HTML 报告用 --report-html DIR 生成,不看日志的人也能看懂。
安装也不难。Hurl 可以通过 Homebrew 和 Cargo 安装,还有官方 Docker 镜像 ghcr.io/orange-opensource/hurl。在严格管控构建机的公司,用 Docker 镜像运行通常是所需权限最少的方式。
放进客户流水线之前的两个坑
第一个坑来自并行执行本身。如果文件 A 创建的数据是文件 B 需要的,两者可能同时运行,测试就会时好时坏。稳妥的规则是让每个文件自成一体:凡是链式请求的流程都放在同一个文件里,通过捕获传递数据。
第二个坑是 HTML 报告。文档写得很清楚:新结果会追加到已有报告中。如果 CI runner 复用工作目录,每次运行前要删除报告目录,否则读者会把今天的结果和昨天的混在一起。
还要清楚这个工具的边界。Hurl 从外部检查 HTTP 行为。它能告诉你 API 返回错了,但要弄清原因,仍然得去读客户的日志和代码。
先学什么
按顺序掌握三件事:请求块及其状态行的结构,如何捕获值来串联请求,以及用于断言的 JSONPath 语法。有了这三样,大多数 REST API 的冒烟测试都能写出来。之后再学 --variable、--test 和各个报告参数。
到了客户现场,第一件事是写一个文件,检查集成中最重要的那个接口,提交到对方仓库,并在第一次演示前在 CI 里跑起来。此后每发现一个 bug,都配上一个能复现它的 .hurl 文件。
先故意让测试失败,再去信任它
把测试套件交给客户之前,值得做一个小练习:在上面的示例文件里,把 "running" 改成一个肯定错误的值,比如 "no-such-state"。然后运行 hurl --variable host=... --test --report-junit report.xml integration/*.hurl。
你要检查三个地方。运行结束时的汇总应显示 create_job.hurl 失败,其他文件仍然通过。report.xml 文件应记录同一个失败;推送到一个试用 CI 任务后,流水线应该变红。
只要其中任何一处没有反映出错误,这套测试就还不可信,哪怕今天全是绿的。把断言改回正确的值,再跑一次,亲眼看到它变红又变绿之后再交接。
从职业角度看,作品集仓库里的一个 .hurl 文件目录,能向招聘方证明你会测试不是自己写的 API。当 FDE 岗位描述提到“API integration”或“CI/CD”时,在简历上写一个具体成果,比如搭建了一套在客户流水线中运行的冒烟测试,而不是只罗列工具名称。
离开项目后,集成代码很可能会被重写。而写明 API 必须返回什么的那些文本文件,往往比代码活得更久。
这篇文章对你有帮助吗?
感谢你的反馈!