tmornini/http-spec

http-spec 镜像说明

镜像概述

http-spec是一款基于模板的HTTP请求/响应规范工具，旨在为API开发者提供轻量、语言无关的测试方案。它支持测试驱动开发（TDD），通过明确的请求/响应规范验证API合约的正确性，帮助开发者关注API的每一个字节输入输出（包括头信息）。

核心功能

• HTSF格式：模拟curl -v输出风格，定义请求与预期响应
• 动态匹配：内置（UUID、日期等）与自定义正则匹配器，支持动态内容验证与捕获
• 变量替换：复用之前捕获的匹配值，适应动态场景
• 请求延迟：支持请求间延迟，适配异步操作
• 并发处理：多文件并发执行，提升测试效率
• 请求仅模式：快速生成预期响应模板，助力迭代开发

使用场景

• API合约的自动化测试与验证
• API开发中的测试驱动实践
• 微服务架构下的接口测试（结合docker-compose）
• 验证API的完整输入输出（含头信息）

配置说明

支持以下命令行参数：

• -hostname string：目标主机名
• -http-retry-delay duration：失败请求重试延迟（默认1s）
• -max-http-attempts int：最大请求尝试次数（默认180）
• -scheme string：协议（http/https）
• -skip-tls-verification：跳过TLS验证（自签名证书、主机名不匹配等场景）

Docker镜像使用

该镜像为基础镜像，需构建自定义镜像使用：

1. 复制.htsf测试文件到镜像
2. 复制/run-http-specs可执行文件（编排测试顺序/时间）
3. 复制自定义匹配器文件（如matchers.yml）

Dockerfile示例

dockerfile
FROM tmornini/http-spec
MAINTAINER Your Name <your.email@example.com>

COPY run-http-specs /run-http-specs
COPY *.htsf /
COPY matchers.yml /

基本使用

运行测试命令：

bash
http-spec path/to/*.htsf

HTSF格式说明

• 请求部分：每行以> 开头，包含请求行、头、空行（必填）、可选请求体
• 响应部分：与请求间用空行分隔，每行以< 开头，包含状态行、排序后的头、空行（必填）、可选响应体
• 响应匹配失败时返回非零退出码，全部匹配返回0

匹配器与替换

内置匹配器

• ⧆name⧆:uuid⧆：匹配RFC-4122 UUID
• ⧆name⧆:date⧆：匹配RFC-822日期
• ⧆name⧆:iso8601:µs:z⧆：匹配带微秒与Z时区的ISO 8601时间戳

自定义匹配器

通过matchers.yml定义：

yaml
RFC4122v4: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"

使用方式：⧆name⧆:RFC4122v4⧆

变量替换

用⧈name⧈引用之前捕获的匹配值，如⧈user_id⧈

请求延迟

在请求间添加延迟行：

+ 1.5s  # 延迟1.5秒

请求仅模式

若请求后无预期响应，工具会输出格式化的响应（用于生成模板），此时返回非零退出码以避免误判。