# 留给客户的 API 测试套件，几个文本文件就够了

> Hurl 既能在你的笔记本上跑，也能放进客户的 CI 流水线，对方团队每一行都看得懂。

原文: https://fdetimes.net/zh/tools/hurl-api-tests-for-client-handover/

在客户现场的第一周，你会调用对方的 API 上百次：获取 token、创建记录、查看状态。这些调用通常散落在你的终端历史或某个人的请求集合里。等到交接时，客户团队手里没有任何可以重新运行的东西。

Hurl 正好填补这个空白。据官网介绍，它是一款运行纯文本格式 HTTP 请求的命令行工具，是用 Rust 编写的轻量级二进制程序，以 libcurl 作为 HTTP 引擎。

该项目托管在 GitHub 的 Orange-OpenSource 组织下，采用 Apache-2.0 许可证。如果客户对开源软件有审批流程，尽早确认这个许可证是否在允许名单上。

对前线部署工程师（FDE）来说，价值不在速度，而在于一个文本文件可以提交到客户的代码仓库，在拉取请求（PR）里评审，并在对方的 CI 中用一条命令运行。

## 一个文件，覆盖一条完整业务流程

假设你在对接客户的任务编排 API，要验证的流程是：创建任务，拿到它的 id，再确认任务正在运行。用 Hurl 写成的 `integration/create_job.hurl` 大致如下：

```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 集成指南给出了一条几乎拿来就能用的命令：

```bash
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 必须返回什么的那些文本文件，往往比代码活得更久。

**本周动手试试:**

- 用 Homebrew、Cargo 或官方 Docker 镜像安装 Hurl，然后写一个 .hurl 文件，调用你正在对接的 API 的健康检查接口
- 再写一个串联两个请求的文件：从第一个请求中捕获一个 id，然后在第二个请求中断言状态
- 用 --test 和 --report-junit 运行整个目录，再把这条命令放进一个试用 CI 任务

## 信源

- [Hurl - Run and Test HTTP Requests](https://hurl.dev/)

- [Orange-OpenSource/hurl: Hurl, run and test HTTP requests with plain text](https://github.com/Orange-OpenSource/hurl)

- [Running Tests - Hurl Documentation](https://hurl.dev/docs/running-tests.html)

- [CI/CD Integration - Hurl Tutorial](https://hurl.dev/docs/tutorial/ci-cd-integration.html)

- [hurl 6.0.0 README (docs.rs)](https://docs.rs/crate/hurl/6.0.0/source/README.md)

- [Samples - Hurl Documentation](https://hurl.dev/docs/samples.html)

- [Installation - Hurl Documentation](https://hurl.dev/docs/installation.html)
