接口测试 rest-assured 使用指南

注意，如果您正在使用 1.9.0 或者更早的版本请参考旧文档。

REST Assured 是一个可以简化 HTTP Builder 顶层 基于 REST 服务的测试过程的 Java DSL（针对某一领域，具有受限表达性的一种计算机程序设计语言）。它支持发起 POST,GET,PUT,DELETE,OPTIONS,PATCH 和 HEAD 请求，并且可以用来验证和校对这些请求的响应信息。

目录

1. 静态导入方法
2. 示例
   1. JSON 示例
   2. JSON Schema Validation
   3. XML 示例
   4. 高级用法
   5. XML
   6. JSON
   7. 其它示例
3. 关于 float 和 double
4. 语法关注点 (语法糖)
5. 获得响应体信息
   1. 从已验证的响应体中提取值
   2. JSON (使用 JsonPath)
   3. XML (使用 XmlPath)
   4. 获取某个路径下的值
   5. Headers, cookies, status 等
   6. 获取全部 header 值
   7. 获取全部 cookie 值
   8. 获取详细的 cookie 值
6. 获得响应信息
   1. 在验证响应之后提取特定的值
   2. JSON (使用 JsonPath)
   3. XML (使用 XmlPath)
   4. 单独使用路径
   5. Headers, cookies, status 等
   6. 获取 header
   7. 获取 cookie
   8. 获取详细的 cookie 值
7. 指定请求数据
   1. 请求 HTTP 资源
   2. 参数化
   3. 多值参数
   4. 参数不赋值
   5. 路径参数
   6. Cookie
   7. Header
   8. Content-Type
   9. 请求正文
8. 验证响应信息
   1. 响应体
   2. Cookie
   3. 状态码
   4. Header
   5. Content-Type
   6. 内容全匹配
   7. 关联类型验证
   8. 计算响应时间
9. 认证
   1. 基本认证
   2. 抢占式的基本认证
   3. 受质询的基本认证
   4. 摘要认证
   5. 表单认证
   6. CSRF
   7. OAuth
   8. OAuth1
   9. OAuth2
10. Multi-part 类型的表单数据
11. 对象映射
    1. 序列化
    2. 基于 Content-Type 的序列化
    3. 由 HashMap 创建 JSON
    4. 使用显式序列化器
    5. 反序列化
    6. 基于 Content-Type 的反序列化
    7. 自定义 content-type 的反序列化
    8. 使用显式反序列化器
    9. 配置
    10. 自定义
12. 解析器
    1. 自定义解析器
    2. 默认解析器
13. 默认值
14. 模式复用
15. 过滤器
    1. Response Builder
16. 日志
    1. 请求日志
    2. 响应日志
    3. 认证失败日志
17. 根路径
    1. 路径参数
18. Session 支持
    1. Session 过滤器
19. SSL
    1. SSL 无效的主机名
20. URL 编码
21. 代理（proxy）配置
    1. 静态代理配置
    2. 请求规范代理配置
22. 详细配置
    1. 编码配置
    2. 解码配置
    3. Session 配置
    4. 重定向（Redirect）DSL
    5. 网络连接配置
    6. JSON 配置
    7. HTTP 客户端配置
    8. SSL 配置
    9. 参数配置
23. Spring Mock Mvc 模型
    1. Bootstrapping RestAssuredMockMvc
    2. 异步请求
    3. 添加 Request Post Processors
    4. 添加 Result Handlers
    5. 使用 Result 匹配器
    6. 拦截器
    7. Specifications
    8. 重置 RestAssuredMockMvc
    9. Spring MVC 身份认证
       1. 使用 Spring Security 测试
       2. 注入一个用户
    10. 参数相关
24. Scala 支持
25. Kotlin 支持
26. 更多

静态导入方法

推荐大家从以下的类中静态导入方法，以提高使用 rest-assured 的效率。

io.restassured.RestAssured.*
io.restassured.matcher.RestAssuredMatchers.*
org.hamcrest.Matchers.*

如果您想使用Json Schema validation 还应该静态导入这些方法：

io.restassured.module.jsv.JsonSchemaValidator.*

更多使用方法参阅 Json Schema Validation 。

如果您正在使用 SpringMVC，你可以使用spring-mock-mvc 模型的 Rest Assured DSL 来对 Spring 的 controller 层进行单元测试。为此需要从RestAssuredMockMvc静态导入这些方法，而不是io.restassured.RestAssured:

io.restassured.module.mockmvc.RestAssuredMockMvc.*

示例

例一 - JSON

假设某个 get 请求 (to http://localhost:8080/lotto) 返回 JSON 如下:

{
"lotto":{
 "lottoId":5,
 "winning-numbers":[2,45,34,23,7,5,3],
 "winners":[{
   "winnerId":23,
   "numbers":[2,45,34,23,3,5]
 },{
   "winnerId":54,
   "numbers":[52,3,12,11,18,22]
 }]
}
}

REST assured 可以帮您轻松地进行 get 请求并对响应信息进行处理。举个例子，如果想要判断 lottoId 的值是否等于 5，你可以这样做：

get("/lotto").then().body("lotto.lottoId", equalTo(5));

又或许您想要检查 winnerId 的取值包括23 和 54：

get("/lotto").then().body("lotto.winners.winnerId", hasItems(23, 54));

注意: equalTo 和 hasItems 是 Hamcrest matchers 的方法，所以需要静态导入 org.hamcrest.Matchers。

注意这里的"json path"语法使用的是Groovy 的 GPath标注法，不要和 Jayway 的JsonPath语法混淆。

以 BigDecimal 返回 float 和 double 类型

（译者注：Java 在 java.math 包中提供的 API 类 BigDecimal，用来对超过 16 位有效位的数进行精确的运算）

您可以对 rest-assured 和 JsonPath 进行配置，使之以 BigDecimal 返回 json 里的数值类型数据，而不是 float 或者 double。可以参考下面 json 文本：

{

    "price":12.12 

}

默认情况下您验证 price 字段是否等于 float 类型的 12.12 像这样：

get("/price").then().body("price", is(12.12f));

但是如果想用 rest-assured 的 JsonConfig 来配置返回的所有的 json 数值都为 BigDecimal 类型：

given().
        config(RestAssured.config().jsonConfig(jsonConfig().numberReturnType(BIG_DECIMAL))).
when().
        get("/price").
then().
        body("price", is(new BigDecimal(12.12));

JSON Schema validation

自从 2.1.0 版本 rest-assured 开始支持Json Schema validation. 举个例子，在 classpath 中放置以下的 schema 文件（译者注：idea 的话可以放在 resources 目录下），products-schema.json:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Product set",
    "type": "array",
    "items": {
        "title": "Product",
        "type": "object",
        "properties": {
            "id": {
                "description": "The unique identifier for a product",
                "type": "number"
            },
            "name": {
                "type": "string"
            },
            "price": {
                "type": "number",
                "minimum": 0,
                "exclusiveMinimum": true
            },
            "tags": {
                "type": "array",
                "items": {
                    "type": "string"
                },
                "minItems": 1,
                "uniqueItems": true
            },
            "dimensions": {
                "type": "object",
                "properties": {
                    "length": {"type": "number"},
                    "width": {"type": "number"},
                    "height": {"type": "number"}
                },
                "required": ["length", "width", "height"]
            },
            "warehouseLocation": {
                "description": "Coordinates of the warehouse with the product",
                "$ref": "http://json-schema.org/geo"