This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

欢迎访问 API Testing

API Testing 文档

1: 任务

1.1: 快速入门
1.2: gRPC TLS verification
1.3: gRPC测试用例编写指南
1.4: Mock Server 功能使用
1.5: 关于安全

2: 安装

2.1: 通过本地安装的方式使用 API Testing
2.2: 通过 Helm 安装的方式使用 API Testing

3: API

3.1: API 引用

4: 版本

4.1: v0.0.1
4.2: v0.0.12
4.3: v0.0.13
4.4: v0.0.14
4.5: v0.0.15
4.6: v0.0.17

记录

该项目正在积极开发中，很多功能尚待补充，我们希望您参与其中！

API Testing 一个基于 YAML 文件的开源接口测试工具，同时支持运行在本地、服务端。

在选择工具时，可以从很多方面进行考量、对比，以下几点是该工具的特色或者优点：

开源与否，atest 采用 MIT 开源协议，是最流行的宽松开源协议之一。有些工具也许有非常丰富的功能、漂亮的界面，但相比于开源项目，免费的工具不定什么时候就有可能变为收费的；而且，你的使用感受几乎很难直接反馈到产品中，只能被动接受。
质量、可靠性，作为一款用于测试场景的工具，atest 本身的单元测试覆盖率达 89%，单测代码与业务逻辑代码量平分秋色；另外，每次代码改动都需要通过代码扫描、单元测试等流水线。
身材小巧，整个工具大小为 18M，支持 Windows、Linux、macOS 平台。
只有简单的可执行二进制文件，不像部分工具会给你的操作系统安装莫名其妙的系统启动项目、系统服务等。
基于 YAML 文件，提交到 Git 仓库后，天生支持团队协作，无需注册额外账号。
同时提供简单、高级两种模式的返回值断言，还包括 JSON Schema 以及针对 Kubernetes 资源的校验判断。
支持性能测试。
直接在 VS Code 中直接触发执行单个或整个测试文件。

如何使用？

那么，这个工具长什么样子呢，下面是命令行 atest 的参数说明：

API testing tool

Usage:
  atest [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  json        Print the JSON schema of the test suites struct
  run         Run the test suite
  sample      Generate a sample test case YAML file
  server      Run as a server mode
  service     Install atest as a Linux service

Flags:
  -h, --help   help for atest

Use "atest [command] --help" for more information about a command.

本地模式

执行一个测试用例集文件：atest run -p sample/testsuite-gitlab.yaml，其中的参数 -p 支持模糊匹配多个文件。

如果希望对测试用例集执行性能测试的话，可以增加响应的参数：

atest run -p sample/testsuite-gitlab.yaml --duration 1m --thread 3 --report m

其中的参数 --report 可以指定性能测试输出报告，目前支持 Markdown 以及控制台输出。效果如下所示：

API	Average	Max	Min	Count	Error
GET https://gitlab.com/api/v4/projects	1.152777167s	2.108680194s	814.928496ms	99	0
GET https://gitlab.com/api/v4/projects/45088772	840.761064ms	1.487285371s	492.583066ms	10	0
consume: 1m2.153686448s

服务端模式

除了本地执行外，atest 还提供了基于 gRPC 协议服务端，通过下面的命令即可启动：

atest server

对于 Linux 操作系统，用户还可以通过下面的命令安装后台服务：

atest service (install | start | stop | restart)

当然，如果你对容器、Kubernetes 比较熟悉的话，本项目也提供了对应的支持。

这种模式，对于想要集成的用户而言，可以通过调用 gRPC 来执行测试。也可以安装 VS Code 插件，在编码与接口测试之间无缝切换，您可以搜索 api-testing 找到该插件。

插件会识别所有第一行是 #!api-testing 的 YAML 文件，并提供快速的执行操作，请参考如下截图：

如图所示，会有四个快捷执行操作：

run suite 会执行整个文件
run suite with env 会加载 env.yaml 文件并执行整个文件
run 执行单个测试用例（包括所依赖的用例）
debug 执行单个测试用例，并输出接口返回值

当你安装了 VS Code 插件后，会自动下载并安装 atest 及其服务。当然，你也可以配置不同的远端服务地址。

文件格式

atest 定义的 YAML 格式，基本遵循 HTTP 的语义，熟悉 HTTP 协议的同学即可快速上手。下面是一个范例，更多例子请参考这里：

#!api-testing
name: Kubernetes
api: https://192.168.123.121:6443
items:
- name: pods
  request:
    api: /api/v1/namespaces/kube-system/pods
    header:
      Authorization: Bearer token
  expect:
    verify:
    - pod("kube-system", "kube-ovn-cni-55bz9").Exist()
    - k8s("deployments", "kube-system", "coredns").Exist()
    - k8s("deployments", "kube-system", "coredns").ExpectField(2, "spec", "replicas")
    - k8s({"kind":"virtualmachines","group":"kubevirt.io"}, "vm-test", "vm-win10-dkkhl").Exist()

用户可以自定义请求的 Header、Payload 等，可以对响应体做全面的断言判断。

后续计划

如果您已经耐心阅读到这里的话，可以再顺便了解下这个项目后续的一些想法。

通过更多的实际场景来打磨、优化 atest 对接口测试的便利性、可扩展性，以不丢失易用性为前提增强功能。例如：

优化错误提示、反馈
提供与 CICD 集成的最佳实践
增加 gRPC 等协议的支持
增加测试记录信息的持久化
VS Code 插件支持测试用例编写的提示、格式校验
提供插件机制，增加对数据库等数据源的格式校验

最后期待您的反馈 https://github.com/LinuxSuRen/api-testing/issues

准备好开始了吗？

1 - 任务

通过任务学习 API Testing 实践。

1.1 - 快速入门

只需几个简单的步骤即可开始使用 API Testing。

本指南将帮助您通过几个简单的步骤开始使用 API Testing。

// TBD

1.2 - gRPC TLS verification

If you want to enable gRPC TLS, you need to generate your certificates in the workspace, or you can use an absolute path

1. 生成私钥

openssl genrsa -out server.key 2048

2. 生成证书（会提示即可，不必填写）

openssl req -new -x509 -key server.key -out server.crt -days 36500
国家名字
Country Name (2 letter code) [AU]:CN
省份全名
State or Province Name (full name) [Some-State]:GuangDong
城市名
Locality Name (eg, city) []:Meizhou
组织名
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Xuexiangban
组织单位名
Organizational Unit Name (eg, section) []:go
服务器or用户的名字
Common Name (e.g. server FQDN or YOUR name) []:kuangstudy
邮箱地址
Email Address []:24736743@qq.com

3.生成csr

openssl req -new -key server.key -out server.csr

4.配置openssl.cfg

1) 查找openssl在服务器的安装目录并且找到openssl.cnf
2) 编辑[ CA_default ] ，打开 copy_extensions = copy #取消注释
3) 找到[ req ]，打开 req_extensions = v3.req #取消注释
4) 找到[ v3_req ]，添加字段 subjectAltName = @alt_names
5) 添加新的标签在最底部 [ alt_names ]和标签字段
DNS.1 = localhost

5.生成本地私钥test.key

openssl genpkey -algorithm RSA -out test.key

6.根据私钥生成csr请求文件test.csr

openssl req -new -nodes -key test.key -out test.csr -days 3650 \
-subj "/C=US/ST=Denial/L=Springfield/O=Dis/CN=www.example.com" \
-config ./openssl.cnf -extensions v3_req

7.生成ca证书 pem

openssl x509 -req -days 365 -in test.csr \
-out test.pem -CA server.crt -CAkey server.key \
-CAcreateserial -extfile ./openssl.cnf -extensions v3_req

1.3 - gRPC测试用例编写指南

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

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

创建测试项目

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

spec:
  rpc:
    serverReflection: true

rpc字段一共有五个子字段

字段名	类型	是否可选
import	[]string	√
protofile	string	√
protoset	string	√
serverReflection	bool	√

字段`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保持一致，此处不再赘述。

1.4 - Mock Server 功能使用

Get started

您可以通过执行下面的命令 mock 一个容器仓库服务container registry:

atest mock --prefix / mock/image-registry.yaml

之后，您可以通过使用如下的命令使用 mock 功能。

docker pull localhost:6060/repo/name:tag

1.5 - 关于安全

通常在不使用 TLS 证书认证时，gRPC 客户端与服务端之间进行的是明文通信，信息易被第三方监听或篡改。所以大多数情况下均推荐使用 SSL/TLS 保护 gRPC 服务。目前atest已实现服务端 TLS，双向 TLS(mTLS) 需等待后续实现。

默认情况下atest不使用任何安全策略，等价于spec.secure.insecure = true。启用 TLS 仅需 yaml 中添加以下内容：

spec:
  secure:
    cert: server.pem
    serverName: atest

字段说明

secure共有以下五个字段：

字段名	类型	是否可选
cert	string	x
ca	string	√
key	string	√
serverName	string	x
insecure	bool	√

cert为客户端需要配置的证书的文件路径，格式为PEM。

serverName为 TLS 所需的服务名，通常为签发证书时使用的 x509 SAN。

ca为 CA 证书的路径，key为与cert对应的私钥，这两项填写后代表启用 mTLS。(mTLS 尚未实现)

当insecure为false时，cert和serverName为必填项。

2 - 安装

本节包含关于安装 API Testing 的内容。

2.1 - 通过本地安装的方式使用 API Testing

// TBD

2.2 - 通过 Helm 安装的方式使用 API Testing

You could install api-testing via Helm chart:

helm install atest oci://docker.io/linuxsuren/api-testing \
    --version v0.0.2-helm \
    --set service.type=NodePort

or upgrade it:

helm upgrade atest oci://docker.io/surenpi/api-testing \
    --version v0.0.2-helm \
    --set image.tag=master \
    --set replicaCount=3

SkyWalking

helm install atest oci://docker.io/linuxsuren/api-testing \
    --version v0.0.2-helm \
    --set image.tag=master \
    --set service.type=NodePort \
    --set service.nodePort=30154 \
    --set skywalking.endpoint.http=http://skywalking-skywalking-helm-oap.skywalking.svc:12800 \
    --set skywalking.endpoint.grpc=skywalking-skywalking-helm-oap.skywalking.svc:11800

3 - API

本节内容包含 API Testing 的 API。

3.1 - API 引用

// TBD.

4 - 版本

本节内容包含 API Testing 的版本概述。

4.1 - v0.0.1

日期：2024 年 6 月 1 日

// TBD

4.2 - v0.0.12

atest 版本发布 v0.0.12

atest 是一款用 Golang 编写的、基于 YAML 格式的开源接口测试工具，可以方便地在本地、服务端、持续集成等场景中使用。我们希望提供一个简单、强大、高质量的测试工具，方便测试、研发人员快速、低成本地借助接口测试为产品研发质量保驾护航。

通过以下命令启动 HTTP 代理服务器后，给您的浏览器配置该代理，打开业务系统就会自动录制：

docker run -p 1234:8080 -v /var/tmp:/var/tmp \
  ghcr.io/linuxsuren/api-testing atest-collector \
  --filter-path /api \
  -o /var/tmp/sample.yaml
# --filter-path /api 会过滤所有以 /api 为前缀的 HTTP 请求
# 关闭服务后，您可以在 /var/tmp/sample 这个目录中找到生成的测试用文件

更新重点

支持通过基于 HTTP 代理服务生成测试用例
支持根据 Swagger 数据生成接口测试覆盖率
增加 HTML、Markdown 等格式的测试报告
代码重构，包括：包结构、原文件名整理，逻辑抽象为接口以及不同实现
支持打印所有支持的模板函数
优化 Kubernetes 的部署清单文件
修复已知缺陷

本次版本发布，包含了以下三位 contributor 的努力：

4.3 - v0.0.13

atest 版本发布 v0.0.13

atest 是一款用 Golang 编写的、开源的接口测试工具。

你可以在容器中启动：

docker run -v /var/www/sample:/var/www/sample \
  --network host \
  linuxsuren/api-testing:master

或者，直接下载二进制文件后启动：

atest server --local-storage /var/www/sample

对于持续集成（CI）场景，可以通过在流水线中执行命令的方式：

# 执行本地文件
atest run -p your-test-suite.yaml
# 执行远程文件
atest run -p https://gitee.com/linuxsuren/api-testing/raw/master/sample/testsuite-gitee.yaml
# 容器中执行
docker run linuxsuren/api-testing:master atest run -p https://gitee.com/linuxsuren/api-testing/raw/master/sample/testsuite-gitee.yaml

你也可以把测试用例转为 JMeter 文件并执行：

# 格式转换
atest convert --converter jmeter -p https://gitee.com/linuxsuren/api-testing/raw/master/sample/testsuite-gitee.yaml --target gitee.jmx
# 执行
jmeter -n -t gitee.jmx

主要的新功能

增加了插件扩展机制，支持以 Git、S3、关系型数据为后端存储，支持从 Vault 获取密码等敏感信息
新增对 gRPC 接口的用例支持 @Ink-33
支持导出 JMeter 文件
支持通过 Operator 的方式安装，并上架 OperatorHub.io
提供了基本的 Web UI
支持导出 PDF 格式的测试报告 @wjsvec

本次版本发布，包含了以下 5 位 contributor 的努力：

4.4 - v0.0.14

atest 版本发布 v0.0.14

atest 是一款用 Golang 编写的、开源的接口测试工具。

你可以在容器中启动：

docker run --network host \
  linuxsuren/api-testing:v0.0.14

或者，直接下载二进制文件后启动：

atest server --local-storage /var/www/sample

主要的新功能

增加了对 tRPC 和 gRPC 协议的（命令行与 Web 界面）支持
新增了 Helm Chart 的安装方式
支持通过按钮切换暗模式
支持启动启动插件
支持在 Web 界面中参数化执行
支持生成 curl 与 Golang 代码
支持从 Postman 中导入测试用例
可观测方便，增加了对 Apache SkyWalking 和 Prometheus 的支持
一些 Web 界面操作的优化（例如：多语言、测试结果缓存、自动保存）

本次版本发布，包含了以下 5 位 contributor 的努力：

4.5 - v0.0.15

atest 发布 v0.0.15

atest 是致力于帮助开发者持续保持高质量 API 的开源接口工具。

你可以在命令行终端或者容器中启动：

docker run -p 8080:8080 linuxsuren/api-testing:v0.0.15

亮点

在本次版本发布之前，成功地为以下开源项目实现了 API 的 E2E 测试：

halo-dev/halo，一款 Java 实现的开源建站工具
dromara/hertzbeat，一款监控系统

非常期待 atest 可以帮助更多的项目持续提升、保持 API 稳定性。

主要的新功能

支持复用 Cookies（简化了基于 Cookie 做会话认证） (#301) @LinuxSuRen
增加了基于 Docker 的应用性能监控 (#300) @LinuxSuRen
支持以 Comment 的方式发送测试报告到 GitHub PR (#298) @LinuxSuRen
UI 布局重构 (#297) @LinuxSuRen
增加对 OAuth 认证的支持（包括 Device 模式） (#290) @LinuxSuRen
支持设置 gRPC 的元数据 (#282) @LinuxSuRen
增加了新的后端存储： Mongodb (#278) @LinuxSuRen

致谢

本次版本发布，包含了以下 2 位 contributor 的努力：

4.6 - v0.0.17

atest 发布 v0.0.17

atest 是致力于帮助开发者持续保持高质量 API 的开源接口工具。

你可以在命令行终端或者容器中启动：

docker run -p 8080:8080 ghcr.io/linuxsuren/api-testing:v0.0.17

亮点

我们提供了基于 Electron 的桌面应用，会极大地方便开发者在桌面环境中测试 API。
为缩减镜像的体积（40M），我们把插件全部以 OCI 的格式单独存储，并在启用时自动下载。
诞生了第二位项目 Committer @yuluo-yx

非常期待 atest 可以帮助更多的项目持续提升、保持 API 稳定性。

🚀 主要的新功能

支持通过 HTTP 请求执行测试套件 (#478) @LinuxSuRen
增加 gRPC 接口对 TLS 的支持 (#477) @DWJ-Squirtle
支持自动下载插件 (#471) @LinuxSuRen
补充代码生成器的 e2e 测试 (#458) @LinuxSuRen
支持复制测试用例和测试套件 (#455) @LinuxSuRen
Web 界面上添加切换语言的按钮 (#447) @SamYSF
支持通过 Web 界面查看 YAML 格式的测试套件 (#438) @SamYSF
支持发送测试报告到 gRPC 服务 (#431) @lizzy-0323
支持发送测试报告到 HTTP 服务 (#367) @hahahashen
增加基于 Electron 的桌面应用 (#428) @LinuxSuRen
实现了镜像 Registry 的 Mock 服务 (#425) @LinuxSuRen
支持在 Web 界面启动、刷新 Mock 服务 (#410) @LinuxSuRen
支持根据测试用例生成 JavaScript 代码 (#400) @YukiCoco
支持根据测试用例生成 Python 代码 (#398) @zhouzhou1017
支持根据测试用例生成 Java 代码 (#369) @Agility6
增加日志框架的支持 (#389) @yuluo-yx
生成 Golang 代码时支持 Cookie 的设置 (#363) @SLOWDOWNO
测试用例支持 Cookie 设置 (#355) @LinuxSuRen

🐛 缺陷修复

解决测试用例页面徽章显示的问题 (#462) @SamYSF
解决无法导入 Postman 子集的问题 (#426) @SamYSF
优化 gRPC 消息超过默认值的处理 (#399) @acceleratorssr
解决 golang.org/x/net 的安全漏洞 CVE-2023-45288 (#401) @yuluo-yx
修复生成 Golang 代码时对 HTTP 请求体的设置 (#383) @Agility6

📝 文档

增加行为准则说明 (#379) @yuluo-yx
增加安全漏洞相关的说明 (#391) @yuluo-yx
更新贡献文档说明 (#380) @yuluo-yx

👻 维护

用 openapi 官方的依赖库替换当前实现 (#439) @dshyjtdes8888
增加 issue comment github actions (#382) @yuluo-yx

致谢

本次版本发布，包含了以下 13 位 contributor 的努力：

欢迎访问 API Testing

记录

如何使用？

本地模式

服务端模式

文件格式

后续计划

准备好开始了吗？

1 - 任务

1.1 - 快速入门

1.2 - gRPC TLS verification

1.3 - gRPC测试用例编写指南

创建测试项目

字段import和protofile

字段protoset

字段serverReflection

编写gRPC API测试

编写返回内容验证

1.4 - Mock Server 功能使用

Get started

1.5 - 关于安全

字段说明

2 - 安装

2.1 - 通过本地安装的方式使用 API Testing

2.2 - 通过 Helm 安装的方式使用 API Testing

SkyWalking

3 - API

3.1 - API 引用

4 - 版本

4.1 - v0.0.1

4.2 - v0.0.12

更新重点

相关数据

4.3 - v0.0.13

主要的新功能

相关数据

4.4 - v0.0.14

主要的新功能

相关数据

4.5 - v0.0.15

亮点

主要的新功能

致谢

相关数据

4.6 - v0.0.17

亮点

🚀 主要的新功能

🐛 缺陷修复

📝 文档

👻 维护

致谢

相关数据

字段`import`和`protofile`

字段`protoset`

字段`serverReflection`