This commit is contained in:
777
.claude/skills/hurl-test/SKILL.md
Normal file
777
.claude/skills/hurl-test/SKILL.md
Normal file
@@ -0,0 +1,777 @@
|
||||
---
|
||||
name: hurl-test
|
||||
description: Hurl 接口测试生成器。用户描述要测试的接口或业务流程，自动探索代码、确认需求、生成完整的 .hurl 测试文件（含 DTO 驱动的字段完整性断言）。触发词：测试、hurl、写测试、接口测试。
|
||||
---
|
||||
|
||||
# Hurl 接口测试生成器
|
||||
|
||||
**用户描述要测试什么，你来读代码、问确认、生成 .hurl 文件。**
|
||||
|
||||
适用于任何后端项目（Go / Python / Node / Java 等），不预设框架和目录结构。
|
||||
|
||||
---
|
||||
|
||||
## 触发条件
|
||||
|
||||
以下情况必须使用本 Skill：
|
||||
- 用户说"测试 XX 接口"、"写 hurl 测试"、"给 XX 加测试"
|
||||
- 用户说"测试 XX 流程"、"测试 XX 的业务逻辑"
|
||||
- 用户说"验证 XX 接口的字段"、"测试接口契约"
|
||||
- 用户提到 hurl、.hurl、接口测试、集成测试、冒烟测试
|
||||
|
||||
---
|
||||
|
||||
## 四阶段工作流（必须按顺序执行）
|
||||
|
||||
```
|
||||
Phase 1: 探索 → Phase 2: 确认 → Phase 3: 生成 → Phase 4: 验证
|
||||
读代码搞清楚 展示给用户确认 输出 .hurl 文件 语法检查 + 试跑
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: 探索（Explore）
|
||||
|
||||
**目标：读代码，搞清楚项目约定 + 涉及的接口 + 字段 + 依赖。**
|
||||
|
||||
#### 1.1 项目画像（首次使用时必须执行，后续复用）
|
||||
|
||||
首次为项目生成 Hurl 测试时，先回答以下问题（通过读代码，不要猜）：
|
||||
|
||||
| 问题 | 怎么找 |
|
||||
|------|--------|
|
||||
| **语言/框架** | 看 go.mod / package.json / requirements.txt / pom.xml |
|
||||
| **路由注册在哪** | 搜索 `router`、`app.Get`、`@GetMapping`、`@app.route` 等关键词 |
|
||||
| **请求/响应 schema 定义在哪** | 搜索 DTO / schema / serializer / model 目录，看 json tag 或装饰器 |
|
||||
| **统一响应格式是什么** | 找 response helper 文件（如 `response.go`、`response.py`），记录 JSON 结构 |
|
||||
| **认证方式是什么** | 找 auth middleware，确定是 Bearer Token / Cookie / API Key / Basic Auth |
|
||||
| **登录接口是什么** | 找登录 handler，记录路径、请求体、响应中 token 的位置 |
|
||||
| **分页格式是什么** | 找列表接口的响应结构，记录 items/total/page 等字段名 |
|
||||
| **已有 hurl 测试吗** | 搜索 `*.hurl` 文件，复用已有的约定 |
|
||||
|
||||
将画像结果**写入 `tests/hurl/.project-profile.md` 文件持久化保存**。
|
||||
|
||||
#### 画像持久化（关键机制）
|
||||
|
||||
**首次使用时**：完成 1.1 探索后，将画像写入 `tests/hurl/.project-profile.md`，格式如下：
|
||||
|
||||
```markdown
|
||||
# 项目画像（Hurl 测试自动生成用）
|
||||
<!-- 由 hurl-test skill 自动生成，请勿手动修改 -->
|
||||
<!-- 如需刷新，删除此文件后重新运行 skill -->
|
||||
|
||||
## 技术栈
|
||||
- 语言: Go 1.25
|
||||
- 框架: Fiber v2
|
||||
- ORM: GORM
|
||||
|
||||
## 路由定义位置
|
||||
- 路由注册入口: internal/routes/routes.go
|
||||
- 按模块拆分: internal/routes/{module}.go
|
||||
- 路由注册函数: Register(router, doc, basePath, method, path, handler, spec)
|
||||
|
||||
## Schema 定义位置
|
||||
- DTO 目录: internal/model/dto/
|
||||
- 命名规则: {module}_dto.go
|
||||
- 字段标签: json / validate / description
|
||||
|
||||
## 统一响应格式
|
||||
{code: int, msg: string, data: any, timestamp: string(RFC3339)}
|
||||
- 成功: code=0, msg="success"
|
||||
- 错误: code!=0
|
||||
|
||||
## 分页格式
|
||||
{items: [], total: int, page: int, size: int}
|
||||
- 包裹在 data 字段内: $.data.items / $.data.total
|
||||
|
||||
## 认证方式
|
||||
- 后台: POST /api/auth/admin-login → $.data.access_token → Authorization: Bearer {token}
|
||||
- C端: JWT → Authorization: Bearer {token}
|
||||
|
||||
## 默认测试账号
|
||||
- 用户名: admin
|
||||
- 密码: Admin@123456
|
||||
|
||||
## 服务端口
|
||||
- 默认: 3000
|
||||
```
|
||||
|
||||
**后续使用时**：检查 `tests/hurl/.project-profile.md` 是否存在：
|
||||
- **存在** → 直接读取，跳过 1.1 的探索步骤，节省时间
|
||||
- **不存在** → 执行 1.1 完整探索，然后生成此文件
|
||||
- **用户说"刷新画像"** → 删除旧文件，重新执行 1.1
|
||||
|
||||
#### 1.2 找接口定义
|
||||
|
||||
根据用户要测的模块，定位路由注册代码，提取：
|
||||
|
||||
- **HTTP 方法**（GET / POST / PUT / DELETE / PATCH）
|
||||
- **路由路径**（含路径参数格式，如 `/users/:id` 或 `/users/{id}`）
|
||||
- **接口说明**（注释、Summary、装饰器描述）
|
||||
- **是否需要认证**
|
||||
- **请求 schema 类型名**（Input / Request DTO）
|
||||
- **响应 schema 类型名**（Output / Response DTO）
|
||||
|
||||
#### 1.3 读 schema 定义（DTO / struct / class / type）
|
||||
|
||||
定位请求和响应的 schema 定义文件，提取每个字段的：
|
||||
|
||||
- **字段名**：JSON 序列化后的名称（json tag / @JsonProperty / serializer field）
|
||||
- **语言类型**：string / int / bool / 数组 / 嵌套对象 / 可空等
|
||||
- **是否必填**：validate tag / required 装饰器 / 非空标注
|
||||
- **是否可空**：指针类型 / Optional / nullable
|
||||
- **是否参与序列化**：`json:"-"` / @JsonIgnore / exclude
|
||||
- **是否 omitempty**：`json:",omitempty"` / 条件序列化
|
||||
- **字段描述**：description tag / docstring / 注释
|
||||
|
||||
#### 1.4 识别业务依赖
|
||||
|
||||
读 service / business logic 层，识别：
|
||||
|
||||
- 创建操作需要哪些前置数据（如创建订单需要先有商品和用户）
|
||||
- 是否有唯一性约束（如用户名不能重复）
|
||||
- 是否依赖外部服务（支付网关、短信、OAuth 等）
|
||||
- 业务流转逻辑（状态机、级联操作）
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: 确认（Clarify）
|
||||
|
||||
**目标：向用户展示发现的内容，确认模糊点。不要闷头生成。**
|
||||
|
||||
#### 2.1 必须展示的内容
|
||||
|
||||
```
|
||||
我梳理了相关代码，发现以下信息：
|
||||
|
||||
📋 涉及接口：
|
||||
- [方法] [路径] - [说明]（认证: 是/否）
|
||||
- ...
|
||||
|
||||
📦 响应字段（基于 {SchemaName}）：
|
||||
- [字段名]: [类型] - [说明]
|
||||
- ...（共 N 个字段，将全部生成断言）
|
||||
|
||||
🔗 依赖关系：
|
||||
- [创建 X 需要先创建 Y]
|
||||
- ...
|
||||
|
||||
⚠️ 特殊情况：
|
||||
- [涉及外部服务 / 文件上传 / 特殊认证等]
|
||||
```
|
||||
|
||||
#### 2.2 按需确认（只问有歧义的）
|
||||
|
||||
| 场景 | 要问的 |
|
||||
|------|--------|
|
||||
| 流程范围不明确 | "要测到哪一步？" |
|
||||
| 多种用户角色 | "用哪种身份测？" |
|
||||
| 是否测异常 | "需要包含异常 case 吗？（参数校验失败、权限不足等）" |
|
||||
| 是否测数据隔离 | "需要验证不同用户间数据不可见吗？" |
|
||||
| 涉及第三方 | "XX 部分怎么处理？绕过 / 模拟回调 / 跳过？" |
|
||||
| 前置数据来源 | "XX 依赖数据是通过 API 创建还是假设已存在？" |
|
||||
|
||||
**如果用户说"越完整越好"或"都要"→ 默认全部包含，不再追问。**
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: 生成（Generate）
|
||||
|
||||
**目标：生成完整的 .hurl 文件，字段断言基于 schema 代码，不能编造。**
|
||||
|
||||
#### 3.1 文件头注释
|
||||
|
||||
```hurl
|
||||
# ============================================================
|
||||
# 测试：{测试名称}
|
||||
# 生成时间：{日期}
|
||||
# 涉及模块：{module1, module2, ...}
|
||||
# 涉及接口：{N} 个
|
||||
# 断言数量：{N} 条
|
||||
# 前置条件：{服务运行 + 必要的前置条件}
|
||||
# ============================================================
|
||||
# 流程：
|
||||
# 1. {步骤描述}
|
||||
# 2. {步骤描述}
|
||||
# ...
|
||||
# ============================================================
|
||||
```
|
||||
|
||||
#### 3.2 请求生成规则
|
||||
|
||||
**认证**：
|
||||
|
||||
- 根据 Phase 1 画像中的登录接口和 token 位置生成
|
||||
- token 必须通过 `[Captures]` 捕获，后续请求引用
|
||||
- 如果是 Cookie 认证，用 `[Cookies]` 或 cookie capture
|
||||
|
||||
**CRUD 标准模式**：
|
||||
|
||||
| 操作 | 生成要求 |
|
||||
|------|---------|
|
||||
| **创建（POST）** | capture 返回的 ID；唯一字段用 `{{newUuid}}` 防冲突 |
|
||||
| **查询详情（GET）** | **逐字段断言**（类型 + 值，见 3.3） |
|
||||
| **查询列表（GET）** | 分页结构断言 + items[0] 逐字段断言 |
|
||||
| **修改（PUT/PATCH）** | 修改后**紧跟一个 GET 验证修改生效** |
|
||||
| **删除（DELETE）** | 删除后**紧跟一个 GET 验证已删除** |
|
||||
|
||||
**业务流程模式**：
|
||||
|
||||
- 按用户描述的流程顺序编排请求
|
||||
- 上一步的输出（ID、状态等）通过 `[Captures]` 传给下一步
|
||||
- 关键步骤加中间状态验证（如创建订单后验证状态为"待支付"）
|
||||
|
||||
#### 3.3 schema 到断言的映射
|
||||
|
||||
读到 schema 字段后，按以下规则生成 jsonpath 断言：
|
||||
|
||||
**通用类型映射（所有语言）**：
|
||||
|
||||
| Schema 类型特征 | Hurl 断言 |
|
||||
|----------------|-----------|
|
||||
| 字符串（string / str / String） | `isString` |
|
||||
| 整数（int / integer / long / Int） | `isInteger` |
|
||||
| 浮点（float / double / decimal / Float） | `isNumber` |
|
||||
| 布尔（bool / boolean / Boolean） | `isBoolean` |
|
||||
| 数组 / 列表（[] / List / Array） | `isList` |
|
||||
| 嵌套对象（struct / class / dict / object） | `isObject`，并递归检查子字段 |
|
||||
| 可空类型（指针 / Optional / nullable） | `exists`（不强制类型，因为可能是 null） |
|
||||
| 不参与序列化（json:"-" / @JsonIgnore / exclude=True） | **跳过，不生成断言** |
|
||||
| 条件序列化（omitempty / if not None） | `exists` 或不生成（取决于场景） |
|
||||
|
||||
**Go 特定映射**：
|
||||
|
||||
| Go 类型 | Hurl 断言 |
|
||||
|---------|-----------|
|
||||
| `string` | `isString` |
|
||||
| `int`, `int8/16/32/64`, `uint`, `uint8/16/32/64` | `isInteger` |
|
||||
| `float32`, `float64` | `isNumber` |
|
||||
| `bool` | `isBoolean` |
|
||||
| `[]T` | `isList` |
|
||||
| `*string`, `*int`, `*uint` 等指针 | `exists` |
|
||||
| `time.Time` | `isString`（通常序列化为字符串） |
|
||||
| `map[string]any` | `isObject` |
|
||||
|
||||
**Python 特定映射（Pydantic / Django / FastAPI）**：
|
||||
|
||||
| Python 类型 | Hurl 断言 |
|
||||
|------------|-----------|
|
||||
| `str` | `isString` |
|
||||
| `int` | `isInteger` |
|
||||
| `float`, `Decimal` | `isNumber` |
|
||||
| `bool` | `isBoolean` |
|
||||
| `list[T]`, `List[T]` | `isList` |
|
||||
| `Optional[T]`, `T | None` | `exists` |
|
||||
| `dict`, `Dict` | `isObject` |
|
||||
| `datetime`, `date` | `isString` |
|
||||
|
||||
**TypeScript/JavaScript 特定映射**：
|
||||
|
||||
| TS/JS 类型 | Hurl 断言 |
|
||||
|-----------|-----------|
|
||||
| `string` | `isString` |
|
||||
| `number`（整数上下文） | `isInteger` |
|
||||
| `number`（通用） | `isNumber` |
|
||||
| `boolean` | `isBoolean` |
|
||||
| `T[]`, `Array<T>` | `isList` |
|
||||
| `T \| null`, `T \| undefined` | `exists` |
|
||||
| `object`, `Record<>` | `isObject` |
|
||||
| `Date` | `isString` |
|
||||
|
||||
**Java 特定映射**：
|
||||
|
||||
| Java 类型 | Hurl 断言 |
|
||||
|----------|-----------|
|
||||
| `String` | `isString` |
|
||||
| `Integer`, `Long`, `int`, `long` | `isInteger` |
|
||||
| `Double`, `Float`, `BigDecimal` | `isNumber` |
|
||||
| `Boolean`, `boolean` | `isBoolean` |
|
||||
| `List<T>` | `isList` |
|
||||
| `@Nullable`, `Optional<T>` | `exists` |
|
||||
| `Map<K,V>` | `isObject` |
|
||||
| `LocalDateTime`, `Instant` | `isString` |
|
||||
|
||||
#### 3.4 统一响应格式断言
|
||||
|
||||
根据 Phase 1 画像中发现的统一响应格式，为**每个成功响应**添加格式断言。
|
||||
|
||||
示例：如果项目的统一格式是 `{code, msg, data, timestamp}`：
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
jsonpath "$.code" == 0
|
||||
jsonpath "$.msg" == "success"
|
||||
jsonpath "$.timestamp" isIsoDate
|
||||
```
|
||||
|
||||
示例：如果项目的格式是 `{status, message, result}`：
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
jsonpath "$.status" == "ok"
|
||||
jsonpath "$.message" isString
|
||||
```
|
||||
|
||||
示例：如果项目无统一包装，直接返回数据：
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
# 直接断言业务字段
|
||||
jsonpath "$.id" isInteger
|
||||
jsonpath "$.name" isString
|
||||
```
|
||||
|
||||
**不要假设响应格式，必须从代码中确认。**
|
||||
|
||||
#### 3.5 分页断言
|
||||
|
||||
根据 Phase 1 画像中发现的分页结构生成。
|
||||
|
||||
示例：如果是 `{items, total, page, size}` 格式：
|
||||
|
||||
```hurl
|
||||
jsonpath "$.data.items" isList
|
||||
jsonpath "$.data.total" isInteger
|
||||
jsonpath "$.data.total" >= 1
|
||||
jsonpath "$.data.page" isInteger
|
||||
jsonpath "$.data.size" isInteger
|
||||
# items 内元素逐字段断言
|
||||
jsonpath "$.data.items[0].{field}" {type_assert}
|
||||
```
|
||||
|
||||
示例：如果是 `{results, count, next, previous}` 格式（Django 风格）：
|
||||
|
||||
```hurl
|
||||
jsonpath "$.results" isList
|
||||
jsonpath "$.count" isInteger
|
||||
jsonpath "$.count" >= 1
|
||||
# results 内元素逐字段断言
|
||||
jsonpath "$.results[0].{field}" {type_assert}
|
||||
```
|
||||
|
||||
**根据实际代码调整字段名，不硬编码。**
|
||||
|
||||
#### 3.6 异常 Case 模板
|
||||
|
||||
**参数校验失败**：
|
||||
|
||||
```hurl
|
||||
# ── 异常：参数校验失败 ──
|
||||
POST {{base_url}}/{path}
|
||||
Authorization: Bearer {{token}}
|
||||
Content-Type: application/json
|
||||
{
|
||||
"required_field": ""
|
||||
}
|
||||
HTTP {expected_error_status}
|
||||
[Asserts]
|
||||
# 断言错误响应格式（根据项目约定调整）
|
||||
```
|
||||
|
||||
> HTTP 状态码根据项目实际返回确定：有的项目错误也返回 200 + 业务错误码，有的返回 400/422。
|
||||
|
||||
**未认证访问**：
|
||||
|
||||
```hurl
|
||||
# ── 异常：未认证访问 ──
|
||||
GET {{base_url}}/{protected_path}
|
||||
HTTP {expected_unauth_status}
|
||||
```
|
||||
|
||||
**越权访问**（如果用户要求）：
|
||||
|
||||
```hurl
|
||||
# ── 异常：用户 B 不能访问用户 A 的资源 ──
|
||||
GET {{base_url}}/{path}/{{user_a_resource_id}}
|
||||
Authorization: Bearer {{user_b_token}}
|
||||
HTTP {expected_forbidden_status}
|
||||
```
|
||||
|
||||
#### 3.7 特殊场景处理
|
||||
|
||||
| 场景 | 处理策略 |
|
||||
|------|---------|
|
||||
| **短信/邮件验证码** | 建议服务端加 test_mode 开关，固定验证码写入 env 文件；注释提醒用户 |
|
||||
| **第三方支付** | 优先用项目内部支付方式（如钱包支付）；如需测回调，直接 POST 回调接口模拟 |
|
||||
| **OAuth 登录（微信/Google/GitHub）** | 建议服务端加 test_mode 支持直接传 openid/email；注释提醒用户 |
|
||||
| **文件上传** | 用 Hurl 的 `[Multipart]` 语法 + testdata 目录下的样本文件 |
|
||||
| **外部 API 依赖** | 只测参数校验和错误响应格式，不断言业务结果；注释说明依赖 |
|
||||
| **WebSocket** | Hurl 不支持，注释说明跳过 |
|
||||
| **异步任务结果** | 用 Hurl 的 `retry` + `retry-interval` 轮询直到状态变更 |
|
||||
|
||||
异步轮询示例：
|
||||
|
||||
```hurl
|
||||
# 等待异步任务完成（最多重试 10 次，间隔 500ms）
|
||||
GET {{base_url}}/{path}/{{task_id}}
|
||||
Authorization: Bearer {{token}}
|
||||
[Options]
|
||||
retry: 10
|
||||
retry-interval: 500ms
|
||||
HTTP 200
|
||||
[Asserts]
|
||||
jsonpath "$.data.status" == "completed"
|
||||
```
|
||||
|
||||
#### 3.8 文件输出
|
||||
|
||||
**目录结构**（首次使用时创建，如不存在）：
|
||||
|
||||
```
|
||||
tests/hurl/
|
||||
├── env/
|
||||
│ └── dev.env # 环境变量
|
||||
├── testdata/ # 测试用的样本文件
|
||||
├── flows/ # 业务流程测试
|
||||
├── modules/ # 按模块的接口测试
|
||||
│ └── {module}/
|
||||
│ └── 01-crud.hurl
|
||||
├── negative/ # 异常/边界测试
|
||||
├── contract/ # 接口契约验证
|
||||
└── Makefile # 快捷命令
|
||||
```
|
||||
|
||||
文件放置规则：
|
||||
|
||||
| 用户描述 | 输出路径 |
|
||||
|---------|---------|
|
||||
| 测试 XX 流程 / 业务流程 | `tests/hurl/flows/{flow-name}.hurl` |
|
||||
| 测试 XX 模块的 CRUD / 接口 | `tests/hurl/modules/{module}/01-crud.hurl` |
|
||||
| 测试异常/边界/权限 | `tests/hurl/negative/{name}.hurl` |
|
||||
| 测试接口契约/字段对齐 | `tests/hurl/contract/{name}.hurl` |
|
||||
|
||||
**如果项目已有 hurl 测试目录结构，沿用已有约定，不要另起炉灶。**
|
||||
|
||||
#### 3.9 env 和 Makefile
|
||||
|
||||
**env/dev.env**（首次创建时生成，内容基于 Phase 1 画像）：
|
||||
|
||||
```properties
|
||||
# 服务地址
|
||||
base_url=http://localhost:{port}
|
||||
|
||||
# 认证信息（根据项目实际填写）
|
||||
admin_username={默认用户名}
|
||||
admin_password={默认密码}
|
||||
|
||||
# 测试模式变量（如果有特殊场景）
|
||||
# test_sms_code=888888
|
||||
# test_openid=test_openid_001
|
||||
```
|
||||
|
||||
**Makefile**（首次创建时生成）：
|
||||
|
||||
```makefile
|
||||
SHELL := /bin/bash
|
||||
ENV ?= dev
|
||||
HURL_OPTS := --variables-file env/$(ENV).env --test
|
||||
|
||||
.PHONY: test test-flows test-modules test-negative report
|
||||
|
||||
test: ## 运行所有测试
|
||||
hurl $(HURL_OPTS) .
|
||||
|
||||
test-flows: ## 运行业务流程测试
|
||||
hurl $(HURL_OPTS) flows/
|
||||
|
||||
test-modules: ## 运行模块接口测试
|
||||
hurl $(HURL_OPTS) modules/
|
||||
|
||||
test-negative: ## 运行异常测试
|
||||
hurl $(HURL_OPTS) negative/
|
||||
|
||||
report: ## 生成 HTML 报告
|
||||
hurl $(HURL_OPTS) --report-html build/report/ .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: 验证（Verify）
|
||||
|
||||
**目标：确保生成的 .hurl 文件语法正确、可运行。**
|
||||
|
||||
#### 4.1 语法自检
|
||||
|
||||
- [ ] 每个请求之间有空行分隔
|
||||
- [ ] `[Captures]` 和 `[Asserts]` 拼写正确（大小写敏感）
|
||||
- [ ] 所有 `{{变量}}` 引用都有来源（env 文件定义 或 上游 `[Captures]`）
|
||||
- [ ] JSON body 无尾逗号、格式正确
|
||||
- [ ] `HTTP {status}` 在请求之后、`[Captures]` / `[Asserts]` 之前
|
||||
- [ ] 请求和断言之间没有多余空行（`HTTP` 行必须紧跟请求）
|
||||
- [ ] 文件上传路径相对于 hurl 文件位置正确
|
||||
|
||||
#### 4.2 运行测试
|
||||
|
||||
```bash
|
||||
hurl --variables-file tests/hurl/env/dev.env --test tests/hurl/{生成的文件}
|
||||
```
|
||||
|
||||
- 服务在跑 → 执行，如有失败分析修正
|
||||
- 服务没跑 → 跳过，告知用户手动验证命令
|
||||
|
||||
---
|
||||
|
||||
## 红线规则
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| **不跳过 Phase 1** | 必须读代码确认接口路径和字段，不能凭记忆或猜测 |
|
||||
| **不跳过 Phase 2** | 必须向用户展示发现的接口和字段，确认后再生成 |
|
||||
| **不编造字段** | 所有断言的字段名必须来自实际 schema 代码 |
|
||||
| **不编造路径** | 所有接口路径必须来自实际路由代码 |
|
||||
| **不遗漏字段** | schema 中每个参与序列化的字段都必须有对应断言 |
|
||||
| **不硬编码 ID** | 所有依赖的 ID 通过 `[Captures]` 从上游请求获取 |
|
||||
| **不假设响应格式** | 统一响应结构必须从代码中确认，不同项目格式不同 |
|
||||
| **唯一值防冲突** | 创建类请求的唯一字段使用 `{{newUuid}}` 或 `{{newDate}}` |
|
||||
| **自给自足** | 每个 .hurl 文件自己创建测试数据，不依赖外部数据准备 |
|
||||
|
||||
---
|
||||
|
||||
## AI 助手检查清单
|
||||
|
||||
生成 .hurl 文件后自检：
|
||||
|
||||
1. ✅ 文件头注释包含流程描述和前置条件
|
||||
2. ✅ 认证步骤正确 capture 了 token / cookie
|
||||
3. ✅ 所有依赖数据通过 API 链式创建（自给自足）
|
||||
4. ✅ 每个成功响应断言了项目的统一响应格式
|
||||
5. ✅ 查询详情接口**逐字段断言**（类型 + 值，基于 schema）
|
||||
6. ✅ 分页接口断言了分页结构 + 第一条记录的字段
|
||||
7. ✅ 修改操作后紧跟 GET 验证修改生效
|
||||
8. ✅ 删除操作后紧跟 GET 验证已删除
|
||||
9. ✅ 唯一字段使用了 `{{newUuid}}`
|
||||
10. ✅ `{{变量}}` 引用无悬空（都有 env 或 capture 来源）
|
||||
11. ✅ 文件放在了正确的目录位置
|
||||
12. ✅ 特殊场景有明确的处理策略和注释提醒
|
||||
|
||||
---
|
||||
|
||||
## 附录：Hurl 语法速查
|
||||
|
||||
**生成 .hurl 文件时必须参照本速查，不可凭记忆编造语法。**
|
||||
|
||||
### 文件结构
|
||||
|
||||
一个 .hurl 文件由多个 entry 组成，每个 entry = 请求 + 可选响应：
|
||||
|
||||
```
|
||||
请求1
|
||||
响应1（可选）
|
||||
|
||||
请求2
|
||||
响应2（可选）
|
||||
```
|
||||
|
||||
entry 之间用空行分隔。
|
||||
|
||||
### 请求格式
|
||||
|
||||
```hurl
|
||||
METHOD URL
|
||||
Header1: value1
|
||||
Header2: value2
|
||||
[Options]
|
||||
key: value
|
||||
[Query]
|
||||
param1: value1
|
||||
[Form]
|
||||
field1: value1
|
||||
[Multipart]
|
||||
file1: file,path/to/file;
|
||||
[BasicAuth]
|
||||
username: password
|
||||
[Cookies]
|
||||
name: value
|
||||
BODY（JSON / XML / multiline string / file）
|
||||
```
|
||||
|
||||
**规则**：
|
||||
- Method + URL 是第一行，必须
|
||||
- Headers 紧跟 URL 之后（无 section 标记）
|
||||
- Sections（`[Query]`、`[Form]`、`[Options]` 等）顺序任意
|
||||
- Body 必须在最后
|
||||
- JSON body 直接写 `{ }` 即可，自动设置 Content-Type: application/json
|
||||
|
||||
### 响应格式
|
||||
|
||||
```hurl
|
||||
HTTP {status_code}
|
||||
Header1: expected_value1
|
||||
[Captures]
|
||||
var_name: jsonpath "$.path"
|
||||
[Asserts]
|
||||
jsonpath "$.field" == "value"
|
||||
```
|
||||
|
||||
**规则**：
|
||||
- `HTTP {status}` 紧跟请求之后（中间不能有空行）
|
||||
- `HTTP *` 表示不检查状态码
|
||||
- Headers 检查紧跟 HTTP 行之后
|
||||
- `[Captures]` 和 `[Asserts]` 顺序任意
|
||||
|
||||
### 变量和模板
|
||||
|
||||
```hurl
|
||||
# 引用变量（从 env 文件、命令行或上游 capture 获取）
|
||||
GET {{base_url}}/api/users/{{user_id}}
|
||||
|
||||
# 内置函数
|
||||
POST {{base_url}}/api/users
|
||||
{
|
||||
"email": "{{newUuid}}@test.com",
|
||||
"created_at": "{{newDate}}"
|
||||
}
|
||||
```
|
||||
|
||||
可用函数：
|
||||
- `{{newUuid}}` — 生成 UUID v4
|
||||
- `{{newDate}}` — 生成 RFC 3339 UTC 时间戳
|
||||
|
||||
### Capture 语法
|
||||
|
||||
```hurl
|
||||
[Captures]
|
||||
# JSONPath
|
||||
token: jsonpath "$.data.access_token"
|
||||
user_id: jsonpath "$.data.id"
|
||||
first_item: jsonpath "$.items[0].name"
|
||||
|
||||
# Header
|
||||
location: header "Location"
|
||||
|
||||
# Cookie
|
||||
session: cookie "SESSIONID"
|
||||
|
||||
# Body（整个响应体作为字符串）
|
||||
full_body: body
|
||||
|
||||
# Status code
|
||||
code: status
|
||||
|
||||
# 正则表达式
|
||||
csrf: regex "name=\"csrf\" value=\"([^\"]+)\""
|
||||
|
||||
# 响应时间（毫秒）
|
||||
response_time: duration
|
||||
```
|
||||
|
||||
### Assert 语法
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
# ── 状态码 ──
|
||||
status == 200
|
||||
status >= 200
|
||||
status < 300
|
||||
|
||||
# ── JSONPath 断言 ──
|
||||
jsonpath "$.name" == "Alice" # 等于
|
||||
jsonpath "$.name" != "Bob" # 不等于
|
||||
jsonpath "$.age" > 18 # 大于
|
||||
jsonpath "$.age" >= 18 # 大于等于
|
||||
jsonpath "$.count" < 100 # 小于
|
||||
jsonpath "$.items" count == 5 # 集合长度
|
||||
jsonpath "$.name" startsWith "Al" # 前缀
|
||||
jsonpath "$.name" endsWith "ce" # 后缀
|
||||
jsonpath "$.name" contains "lic" # 包含
|
||||
jsonpath "$.date" matches /\\d{4}-\\d{2}-\\d{2}/ # 正则
|
||||
|
||||
# ── 类型断言 ──
|
||||
jsonpath "$.name" isString
|
||||
jsonpath "$.age" isInteger
|
||||
jsonpath "$.score" isFloat
|
||||
jsonpath "$.count" isNumber # 整数或浮点
|
||||
jsonpath "$.active" isBoolean
|
||||
jsonpath "$.items" isList
|
||||
jsonpath "$.meta" isObject
|
||||
jsonpath "$.id" isUuid
|
||||
jsonpath "$.created_at" isIsoDate # RFC 3339 格式
|
||||
jsonpath "$.field" isEmpty # 空集合
|
||||
|
||||
# ── 存在性 ──
|
||||
jsonpath "$.field" exists
|
||||
jsonpath "$.field" not exists
|
||||
|
||||
# ── 否定 ──
|
||||
jsonpath "$.name" not contains "Bob"
|
||||
jsonpath "$.status" not == "deleted"
|
||||
|
||||
# ── Header 断言 ──
|
||||
header "Content-Type" contains "application/json"
|
||||
header "X-Request-Id" exists
|
||||
|
||||
# ── 性能 ──
|
||||
duration < 1000 # 响应时间（毫秒）
|
||||
|
||||
# ── Body 断言 ──
|
||||
body contains "Hello"
|
||||
bytes count == 1024
|
||||
```
|
||||
|
||||
### Options（逐请求配置）
|
||||
|
||||
```hurl
|
||||
GET {{base_url}}/api/task/{{task_id}}
|
||||
[Options]
|
||||
retry: 10 # 最大重试次数（-1 = 无限）
|
||||
retry-interval: 500ms # 重试间隔
|
||||
delay: 2s # 请求前等待
|
||||
location: true # 跟随重定向
|
||||
insecure: true # 允许不安全 SSL
|
||||
verbose: true # 输出详细日志
|
||||
very-verbose: true # 输出更详细日志
|
||||
skip: true # 跳过此请求
|
||||
variable: key=value # 定义变量
|
||||
HTTP 200
|
||||
```
|
||||
|
||||
### Multipart 文件上传
|
||||
|
||||
```hurl
|
||||
POST {{base_url}}/api/upload
|
||||
[Multipart]
|
||||
file: file,testdata/sample.xlsx;
|
||||
field1: value1
|
||||
# 指定 Content-Type
|
||||
file2: file,testdata/data.bin; application/octet-stream
|
||||
```
|
||||
|
||||
### 运行命令
|
||||
|
||||
```bash
|
||||
# 运行单个文件
|
||||
hurl --test file.hurl
|
||||
|
||||
# 带变量文件
|
||||
hurl --variables-file env/dev.env --test file.hurl
|
||||
|
||||
# 运行目录下所有 .hurl
|
||||
hurl --test tests/hurl/
|
||||
|
||||
# 生成 HTML 报告
|
||||
hurl --test --report-html build/report/ tests/hurl/
|
||||
|
||||
# 生成 JUnit 报告（CI 用）
|
||||
hurl --test --report-junit build/report.xml tests/hurl/
|
||||
|
||||
# 并行执行（--test 默认并行，同文件内串行）
|
||||
hurl --test --jobs 4 tests/hurl/
|
||||
|
||||
# 指定单个变量
|
||||
hurl --variable base_url=http://localhost:3000 --test file.hurl
|
||||
|
||||
# 失败后继续执行
|
||||
hurl --test --continue-on-error tests/hurl/
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
|
||||
| 错误 | 原因 | 修正 |
|
||||
|------|------|------|
|
||||
| `HTTP 200` 和请求之间有空行 | 空行会被当作 entry 分隔符 | 删除空行，HTTP 行紧跟请求 |
|
||||
| JSON body 有尾逗号 | Hurl 严格解析 JSON | 删除最后一个逗号 |
|
||||
| `jsonpath` 写成 `json_path` 或 `JsonPath` | 关键字大小写敏感 | 必须小写 `jsonpath` |
|
||||
| `[Captures]` 写成 `[Capture]` | 必须是复数 | `[Captures]`、`[Asserts]`、`[Options]` |
|
||||
| 变量 `{{ var }}` 有空格 | 允许，但建议统一 | `{{var}}` 或 `{{ var }}` 都可以 |
|
||||
| `isIsoDate` 用在非 RFC 3339 格式 | 只认 `YYYY-MM-DDTHH:mm:ss` 格式 | 如果是其他格式用 `matches` |
|
||||
| `file,path;` 路径含 `..` | Hurl 禁止相对父目录 | 用 `--file-root` 或调整路径 |
|
||||
10
.gitignore
vendored
10
.gitignore
vendored
@@ -76,4 +76,12 @@ docs/admin-openapi.yaml
|
||||
/api
|
||||
/gendocs
|
||||
.env.local
|
||||
/worker
|
||||
/worker
|
||||
.opencode/skills/json-canvas
|
||||
.opencode/skills/obsidian-bases
|
||||
.gitignore
|
||||
.opencode/skills/obsidian-cli
|
||||
.opencode/skills/obsidian-markdown
|
||||
.opencode/skills/kb-sync
|
||||
.gitignore
|
||||
.opencode/skills/defuddle
|
||||
|
||||
952
.opencode/skills/hurl-test/SKILL.md
Normal file
952
.opencode/skills/hurl-test/SKILL.md
Normal file
@@ -0,0 +1,952 @@
|
||||
---
|
||||
name: hurl-test
|
||||
description: Hurl 接口测试生成器。用户描述要测试的接口或业务流程，自动探索代码、确认需求、生成完整的 .hurl 测试文件（含 DTO 驱动的字段完整性断言）。触发词：测试、hurl、写测试、接口测试。
|
||||
---
|
||||
|
||||
# Hurl 接口测试生成器
|
||||
|
||||
**用户描述要测试什么，你来读代码、问确认、生成 .hurl 文件。**
|
||||
|
||||
适用于任何后端项目（Go / Python / Node / Java 等），不预设框架和目录结构。
|
||||
|
||||
---
|
||||
|
||||
## 触发条件
|
||||
|
||||
以下情况必须使用本 Skill：
|
||||
- 用户说"测试 XX 接口"、"写 hurl 测试"、"给 XX 加测试"
|
||||
- 用户说"测试 XX 流程"、"测试 XX 的业务逻辑"
|
||||
- 用户说"验证 XX 接口的字段"、"测试接口契约"
|
||||
- 用户提到 hurl、.hurl、接口测试、集成测试、冒烟测试
|
||||
|
||||
---
|
||||
|
||||
## 五阶段工作流（必须按顺序执行）
|
||||
|
||||
```
|
||||
Phase 1: 探索 → Phase 2: 确认 → Phase 3: 生成 → Phase 4: 验证 → Phase 5: 研判
|
||||
读代码搞清楚 展示给用户确认 输出 .hurl 文件 语法检查+试跑 分析失败/报告发现
|
||||
```
|
||||
|
||||
> **核心原则：测试是用来发现问题的，不是用来全部通过的。**
|
||||
> 断言基于代码定义（Handler + DTO）生成，与实际行为的差异是"发现"，不是要修掉的"错误"。
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: 探索（Explore）
|
||||
|
||||
**目标：读代码，搞清楚项目约定 + 涉及的接口 + 字段 + 依赖。要求准确，不求快。**
|
||||
|
||||
#### 真理源层级（必须遵守）
|
||||
|
||||
断言的字段名和类型基于以下优先级确定，**高优先级推翻低优先级**：
|
||||
|
||||
| 优先级 | 来源 | 说明 | 怎么找 |
|
||||
|-------|------|------|--------|
|
||||
| **1（最高）** | Handler 实际实现 | Handler 返回什么类型、调用哪个 response 方法、是否做了 model→DTO 转换 | 读 handler 函数体，看 `return response.Success(c, xxx)` 中 xxx 的类型 |
|
||||
| **2** | DTO / Response 结构体 | Handler 引用的 DTO 的 json tag、字段类型 | 读 DTO struct 定义 |
|
||||
| **3（最低）** | 路由注册的 Output 声明 | RouteSpec 中声明的 Output 类型，仅作为文档参考，可能过期 | 读路由注册代码 |
|
||||
|
||||
**关键规则**：
|
||||
- **不能只读 DTO 就生成断言**。必须追溯到 Handler 确认它确实用了这个 DTO
|
||||
- 如果 Handler 直接返回 GORM model 而非 DTO，断言用 model 的字段名（可能是大写 `ID` 而非小写 `id`）
|
||||
- 如果 Handler 用了 `response.SuccessWithPagination()`，分页字段以该函数的结构为准，而非 DTO 定义的分页结构
|
||||
- 当 Handler 实现与 DTO 定义不一致时，**以 Handler 为准生成断言，同时在 Phase 5 中将不一致标记为发现**
|
||||
|
||||
#### 1.1 项目画像（首次使用时必须执行，后续复用）
|
||||
|
||||
首次为项目生成 Hurl 测试时，先回答以下问题（通过读代码，不要猜）：
|
||||
|
||||
| 问题 | 怎么找 |
|
||||
|------|--------|
|
||||
| **语言/框架** | 看 go.mod / package.json / requirements.txt / pom.xml |
|
||||
| **路由注册在哪** | 搜索 `router`、`app.Get`、`@GetMapping`、`@app.route` 等关键词 |
|
||||
| **请求/响应 schema 定义在哪** | 搜索 DTO / schema / serializer / model 目录，看 json tag 或装饰器 |
|
||||
| **统一响应格式是什么** | 找 response helper 文件（如 `response.go`、`response.py`），记录 JSON 结构 |
|
||||
| **认证方式是什么** | 找 auth middleware，确定是 Bearer Token / Cookie / API Key / Basic Auth |
|
||||
| **登录接口是什么** | 找登录 handler，记录路径、请求体、响应中 token 的位置 |
|
||||
| **分页格式是什么** | 找列表接口的响应结构，记录 items/total/page 等字段名 |
|
||||
| **已有 hurl 测试吗** | 搜索 `*.hurl` 文件，复用已有的约定 |
|
||||
|
||||
将画像结果**写入 `tests/hurl/.project-profile.md` 文件持久化保存**。
|
||||
|
||||
#### 画像持久化（关键机制）
|
||||
|
||||
**首次使用时**：完成 1.1 探索后，将画像写入 `tests/hurl/.project-profile.md`，格式如下：
|
||||
|
||||
```markdown
|
||||
# 项目画像（Hurl 测试自动生成用）
|
||||
<!-- 由 hurl-test skill 自动生成，请勿手动修改 -->
|
||||
<!-- 如需刷新，删除此文件后重新运行 skill -->
|
||||
|
||||
## 技术栈
|
||||
- 语言: Go 1.25
|
||||
- 框架: Fiber v2
|
||||
- ORM: GORM
|
||||
|
||||
## 路由定义位置
|
||||
- 路由注册入口: internal/routes/routes.go
|
||||
- 按模块拆分: internal/routes/{module}.go
|
||||
- 路由注册函数: Register(router, doc, basePath, method, path, handler, spec)
|
||||
|
||||
## Schema 定义位置
|
||||
- DTO 目录: internal/model/dto/
|
||||
- 命名规则: {module}_dto.go
|
||||
- 字段标签: json / validate / description
|
||||
|
||||
## 统一响应格式
|
||||
{code: int, msg: string, data: any, timestamp: string(RFC3339)}
|
||||
- 成功: code=0, msg="success"
|
||||
- 错误: code!=0
|
||||
|
||||
## 分页格式
|
||||
{items: [], total: int, page: int, size: int}
|
||||
- 包裹在 data 字段内: $.data.items / $.data.total
|
||||
|
||||
## 认证方式
|
||||
- 后台: POST /api/auth/admin-login → $.data.access_token → Authorization: Bearer {token}
|
||||
- C端: JWT → Authorization: Bearer {token}
|
||||
|
||||
## 默认测试账号
|
||||
- 用户名: admin
|
||||
- 密码: Admin@123456
|
||||
|
||||
## 服务端口
|
||||
- 默认: 3000
|
||||
```
|
||||
|
||||
**后续使用时**：检查 `tests/hurl/.project-profile.md` 是否存在：
|
||||
- **存在** → 直接读取，跳过 1.1 的探索步骤，节省时间
|
||||
- **不存在** → 执行 1.1 完整探索，然后生成此文件
|
||||
- **用户说"刷新画像"** → 删除旧文件，重新执行 1.1
|
||||
|
||||
#### 1.2 找接口定义
|
||||
|
||||
根据用户要测的模块，定位路由注册代码，提取：
|
||||
|
||||
- **HTTP 方法**（GET / POST / PUT / DELETE / PATCH）
|
||||
- **路由路径**（含路径参数格式，如 `/users/:id` 或 `/users/{id}`）
|
||||
- **接口说明**（注释、Summary、装饰器描述）
|
||||
- **是否需要认证**
|
||||
- **请求 schema 类型名**（Input / Request DTO）
|
||||
- **响应 schema 类型名**（Output / Response DTO）
|
||||
|
||||
#### 1.3 读 schema 定义（DTO / struct / class / type）
|
||||
|
||||
定位请求和响应的 schema 定义文件，提取每个字段的：
|
||||
|
||||
- **字段名**：JSON 序列化后的名称（json tag / @JsonProperty / serializer field）
|
||||
- **语言类型**：string / int / bool / 数组 / 嵌套对象 / 可空等
|
||||
- **是否必填**：validate tag / required 装饰器 / 非空标注
|
||||
- **是否可空**：指针类型 / Optional / nullable
|
||||
- **是否参与序列化**：`json:"-"` / @JsonIgnore / exclude
|
||||
- **是否 omitempty**：`json:",omitempty"` / 条件序列化
|
||||
- **字段描述**：description tag / docstring / 注释
|
||||
|
||||
#### 1.4 识别业务依赖
|
||||
|
||||
读 service / business logic 层，识别：
|
||||
|
||||
- 创建操作需要哪些前置数据（如创建订单需要先有商品和用户）
|
||||
- 是否有唯一性约束（如用户名不能重复）
|
||||
- 是否依赖外部服务（支付网关、短信、OAuth 等）
|
||||
- 业务流转逻辑（状态机、级联操作）
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: 确认（Clarify）
|
||||
|
||||
**目标：向用户展示发现的内容，确认模糊点。不要闷头生成。**
|
||||
|
||||
#### 2.1 必须展示的内容
|
||||
|
||||
```
|
||||
我梳理了相关代码，发现以下信息：
|
||||
|
||||
📋 涉及接口：
|
||||
- [方法] [路径] - [说明]（认证: 是/否）
|
||||
- ...
|
||||
|
||||
📦 响应字段（基于 {SchemaName}）：
|
||||
- [字段名]: [类型] - [说明]
|
||||
- ...（共 N 个字段，将全部生成断言）
|
||||
|
||||
🔗 依赖关系：
|
||||
- [创建 X 需要先创建 Y]
|
||||
- ...
|
||||
|
||||
⚠️ 特殊情况：
|
||||
- [涉及外部服务 / 文件上传 / 特殊认证等]
|
||||
```
|
||||
|
||||
#### 2.2 按需确认（只问有歧义的）
|
||||
|
||||
| 场景 | 要问的 |
|
||||
|------|--------|
|
||||
| 流程范围不明确 | "要测到哪一步？" |
|
||||
| 多种用户角色 | "用哪种身份测？" |
|
||||
| 是否测异常 | "需要包含异常 case 吗？（参数校验失败、权限不足等）" |
|
||||
| 是否测数据隔离 | "需要验证不同用户间数据不可见吗？" |
|
||||
| 涉及第三方 | "XX 部分怎么处理？绕过 / 模拟回调 / 跳过？" |
|
||||
| 前置数据来源 | "XX 依赖数据是通过 API 创建还是假设已存在？" |
|
||||
|
||||
**如果用户说"越完整越好"或"都要"→ 默认全部包含，不再追问。**
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: 生成（Generate）
|
||||
|
||||
**目标：生成完整的 .hurl 文件，字段断言基于 schema 代码，不能编造。**
|
||||
|
||||
#### 3.1 文件头注释
|
||||
|
||||
```hurl
|
||||
# ============================================================
|
||||
# 测试：{测试名称}
|
||||
# 生成时间：{日期}
|
||||
# 涉及模块：{module1, module2, ...}
|
||||
# 涉及接口：{N} 个
|
||||
# 断言数量：{N} 条
|
||||
# 前置条件：{服务运行 + 必要的前置条件}
|
||||
# ============================================================
|
||||
# 流程：
|
||||
# 1. {步骤描述}
|
||||
# 2. {步骤描述}
|
||||
# ...
|
||||
# ============================================================
|
||||
```
|
||||
|
||||
#### 3.2 请求生成规则
|
||||
|
||||
**认证**：
|
||||
|
||||
- 根据 Phase 1 画像中的登录接口和 token 位置生成
|
||||
- token 必须通过 `[Captures]` 捕获，后续请求引用
|
||||
- 如果是 Cookie 认证，用 `[Cookies]` 或 cookie capture
|
||||
|
||||
**CRUD 标准模式**：
|
||||
|
||||
| 操作 | 生成要求 |
|
||||
|------|---------|
|
||||
| **创建（POST）** | capture 返回的 ID；**所有**唯一约束字段用 `{{newUuid}}` 防冲突 |
|
||||
| **查询详情（GET）** | **逐字段断言**（类型 + 值，见 3.3） |
|
||||
| **查询列表（GET）** | 分页结构断言 + items[0] 逐字段断言 |
|
||||
| **修改（PUT/PATCH）** | 修改后**紧跟一个 GET 验证修改生效** |
|
||||
| **删除（DELETE）** | 删除后**紧跟一个 GET 验证已删除** |
|
||||
|
||||
#### 唯一值防冲突规范（强制执行）
|
||||
|
||||
**所有创建类请求（POST）中，凡是有唯一约束的字段，必须使用 `{{newUuid}}` 或包含 UUID 后缀**，确保测试可重复运行。
|
||||
|
||||
| 场景 | 正确做法 | 错误做法 |
|
||||
|------|---------|---------|
|
||||
| 编码/Code 字段 | `"code": "TEST-{{newUuid}}"` | `"code": "TEST-001"` |
|
||||
| 名称（有唯一约束） | `"name": "测试-{{newUuid}}"` | `"name": "测试角色"` |
|
||||
| 用户名 | `"username": "hurl_{{newUuid}}"` | `"username": "test_user"` |
|
||||
| 手机号 | `"phone": "189{{newUuid}}"` 取前11位，或放在 env 文件 | `"phone": "18899990001"` |
|
||||
| 邮箱 | `"email": "{{newUuid}}@test.com"` | `"email": "test@test.com"` |
|
||||
|
||||
**后续步骤需要引用的值（如登录用的 username/password）**：
|
||||
- 必须定义在 `env/dev.env` 中作为变量
|
||||
- 在创建请求和后续引用处都通过 `{{变量名}}` 引用，保持一致
|
||||
- env 文件中的值也应该带有测试标识前缀（如 `hurl_test_`），避免与真实数据冲突
|
||||
- **env 中有唯一约束的变量值每次运行前可能需要更新**（文档中注明）
|
||||
|
||||
**业务流程模式**：
|
||||
|
||||
- 按用户描述的流程顺序编排请求
|
||||
- 上一步的输出（ID、状态等）通过 `[Captures]` 传给下一步
|
||||
- 关键步骤加中间状态验证（如创建订单后验证状态为"待支付"）
|
||||
|
||||
#### 3.3 schema 到断言的映射
|
||||
|
||||
读到 schema 字段后，按以下规则生成 jsonpath 断言：
|
||||
|
||||
**通用类型映射（所有语言）**：
|
||||
|
||||
| Schema 类型特征 | Hurl 断言 |
|
||||
|----------------|-----------|
|
||||
| 字符串（string / str / String） | `isString` |
|
||||
| 整数（int / integer / long / Int） | `isInteger` |
|
||||
| 浮点（float / double / decimal / Float） | `isNumber` |
|
||||
| 布尔（bool / boolean / Boolean） | `isBoolean` |
|
||||
| 数组 / 列表（[] / List / Array） | `isList` |
|
||||
| 嵌套对象（struct / class / dict / object） | `isObject`，并递归检查子字段 |
|
||||
| 可空类型（指针 / Optional / nullable） | `exists`（不强制类型，因为可能是 null） |
|
||||
| 不参与序列化（json:"-" / @JsonIgnore / exclude=True） | **跳过，不生成断言** |
|
||||
| 条件序列化（omitempty / if not None） | `exists` 或不生成（取决于场景） |
|
||||
|
||||
**Go 特定映射**：
|
||||
|
||||
| Go 类型 | Hurl 断言 |
|
||||
|---------|-----------|
|
||||
| `string` | `isString` |
|
||||
| `int`, `int8/16/32/64`, `uint`, `uint8/16/32/64` | `isInteger` |
|
||||
| `float32`, `float64` | `isNumber` |
|
||||
| `bool` | `isBoolean` |
|
||||
| `[]T` | `isList` |
|
||||
| `*string`, `*int`, `*uint` 等指针 | `exists` |
|
||||
| `time.Time` | `isString`（通常序列化为字符串） |
|
||||
| `map[string]any` | `isObject` |
|
||||
|
||||
**Python 特定映射（Pydantic / Django / FastAPI）**：
|
||||
|
||||
| Python 类型 | Hurl 断言 |
|
||||
|------------|-----------|
|
||||
| `str` | `isString` |
|
||||
| `int` | `isInteger` |
|
||||
| `float`, `Decimal` | `isNumber` |
|
||||
| `bool` | `isBoolean` |
|
||||
| `list[T]`, `List[T]` | `isList` |
|
||||
| `Optional[T]`, `T | None` | `exists` |
|
||||
| `dict`, `Dict` | `isObject` |
|
||||
| `datetime`, `date` | `isString` |
|
||||
|
||||
**TypeScript/JavaScript 特定映射**：
|
||||
|
||||
| TS/JS 类型 | Hurl 断言 |
|
||||
|-----------|-----------|
|
||||
| `string` | `isString` |
|
||||
| `number`（整数上下文） | `isInteger` |
|
||||
| `number`（通用） | `isNumber` |
|
||||
| `boolean` | `isBoolean` |
|
||||
| `T[]`, `Array<T>` | `isList` |
|
||||
| `T \| null`, `T \| undefined` | `exists` |
|
||||
| `object`, `Record<>` | `isObject` |
|
||||
| `Date` | `isString` |
|
||||
|
||||
**Java 特定映射**：
|
||||
|
||||
| Java 类型 | Hurl 断言 |
|
||||
|----------|-----------|
|
||||
| `String` | `isString` |
|
||||
| `Integer`, `Long`, `int`, `long` | `isInteger` |
|
||||
| `Double`, `Float`, `BigDecimal` | `isNumber` |
|
||||
| `Boolean`, `boolean` | `isBoolean` |
|
||||
| `List<T>` | `isList` |
|
||||
| `@Nullable`, `Optional<T>` | `exists` |
|
||||
| `Map<K,V>` | `isObject` |
|
||||
| `LocalDateTime`, `Instant` | `isString` |
|
||||
|
||||
#### 3.4 统一响应格式断言
|
||||
|
||||
根据 Phase 1 画像中发现的统一响应格式，为**每个成功响应**添加格式断言。
|
||||
|
||||
示例：如果项目的统一格式是 `{code, msg, data, timestamp}`：
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
jsonpath "$.code" == 0
|
||||
jsonpath "$.msg" == "success"
|
||||
jsonpath "$.timestamp" isIsoDate
|
||||
```
|
||||
|
||||
示例：如果项目的格式是 `{status, message, result}`：
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
jsonpath "$.status" == "ok"
|
||||
jsonpath "$.message" isString
|
||||
```
|
||||
|
||||
示例：如果项目无统一包装，直接返回数据：
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
# 直接断言业务字段
|
||||
jsonpath "$.id" isInteger
|
||||
jsonpath "$.name" isString
|
||||
```
|
||||
|
||||
**不要假设响应格式，必须从代码中确认。**
|
||||
|
||||
#### 3.5 分页断言
|
||||
|
||||
根据 Phase 1 画像中发现的分页结构生成。
|
||||
|
||||
示例：如果是 `{items, total, page, size}` 格式：
|
||||
|
||||
```hurl
|
||||
jsonpath "$.data.items" isList
|
||||
jsonpath "$.data.total" isInteger
|
||||
jsonpath "$.data.total" >= 1
|
||||
jsonpath "$.data.page" isInteger
|
||||
jsonpath "$.data.size" isInteger
|
||||
# items 内元素逐字段断言
|
||||
jsonpath "$.data.items[0].{field}" {type_assert}
|
||||
```
|
||||
|
||||
示例：如果是 `{results, count, next, previous}` 格式（Django 风格）：
|
||||
|
||||
```hurl
|
||||
jsonpath "$.results" isList
|
||||
jsonpath "$.count" isInteger
|
||||
jsonpath "$.count" >= 1
|
||||
# results 内元素逐字段断言
|
||||
jsonpath "$.results[0].{field}" {type_assert}
|
||||
```
|
||||
|
||||
**根据实际代码调整字段名，不硬编码。**
|
||||
|
||||
#### 3.6 异常 Case 模板
|
||||
|
||||
**参数校验失败**：
|
||||
|
||||
```hurl
|
||||
# ── 异常：参数校验失败 ──
|
||||
POST {{base_url}}/{path}
|
||||
Authorization: Bearer {{token}}
|
||||
Content-Type: application/json
|
||||
{
|
||||
"required_field": ""
|
||||
}
|
||||
HTTP {expected_error_status}
|
||||
[Asserts]
|
||||
# 断言错误响应格式（根据项目约定调整）
|
||||
```
|
||||
|
||||
> HTTP 状态码根据项目实际返回确定：有的项目错误也返回 200 + 业务错误码，有的返回 400/422。
|
||||
|
||||
**未认证访问**：
|
||||
|
||||
```hurl
|
||||
# ── 异常：未认证访问 ──
|
||||
GET {{base_url}}/{protected_path}
|
||||
HTTP {expected_unauth_status}
|
||||
```
|
||||
|
||||
**越权访问**（如果用户要求）：
|
||||
|
||||
```hurl
|
||||
# ── 异常：用户 B 不能访问用户 A 的资源 ──
|
||||
GET {{base_url}}/{path}/{{user_a_resource_id}}
|
||||
Authorization: Bearer {{user_b_token}}
|
||||
HTTP {expected_forbidden_status}
|
||||
```
|
||||
|
||||
#### 3.7 特殊场景处理
|
||||
|
||||
| 场景 | 处理策略 |
|
||||
|------|---------|
|
||||
| **短信/邮件验证码** | 建议服务端加 test_mode 开关，固定验证码写入 env 文件；注释提醒用户 |
|
||||
| **第三方支付** | 优先用项目内部支付方式（如钱包支付）；如需测回调，直接 POST 回调接口模拟 |
|
||||
| **OAuth 登录（微信/Google/GitHub）** | 建议服务端加 test_mode 支持直接传 openid/email；注释提醒用户 |
|
||||
| **文件上传** | 用 Hurl 的 `[Multipart]` 语法 + testdata 目录下的样本文件 |
|
||||
| **外部 API 依赖** | 只测参数校验和错误响应格式，不断言业务结果；注释说明依赖 |
|
||||
| **WebSocket** | Hurl 不支持，注释说明跳过 |
|
||||
| **异步任务结果** | 用 Hurl 的 `retry` + `retry-interval` 轮询直到状态变更 |
|
||||
|
||||
异步轮询示例：
|
||||
|
||||
```hurl
|
||||
# 等待异步任务完成（最多重试 10 次，间隔 500ms）
|
||||
GET {{base_url}}/{path}/{{task_id}}
|
||||
Authorization: Bearer {{token}}
|
||||
[Options]
|
||||
retry: 10
|
||||
retry-interval: 500ms
|
||||
HTTP 200
|
||||
[Asserts]
|
||||
jsonpath "$.data.status" == "completed"
|
||||
```
|
||||
|
||||
#### 3.8 文件输出
|
||||
|
||||
**目录结构**（首次使用时创建，如不存在）：
|
||||
|
||||
```
|
||||
tests/hurl/
|
||||
├── env/
|
||||
│ └── dev.env # 环境变量
|
||||
├── testdata/ # 测试用的样本文件
|
||||
├── flows/ # 业务流程测试
|
||||
├── modules/ # 按模块的接口测试
|
||||
│ └── {module}/
|
||||
│ └── 01-crud.hurl
|
||||
├── negative/ # 异常/边界测试
|
||||
├── contract/ # 接口契约验证
|
||||
├── reports/ # Phase 5 发现报告（自动生成）
|
||||
│ └── findings-{name}-{date}.md
|
||||
└── Makefile # 快捷命令
|
||||
```
|
||||
|
||||
文件放置规则：
|
||||
|
||||
| 用户描述 | 输出路径 |
|
||||
|---------|---------|
|
||||
| 测试 XX 流程 / 业务流程 | `tests/hurl/flows/{flow-name}.hurl` |
|
||||
| 测试 XX 模块的 CRUD / 接口 | `tests/hurl/modules/{module}/01-crud.hurl` |
|
||||
| 测试异常/边界/权限 | `tests/hurl/negative/{name}.hurl` |
|
||||
| 测试接口契约/字段对齐 | `tests/hurl/contract/{name}.hurl` |
|
||||
|
||||
**如果项目已有 hurl 测试目录结构，沿用已有约定，不要另起炉灶。**
|
||||
|
||||
#### 3.9 env 和 Makefile
|
||||
|
||||
**env/dev.env**（首次创建时生成，内容基于 Phase 1 画像）：
|
||||
|
||||
```properties
|
||||
# 服务地址
|
||||
base_url=http://localhost:{port}
|
||||
|
||||
# 认证信息（根据项目实际填写）
|
||||
admin_username={默认用户名}
|
||||
admin_password={默认密码}
|
||||
|
||||
# 测试模式变量（如果有特殊场景）
|
||||
# test_sms_code=888888
|
||||
# test_openid=test_openid_001
|
||||
```
|
||||
|
||||
**Makefile**（首次创建时生成）：
|
||||
|
||||
```makefile
|
||||
SHELL := /bin/bash
|
||||
ENV ?= dev
|
||||
HURL_OPTS := --variables-file env/$(ENV).env --test
|
||||
|
||||
.PHONY: test test-flows test-modules test-negative report
|
||||
|
||||
test: ## 运行所有测试
|
||||
hurl $(HURL_OPTS) .
|
||||
|
||||
test-flows: ## 运行业务流程测试
|
||||
hurl $(HURL_OPTS) flows/
|
||||
|
||||
test-modules: ## 运行模块接口测试
|
||||
hurl $(HURL_OPTS) modules/
|
||||
|
||||
test-negative: ## 运行异常测试
|
||||
hurl $(HURL_OPTS) negative/
|
||||
|
||||
report: ## 生成 HTML 报告
|
||||
hurl $(HURL_OPTS) --report-html build/report/ .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: 验证（Verify）
|
||||
|
||||
**目标：确保生成的 .hurl 文件语法正确、可运行。**
|
||||
|
||||
#### 4.1 语法自检
|
||||
|
||||
- [ ] 每个请求之间有空行分隔
|
||||
- [ ] `[Captures]` 和 `[Asserts]` 拼写正确（大小写敏感）
|
||||
- [ ] 所有 `{{变量}}` 引用都有来源（env 文件定义 或 上游 `[Captures]`）
|
||||
- [ ] JSON body 无尾逗号、格式正确
|
||||
- [ ] `HTTP {status}` 在请求之后、`[Captures]` / `[Asserts]` 之前
|
||||
- [ ] 请求和断言之间没有多余空行（`HTTP` 行必须紧跟请求）
|
||||
- [ ] 文件上传路径相对于 hurl 文件位置正确
|
||||
|
||||
#### 4.2 运行测试
|
||||
|
||||
```bash
|
||||
hurl --variables-file tests/hurl/env/dev.env --test tests/hurl/{生成的文件}
|
||||
```
|
||||
|
||||
- 服务在跑 → 执行，如有失败分析修正
|
||||
- 服务没跑 → 跳过，告知用户手动验证命令
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: 研判（Triage）
|
||||
|
||||
**目标：分析测试失败原因，区分"测试自身问题"和"接口问题"，生成发现报告。**
|
||||
|
||||
> **核心原则：不因实际返回与预期不符而盲目修改断言。差异是"发现"，需要分类研判。**
|
||||
|
||||
#### 5.1 失败分类（A/B/C 三类）
|
||||
|
||||
每个断言失败必须归入以下三类之一：
|
||||
|
||||
| 类型 | 含义 | 判断标准 | 处置方式 |
|
||||
|------|------|---------|---------|
|
||||
| **A 类 — 测试自身错误** | JSON path 写错、请求参数遗漏、env 变量缺失、前置步骤失败导致 ID 为空 | 改正后 DTO/Handler 代码能对应上 | ✅ **自动修正测试**，不打扰用户 |
|
||||
| **B 类 — 代码一致性问题** | DTO 定义和 Handler 实际返回不一致（如 DTO 写 `json:"id"` 但 Handler 返回 `"ID"`；DTO 定义了分页结构但 Handler 用了另一种） | DTO 说的是 A，Handler 做的是 B，两个都是代码 | ⚠️ **以 Handler 为准修正断言** + **写入发现报告** |
|
||||
| **C 类 — 接口行为 Bug** | 接口行为不符合合理预期（如详情接口缺少列表接口有的字段；创建接口返回 500；同一个 DTO 在不同接口表现不一致） | Handler 的行为本身不合理，不是 DTO 过期的问题 | 🐛 **保留原始断言（测试会失败）** + **写入发现报告** |
|
||||
|
||||
#### 5.2 分类判断流程
|
||||
|
||||
```
|
||||
断言失败
|
||||
│
|
||||
├─ jsonpath 写错 / 变量未定义 / 前置步骤失败？
|
||||
│ → A 类：修正测试
|
||||
│
|
||||
├─ DTO 定义字段名 ≠ 实际返回字段名？（如 id vs ID, list vs items）
|
||||
│ │
|
||||
│ ├─ Handler 代码确实返回了不同的结构？
|
||||
│ │ → B 类：以 Handler 为准，报告不一致
|
||||
│ │
|
||||
│ └─ Handler 代码引用了 DTO 但行为不符？
|
||||
│ → C 类：接口 Bug
|
||||
│
|
||||
├─ 某个字段在接口 A 有、接口 B 没有？（如列表有但详情没有）
|
||||
│ → C 类：接口一致性 Bug
|
||||
│
|
||||
├─ 接口返回 5xx 错误？
|
||||
│ → C 类：服务端 Bug
|
||||
│
|
||||
└─ 业务逻辑不符预期？（如已传 packages 但响应中 packages 为空）
|
||||
→ C 类：业务逻辑 Bug
|
||||
```
|
||||
|
||||
#### 5.3 发现报告格式
|
||||
|
||||
报告输出到 **`tests/hurl/reports/findings-{测试文件名}-{日期}.md`**，格式如下：
|
||||
|
||||
```markdown
|
||||
# 🔍 Hurl 测试发现报告
|
||||
|
||||
- 测试文件：`flows/package-resource-full-flow.hurl`
|
||||
- 生成时间：2026-03-30
|
||||
- 总请求数：25
|
||||
- 通过：20
|
||||
- 失败：5（A类: 2, B类: 1, C类: 2）
|
||||
|
||||
---
|
||||
|
||||
## A 类（测试自身错误）— 已自动修正
|
||||
|
||||
### A-1: 角色名冲突导致创建失败
|
||||
- **位置**：第 2 步 POST /api/admin/roles
|
||||
- **原因**：角色名使用固定值，重复运行时 409 冲突
|
||||
- **修正**：角色名改为 `hurl测试角色-{{newUuid}}`
|
||||
|
||||
---
|
||||
|
||||
## B 类（代码一致性问题）— 已按 Handler 修正断言
|
||||
|
||||
### B-1: 角色接口返回原始 GORM 模型而非 DTO
|
||||
- **位置**：POST /api/admin/roles → 响应
|
||||
- **DTO 定义**：`RoleResponse` 有 `json:"id"`（小写）
|
||||
- **Handler 实际**：直接返回 `model.Role`，字段为 `ID`（大写 GORM 默认）
|
||||
- **影响**：前端按 API 文档对接会取不到 `id` 字段
|
||||
- **建议**：Handler 添加 model → DTO 转换
|
||||
|
||||
---
|
||||
|
||||
## C 类（接口行为 Bug）— 断言保留，测试会失败
|
||||
|
||||
### C-1: 套餐详情接口缺少 one_time_commission_amount
|
||||
- **位置**：GET /api/admin/packages/:id（代理视角）
|
||||
- **预期**：`PackageResponse` DTO 定义了 `one_time_commission_amount` 字段
|
||||
- **实际**：列表接口 GET /packages 返回该字段，详情接口不返回
|
||||
- **影响**：代理端查看单个套餐时看不到佣金信息
|
||||
- **建议**：Detail handler 增加佣金信息增强逻辑
|
||||
|
||||
### C-2: 批量分配对已授权店铺返回 500
|
||||
- **位置**：POST /api/admin/shop-package-batch-allocations
|
||||
- **预期**：对已有授权的店铺，应返回业务错误码（4xx），而非 500
|
||||
- **实际**：返回 `{code: 2001, msg: "内部服务器错误"}`
|
||||
- **影响**：前端无法区分是参数错误还是服务异常
|
||||
- **建议**：添加"已存在授权"的前置检查，返回明确的业务错误
|
||||
```
|
||||
|
||||
#### 5.4 研判完成后的交付物
|
||||
|
||||
| 交付物 | 说明 |
|
||||
|-------|------|
|
||||
| **修正后的 .hurl 文件** | A 类已自动修正；B 类按 Handler 实际修正；C 类**保留原始断言**（预期失败） |
|
||||
| **发现报告** | `tests/hurl/reports/findings-{name}-{date}.md` |
|
||||
| **终端摘要** | 向用户输出发现数量和关键 C 类问题摘要 |
|
||||
|
||||
#### 5.5 用户交互
|
||||
|
||||
研判完成后，向用户展示摘要并询问：
|
||||
|
||||
```
|
||||
## 研判结果
|
||||
|
||||
- A 类（测试错误）：N 个，已自动修正
|
||||
- B 类（一致性问题）：N 个，已按实际修正并记录
|
||||
- C 类（接口 Bug）：N 个，断言保留（测试会失败直到代码修复）
|
||||
|
||||
### C 类发现摘要：
|
||||
1. [C-1] 套餐详情缺少 one_time_commission_amount
|
||||
2. [C-2] 批量分配对已授权店铺返回 500
|
||||
|
||||
详细报告已写入: tests/hurl/reports/findings-xxx.md
|
||||
|
||||
是否需要对某个 C 类发现调整处置？（如确认为已知行为，改为 B 类）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 红线规则
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| **不跳过 Phase 1** | 必须读代码确认接口路径和字段，不能凭记忆或猜测 |
|
||||
| **不跳过 Phase 2** | 必须向用户展示发现的接口和字段，确认后再生成 |
|
||||
| **不编造字段** | 所有断言的字段名必须来自实际 schema 代码 |
|
||||
| **不编造路径** | 所有接口路径必须来自实际路由代码 |
|
||||
| **不遗漏字段** | schema 中每个参与序列化的字段都必须有对应断言 |
|
||||
| **不硬编码 ID** | 所有依赖的 ID 通过 `[Captures]` 从上游请求获取 |
|
||||
| **不假设响应格式** | 统一响应结构必须从代码中确认，不同项目格式不同 |
|
||||
| **唯一值防冲突** | 创建类请求的**所有**唯一约束字段必须使用 `{{newUuid}}`（详见 3.2 规范） |
|
||||
| **自给自足** | 每个 .hurl 文件自己创建测试数据，不依赖外部数据准备 |
|
||||
| **不为通过而改断言** | 断言失败时走 Phase 5 研判流程，C 类 Bug 必须保留断言并写入发现报告 |
|
||||
| **Handler 追溯** | 断言字段名必须追溯到 Handler 实际返回的类型，不能只看 DTO 定义（详见 Phase 1 真理源层级） |
|
||||
|
||||
---
|
||||
|
||||
## AI 助手检查清单
|
||||
|
||||
### 生成阶段自检（Phase 3 完成后）
|
||||
|
||||
1. ✅ 文件头注释包含流程描述和前置条件
|
||||
2. ✅ 认证步骤正确 capture 了 token / cookie
|
||||
3. ✅ 所有依赖数据通过 API 链式创建（自给自足）
|
||||
4. ✅ 每个成功响应断言了项目的统一响应格式
|
||||
5. ✅ 查询详情接口**逐字段断言**（类型 + 值，基于 Handler 实际返回）
|
||||
6. ✅ 分页接口断言了分页结构 + 第一条记录的字段
|
||||
7. ✅ 修改操作后紧跟 GET 验证修改生效
|
||||
8. ✅ 删除操作后紧跟 GET 验证已删除
|
||||
9. ✅ **所有**创建请求的唯一约束字段使用了 `{{newUuid}}`
|
||||
10. ✅ `{{变量}}` 引用无悬空（都有 env 或 capture 来源）
|
||||
11. ✅ 文件放在了正确的目录位置
|
||||
12. ✅ 特殊场景有明确的处理策略和注释提醒
|
||||
13. ✅ 断言字段名已追溯到 Handler 实际返回类型（非仅依赖 DTO）
|
||||
|
||||
### 研判阶段自检（Phase 5 完成后）
|
||||
|
||||
14. ✅ 每个断言失败都已分类（A/B/C）
|
||||
15. ✅ A 类错误已自动修正
|
||||
16. ✅ B 类不一致已按 Handler 修正断言，并写入发现报告
|
||||
17. ✅ C 类 Bug 保留了原始断言（测试预期失败），并写入发现报告
|
||||
18. ✅ 发现报告已输出到 `tests/hurl/reports/findings-{name}-{date}.md`
|
||||
19. ✅ 向用户展示了研判结果摘要
|
||||
|
||||
---
|
||||
|
||||
## 附录：Hurl 语法速查
|
||||
|
||||
**生成 .hurl 文件时必须参照本速查，不可凭记忆编造语法。**
|
||||
|
||||
### 文件结构
|
||||
|
||||
一个 .hurl 文件由多个 entry 组成，每个 entry = 请求 + 可选响应：
|
||||
|
||||
```
|
||||
请求1
|
||||
响应1（可选）
|
||||
|
||||
请求2
|
||||
响应2（可选）
|
||||
```
|
||||
|
||||
entry 之间用空行分隔。
|
||||
|
||||
### 请求格式
|
||||
|
||||
```hurl
|
||||
METHOD URL
|
||||
Header1: value1
|
||||
Header2: value2
|
||||
[Options]
|
||||
key: value
|
||||
[Query]
|
||||
param1: value1
|
||||
[Form]
|
||||
field1: value1
|
||||
[Multipart]
|
||||
file1: file,path/to/file;
|
||||
[BasicAuth]
|
||||
username: password
|
||||
[Cookies]
|
||||
name: value
|
||||
BODY（JSON / XML / multiline string / file）
|
||||
```
|
||||
|
||||
**规则**：
|
||||
- Method + URL 是第一行，必须
|
||||
- Headers 紧跟 URL 之后（无 section 标记）
|
||||
- Sections（`[Query]`、`[Form]`、`[Options]` 等）顺序任意
|
||||
- Body 必须在最后
|
||||
- JSON body 直接写 `{ }` 即可，自动设置 Content-Type: application/json
|
||||
|
||||
### 响应格式
|
||||
|
||||
```hurl
|
||||
HTTP {status_code}
|
||||
Header1: expected_value1
|
||||
[Captures]
|
||||
var_name: jsonpath "$.path"
|
||||
[Asserts]
|
||||
jsonpath "$.field" == "value"
|
||||
```
|
||||
|
||||
**规则**：
|
||||
- `HTTP {status}` 紧跟请求之后（中间不能有空行）
|
||||
- `HTTP *` 表示不检查状态码
|
||||
- Headers 检查紧跟 HTTP 行之后
|
||||
- `[Captures]` 和 `[Asserts]` 顺序任意
|
||||
|
||||
### 变量和模板
|
||||
|
||||
```hurl
|
||||
# 引用变量（从 env 文件、命令行或上游 capture 获取）
|
||||
GET {{base_url}}/api/users/{{user_id}}
|
||||
|
||||
# 内置函数
|
||||
POST {{base_url}}/api/users
|
||||
{
|
||||
"email": "{{newUuid}}@test.com",
|
||||
"created_at": "{{newDate}}"
|
||||
}
|
||||
```
|
||||
|
||||
可用函数：
|
||||
- `{{newUuid}}` — 生成 UUID v4
|
||||
- `{{newDate}}` — 生成 RFC 3339 UTC 时间戳
|
||||
|
||||
### Capture 语法
|
||||
|
||||
```hurl
|
||||
[Captures]
|
||||
# JSONPath
|
||||
token: jsonpath "$.data.access_token"
|
||||
user_id: jsonpath "$.data.id"
|
||||
first_item: jsonpath "$.items[0].name"
|
||||
|
||||
# Header
|
||||
location: header "Location"
|
||||
|
||||
# Cookie
|
||||
session: cookie "SESSIONID"
|
||||
|
||||
# Body（整个响应体作为字符串）
|
||||
full_body: body
|
||||
|
||||
# Status code
|
||||
code: status
|
||||
|
||||
# 正则表达式
|
||||
csrf: regex "name=\"csrf\" value=\"([^\"]+)\""
|
||||
|
||||
# 响应时间（毫秒）
|
||||
response_time: duration
|
||||
```
|
||||
|
||||
### Assert 语法
|
||||
|
||||
```hurl
|
||||
[Asserts]
|
||||
# ── 状态码 ──
|
||||
status == 200
|
||||
status >= 200
|
||||
status < 300
|
||||
|
||||
# ── JSONPath 断言 ──
|
||||
jsonpath "$.name" == "Alice" # 等于
|
||||
jsonpath "$.name" != "Bob" # 不等于
|
||||
jsonpath "$.age" > 18 # 大于
|
||||
jsonpath "$.age" >= 18 # 大于等于
|
||||
jsonpath "$.count" < 100 # 小于
|
||||
jsonpath "$.items" count == 5 # 集合长度
|
||||
jsonpath "$.name" startsWith "Al" # 前缀
|
||||
jsonpath "$.name" endsWith "ce" # 后缀
|
||||
jsonpath "$.name" contains "lic" # 包含
|
||||
jsonpath "$.date" matches /\\d{4}-\\d{2}-\\d{2}/ # 正则
|
||||
|
||||
# ── 类型断言 ──
|
||||
jsonpath "$.name" isString
|
||||
jsonpath "$.age" isInteger
|
||||
jsonpath "$.score" isFloat
|
||||
jsonpath "$.count" isNumber # 整数或浮点
|
||||
jsonpath "$.active" isBoolean
|
||||
jsonpath "$.items" isList
|
||||
jsonpath "$.meta" isObject
|
||||
jsonpath "$.id" isUuid
|
||||
jsonpath "$.created_at" isIsoDate # RFC 3339 格式
|
||||
jsonpath "$.field" isEmpty # 空集合
|
||||
|
||||
# ── 存在性 ──
|
||||
jsonpath "$.field" exists
|
||||
jsonpath "$.field" not exists
|
||||
|
||||
# ── 否定 ──
|
||||
jsonpath "$.name" not contains "Bob"
|
||||
jsonpath "$.status" not == "deleted"
|
||||
|
||||
# ── Header 断言 ──
|
||||
header "Content-Type" contains "application/json"
|
||||
header "X-Request-Id" exists
|
||||
|
||||
# ── 性能 ──
|
||||
duration < 1000 # 响应时间（毫秒）
|
||||
|
||||
# ── Body 断言 ──
|
||||
body contains "Hello"
|
||||
bytes count == 1024
|
||||
```
|
||||
|
||||
### Options（逐请求配置）
|
||||
|
||||
```hurl
|
||||
GET {{base_url}}/api/task/{{task_id}}
|
||||
[Options]
|
||||
retry: 10 # 最大重试次数（-1 = 无限）
|
||||
retry-interval: 500ms # 重试间隔
|
||||
delay: 2s # 请求前等待
|
||||
location: true # 跟随重定向
|
||||
insecure: true # 允许不安全 SSL
|
||||
verbose: true # 输出详细日志
|
||||
very-verbose: true # 输出更详细日志
|
||||
skip: true # 跳过此请求
|
||||
variable: key=value # 定义变量
|
||||
HTTP 200
|
||||
```
|
||||
|
||||
### Multipart 文件上传
|
||||
|
||||
```hurl
|
||||
POST {{base_url}}/api/upload
|
||||
[Multipart]
|
||||
file: file,testdata/sample.xlsx;
|
||||
field1: value1
|
||||
# 指定 Content-Type
|
||||
file2: file,testdata/data.bin; application/octet-stream
|
||||
```
|
||||
|
||||
### 运行命令
|
||||
|
||||
```bash
|
||||
# 运行单个文件
|
||||
hurl --test file.hurl
|
||||
|
||||
# 带变量文件
|
||||
hurl --variables-file env/dev.env --test file.hurl
|
||||
|
||||
# 运行目录下所有 .hurl
|
||||
hurl --test tests/hurl/
|
||||
|
||||
# 生成 HTML 报告
|
||||
hurl --test --report-html build/report/ tests/hurl/
|
||||
|
||||
# 生成 JUnit 报告（CI 用）
|
||||
hurl --test --report-junit build/report.xml tests/hurl/
|
||||
|
||||
# 并行执行（--test 默认并行，同文件内串行）
|
||||
hurl --test --jobs 4 tests/hurl/
|
||||
|
||||
# 指定单个变量
|
||||
hurl --variable base_url=http://localhost:3000 --test file.hurl
|
||||
|
||||
# 失败后继续执行
|
||||
hurl --test --continue-on-error tests/hurl/
|
||||
```
|
||||
|
||||
### 常见错误
|
||||
|
||||
| 错误 | 原因 | 修正 |
|
||||
|------|------|------|
|
||||
| `HTTP 200` 和请求之间有空行 | 空行会被当作 entry 分隔符 | 删除空行，HTTP 行紧跟请求 |
|
||||
| JSON body 有尾逗号 | Hurl 严格解析 JSON | 删除最后一个逗号 |
|
||||
| `jsonpath` 写成 `json_path` 或 `JsonPath` | 关键字大小写敏感 | 必须小写 `jsonpath` |
|
||||
| `[Captures]` 写成 `[Capture]` | 必须是复数 | `[Captures]`、`[Asserts]`、`[Options]` |
|
||||
| 变量 `{{ var }}` 有空格 | 允许，但建议统一 | `{{var}}` 或 `{{ var }}` 都可以 |
|
||||
| `isIsoDate` 用在非 RFC 3339 格式 | 只认 `YYYY-MM-DDTHH:mm:ss` 格式 | 如果是其他格式用 `matches` |
|
||||
| `file,path;` 路径含 `..` | Hurl 禁止相对父目录 | 用 `--file-root` 或调整路径 |
|
||||
Reference in New Issue
Block a user