gRPC测试用例编写指南

本文档将介绍如何编写api-testing的 gRPC API 的测试用例。

阅读本文档之前，您需要先安装并配置好api-testing，具体操作可以参考安装章节。如果您已经完成了这些步骤，可以继续阅读本文档的后续部分。

创建测试项目

创建一个基于服务反射的 gRPC 测试用例仅需在 yaml 文件的spec路径下加入以下内容：

spec:
  rpc:
    serverReflection: true

rpc字段一共有五个子字段

字段import和protofile

protofile是一个文件路径，指向api-testing查找描述符的.proto文件的位置。

import字段与protc编译器中的--import_path参数类似，用于确定查找proto文件的位置与解析依赖的目录。与protoc一样，您不需要在此处指定某些proto文件的位置（以google.protobuf开头的Protocol Buffers Well-Known Types），它们已经内置在了api-testing中。

字段protoset

protoset字段既可以是一个文件路径，也可以是http(s)://开头的网络地址。

当您的proto数量繁多或引用关系复杂，可以尝试使用protoc --descriptor_set_out=set.pb生成proto描述符集合。本质上它是一个使用了wire编码的二进制文件，其中包括了所有需要的描述符。

字段serverReflection

若目标服务器支持服务反射，将此项设为true则不再需要提供上述三个字段。

注：api-testing对三种描述符来源的优先级顺序为

serverReflection > protoset > protofile

编写gRPC API测试

与编写HTTP测试用例类型，您需要在根节点的api字段定义服务器的地址。

api: 127.0.0.1:7070

默认情况下api-testing使用不安全的方式连接到目标服务器。若您想配置TLS证书，请参考文档关于安全

编写gRPC API测试的方式与编写HTTP API测试的方式基本相同。

- name: FunctionsQuery
  request:
    api: /server.Runner/FunctionsQuery
    body: |
      {
        "name": "hello"
      }      
  expect:
    body: |
      {
        "data": [
          {
            "key": "hello",
            "value": "func() string"
          }
        ]
      }      

api字段的格式为/package.service/method，支持 gRPC 一元调用、客户端流、服务端流和双向流调用。

与api字段同级的body字段是以JSON格式表示的Protocol Buffers消息，代表将要调用的api的入参。特别的，当您需要调用客户端流或双向流 API 时，请使用JSON Array格式编写字段body，如：

body: |
  [
    {
      "name": "hello"
    },
    {
      "name": "title"
    }
  ]  

编写返回内容验证

编写gRPC API返回内容验证的方式与HTTP API基本相同。对与gRPC API来说，一切返回值都被视为map类型，被放入api testing特定的返回结构中：

expect:
  body: |
    {
      "data": [
        {
          "key": "hello",
          "value": "func() string"
        }
      ]
    }    

api-testing为JSON比对编写了一套对比库，请参考此处compare

请注意，对于服务端流和双向流模式，服务器发送多条消息的情况下，此处的data字段内的填写的目标数组，需同时满足与待验证数组长度相，两个数组同一下标的内容完全相同。

gRPC API的verify功能与HTTP API保持一致，此处不再赘述。