smoke-tests

冒烟测试

在运行较慢的测试套件之前，快速验证面向用户的关键功能的最小化测试。 如果冒烟测试失败，说明构建已损坏。不会运行完整测试套件。 **特点：**设置最少 · 速度快（几秒内）· 仅覆盖正常流程 · 高信噪比 · 仅限 HTTP——不需要 JS 运行时或测试框架

**范围：**本技能仅涵盖使用 Hurl 或 curl 编写的 HTTP API 冒烟测试。不使用 Jest、Vitest 或其他进程内 JS 测试运行器——这里的冒烟测试是针对运行中应用（本地、预发布或预览环境）的黑盒 HTTP 检查。

---

识别现有冒烟测试

模式	检测方式
smoke-tests/ 目录	基于约定的目录
*.hurl 文件	Hurl 场景文件
smoke.sh / smoke-test.sh	基于 curl 的 shell 脚本
# @smoke / # @critical 注释	搜索标签

---

工具选择

使用 Hurl	使用 curl
多步骤流程（捕获令牌、串联请求）	单个请求／快速的一次性检查
需要结构化的 JSONPath 断言	希望 CI 依赖尽可能简单（curl 几乎总是预装的）
希望每个场景都有可读的声明式文件	不想安装 hurl 二进制文件
希望使用内置的 HTML/JUnit 报告	通过 jq 进行简单断言（状态码、单个字段）

除了单个请求以外，默认使用 Hurl——它专为此类用途打造，并且保持声明式。仅当目标环境无法安装 Hurl，或检查只需一行命令时，才使用 curl（JSON 检查搭配 jq，状态检查使用纯 shell）。

---

运行命令

# Hurl — run all .hurl files as tests
hurl --test --max-time 10 smoke-tests/*.hurl

# Hurl — single file with variables
hurl --test --max-time 10 --variable base_url=http://localhost:3000 smoke-tests/health.hurl

# Hurl — variables file + HTML report
hurl --test --max-time 10 --variables-file smoke-tests/vars.env --report-html report/ smoke-tests/*.hurl

# curl — quick health check, fail on non-2xx
curl --fail --silent --show-error "$BASE_URL/health" | jq -e '.status == "ok"'

# curl — run a smoke script (see references/curl.md)
BASE_URL=https://staging.example.com bash smoke-tests/smoke.sh

---

质量表

方面	应做	不应做
范围	测试关键工作流	测试每一种边缘情况
设置	使用最少、可复用的测试夹具	进行复杂的多步骤设置
断言	每个请求进行 1–3 项有针对性的断言	每个请求进行大量断言
耗时	每个请求 <100ms	运行缓慢、消耗资源的测试
维护	保持稳定，很少更改	因实现更改而失效
覆盖范围	覆盖广泛路径，而非深入测试	深入测试内部行为

---

CI 集成

# GitHub Actions — Hurl smoke as gate
- name: Install Hurl
  # Pin an exact version + verify checksum — don't pipe install.sh straight from
  # the web with no version pin or verification (see references/hurl.md for the
  # full snippet with the sha256sum check).
  run: |
    HURL_VERSION=4.3.0
    curl -LO https://github.com/Orange-OpenSource/hurl/releases/download/${HURL_VERSION}/hurl_${HURL_VERSION}_amd64.deb
    echo "<pin-expected-sha256-here>  hurl_${HURL_VERSION}_amd64.deb" | sha256sum -c -
    sudo dpkg -i hurl_${HURL_VERSION}_amd64.deb

- name: Run Smoke Tests
  id: smoke
  run: hurl --test --max-time 10 --variable base_url=${{ env.APP_URL }} smoke-tests/*.hurl

- name: Run Full Test Suite
  run: npm test
  if: steps.smoke.outcome == 'success'

# GitHub Actions — curl smoke as gate (no Hurl install needed)
- name: Run Smoke Tests
  id: smoke
  env:
    BASE_URL: ${{ env.APP_URL }}
  run: bash smoke-tests/smoke.sh

- name: Run Full Test Suite
  run: npm test
  if: steps.smoke.outcome == 'success'

---

快速检查清单

• 确认冒烟测试的位置（smoke-tests/ 目录、.hurl 文件或 smoke.sh）
• 列出关键工作流：身份验证、创建、读取、列表、健康检查
• 编写 5–10 项有针对性的检查——仅覆盖正常流程
• 在测试套件运行前设置环境（身份验证令牌、基础 URL）；如有需要，在运行后清理
• 单独运行；所有测试必须通过后才能运行完整测试套件
• 将其设置为 CI 流水线中的第一道关卡

---

集成示例

**识别：**某商店 API 最关键的路径是“用户能否登录并加载购物车？” 如果这条路径出错，其他一切都无关紧要——这是冒烟测试的绝佳候选。它是一个多步骤 HTTP 流程（登录、捕获令牌、使用令牌），因此选择 Hurl。

编写 smoke-tests/login-cart.hurl：

POST {{base_url}}/login
{ "email": "[email protected]", "password": "{{smoke_pw}}" }
HTTP 200
[Captures]
token: jsonpath "$.token"

GET {{base_url}}/cart
Authorization: Bearer {{token}}
HTTP 200
[Asserts]
jsonpath "$.items" exists

hurl --test --variable base_url=https://staging.example.com \
            --variable smoke_pw=$SMOKE_PW smoke-tests/login-cart.hurl

接入 CI——在完整测试套件之前设置此关卡：

- name: Smoke
  id: smoke
  run: hurl --test --variable base_url=${{ env.APP_URL }} smoke-tests/*.hurl
- name: Full suite
  run: npm test
  if: steps.smoke.outcome == 'success'

仅覆盖正常流程，两个请求，运行时间不到一秒。如果登录或购物车出错，完整测试套件就不会启动。

---

按需阅读

阅读时机	文件
需要 Hurl 模板、变量、CI 代码片段或模式时	references/hurl.md
没有 Hurl 可用／需要 curl+jq shell 脚本模板时	references/curl.md

---

基准测试

场景：.benchmarks/scenarios/smoke-tests-001-ci-gate.md · 运行日期：2026-08-31 · 日志：.benchmarks/runs/2026-08-31/smoke-tests-001-ci-gate.json

模型	不使用	使用	差值
claude-opus-4-8	50%	100%	+50%
claude-sonnet-4-6	33%	100%	+67%
claude-haiku-4-5	50%	100%	+50%

通过（运行日期：2026-08-31）。各模型均有提升；CI 门禁标准适用于所有模型。门禁规则见 .agents/skills/skill-optimizer/rules/release-gates.md。