120 lines
4.3 KiB
Markdown
120 lines
4.3 KiB
Markdown
# gRPC testsuite writing manual
|
|
|
|
This document will introduce how to write testsuite for the gRPC API of `api-testing`.
|
|
|
|
Before reading this document, you need to install and configure `api-testing`. For specific operations, please refer to [Official Document](./README.md). If you have completed these steps, you can continue reading the rest of this document.
|
|
|
|
## Create testsuite
|
|
|
|
To create a gRPC testsuite based on service reflection, just add the following content to the `spec` path of the yaml file:
|
|
|
|
```yaml
|
|
spec:
|
|
rpc:
|
|
serverReflection: true
|
|
```
|
|
|
|
Field `rpc` has five subfields in total:
|
|
|
|
| Name | Type | Optional |
|
|
| ---------------- | -------- | -------- |
|
|
| import | []string | √ |
|
|
| protofile | string | √ |
|
|
| protoset | string | √ |
|
|
| serverReflection | bool | √ |
|
|
|
|
|
|
### Field `import` and `protofile`
|
|
|
|
`protofile` is a file path pointing to the location of the `.proto` file where `api-testing` looks for descriptors.
|
|
|
|
The `import` field is similar to the `--import_path` parameter in the `protc` compiler, and is used to determine the location of the `proto` file and the directory for parsing dependencies. Like `protoc`, you don't need to specify the location of certain `proto` files here (such as `Protocol Buffers Well-Known Types` starting with `google.protobuf`), they are already built into `api-testing` binary file.
|
|
|
|
### Field `protoset`
|
|
|
|
Field `protoset` can be either a file path or a network address starting with `http(s)://`.
|
|
|
|
When you have a large number of `proto` or complex dependencies, you can try to use `protoc --descriptor_set_out=set.pb` to generate a `proto descriptor set`. Essentially it is a wire-encoded binary file that includes all the required descriptors.
|
|
|
|
|
|
### Field `serverReflection`
|
|
|
|
If the target server supports service reflection, setting this to `true` will no longer need to provide the above three fields.
|
|
|
|
---
|
|
Note: The priority order of `api-testing` for the three descriptor sources is
|
|
|
|
`serverReflection` > `protoset` > `protofile`
|
|
|
|
## Write gRPC API testsuite
|
|
|
|
Like writing the `HTTP` testsuite, you need to define the address of the server in the `api` field of the root node.
|
|
|
|
```yaml
|
|
api: 127.0.0.1:7070
|
|
```
|
|
|
|
By default, `api-testing` uses an insecure way to connect to the target server. If you want to configure a TLS certificate, please refer to the document [About Security](./secure.md)
|
|
|
|
---
|
|
|
|
Writing testsuite for `gRPC API` is basically the same as writing testsuite for `HTTP API`.
|
|
|
|
```yaml
|
|
- name: FunctionsQuery
|
|
request:
|
|
api: /server.Runner/FunctionsQuery
|
|
body: |
|
|
{
|
|
"name": "hello"
|
|
}
|
|
expect:
|
|
body: |
|
|
{
|
|
"data": [
|
|
{
|
|
"key": "hello",
|
|
"value": "func() string"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
The format of the `api` field is `/package.service/method`, which supports gRPC unary calls, client streams, server streams and bidirectional stream calls.
|
|
|
|
The `body` field at the same level as the `api` field is a `Protocol Buffers` message expressed in `JSON` format, representing the input parameters of the `api` to be called. Especially, when you need to call the client stream or bidirectional stream API, please use the `JSON Array` format to write the field `body`, such as:
|
|
|
|
```yaml
|
|
body: |
|
|
[
|
|
{
|
|
"name": "hello"
|
|
},
|
|
{
|
|
"name": "title"
|
|
}
|
|
]
|
|
```
|
|
|
|
## Write return content verification
|
|
|
|
Writing `gRPC API` to return content validation is basically the same as `HTTP API`. For the `gRPC API`, all return values are treated as `map` types and put into the `api testing` specific return structure:
|
|
|
|
```yaml
|
|
expect:
|
|
body: |
|
|
{
|
|
"data": [
|
|
{
|
|
"key": "hello",
|
|
"value": "func() string"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
`api-testing` has written a comparison lib for `JSON` comparison, please refer to here [compare](https://pkg.go.dev/github.com/linuxsuren/api-testing/pkg/compare)
|
|
|
|
Please note that for server-side streaming and bi-directional streaming modes where the server sends multiple messages, the target array in the `data` field must be the same length as the array to be validated, and both arrays must have the same contents under the same index.
|
|
|
|
The `verify` functionality of the `gRPC API` is consistent with the `HTTP API` and will not be repeated here. |