burl: 一个简单但灵活的 HTTP/3 测试框架,基于 bash 和 curl

我创建了一个基于 bash 和 curl 的新 HTTP/3 测试框架:
https://github.com/kingluo/burl

背景

几个月前,当我将 QUIC 补丁从 nginx 主线移植到 APISIX 并尝试测试时,我发现test::nginx运行得不太好。它使用错误的监听指令参数“http3”而不是“quic”(可能是由于版本差异)。

所以我想知道是否可以设计一个简单的测试框架,因为最新的curl已经完全支持HTTP/3。

许多测试框架更喜欢 DSL(领域特定语言),例如 test::nginx 和Hurl,因为它更用户友好。而且它看起来更受数据驱动。然而,这对于希望扩展其功能的开发人员来说并不好,因为他们需要学习其背后的语言,花时间通过阅读此测试框架的代码库来理解核心和扩展 API。换句话说,DSL 及其背后的语言为开发人员造成了知识鸿沟,因为它不直观,无法将 DSL 对应的功能映射到语言本身。尤其是当框架本身能力不足,需要扩展时,这种差距会带来巨大的学习成本。

以test::nignx为例,它是用Perl实现的。当我需要验证响应正文时,通过预共享密钥对其进行解密,内置函数没有帮助,因为它只支持正则表达式匹配。所以我需要编写一堆Perl 代码来做到这一点。然而,我对 Perl 不熟悉,所以这不是一件容易的事。众所周知,Perl 不是主流语言,学习曲线陡峭。当时我就想,如果我能用Python写代码该多好啊。

test::nginx的表达能力是有限的,尽管它已经支持使用curl发送请求,因为它不是一个脚本系统(当然,你可以使用Perl模块扩展它,但由于框架设计的限制,这对于大多数人来说是一项艰巨的任务)。

  1. 它假设您的输入是文本字符串,您不能使用其他格式(例如 protobuf),也不能压缩或加密文本。
  2. 唯一支持的输出后处理是正则匹配,因此您无法解析和验证其他形式的内容,例如解密。
  3. 您无法描述复杂的测试过程,例如发送三个请求来触发请求集配额并验证速率限制结果。
  4. 您不能发出其他类型的请求,例如 GRPC、SOAP。
    在我的实践中,当我有这样的需求超出test::nginx的能力时,我必须将它们委托给lua部分,这是非常麻烦的。

例如,当我需要解析并验证CAS Auth插件的正确性时,涉及到很多客户端CAS协议细节,所以你必须在lua部分实现整个逻辑,这增加了维护的难度混合。众所周知,Perl 和 Lua 都不是流行语言。;-(

您可以看到下面的测试用例涉及额外的 lua lib 开发来测试 CAS。并且,为了适应 test::nginx 缺乏响应解析,您必须在 lua 环境中进行转换。相当烦人,至少对我来说,因为这些年来我写了很多这样的测试用例。

=== TEST 2: login and logout ok
--- config
    location /t {
        content_by_lua_block {
            local http = require "resty.http"
            local httpc = http.new()
            -- Test-specific CAS lua lib
            local kc = require "lib.keycloak_cas"

            local path = "/uri"
            local uri = "http://127.0.0.1:" .. ngx.var.server_port
            local username = "test"
            local password = "test"

            local res, err, cas_cookie, keycloak_cookie = kc.login_keycloak(uri .. path, username, password)
            if err or res.headers['Location'] ~= path then
                ngx.log(ngx.ERR, err)
                ngx.exit(500)
            end
            res, err = httpc:request_uri(uri .. res.headers['Location'], {
                method = "GET",
                headers = {
                    ["Cookie"] = cas_cookie
                }
            })
            assert(res.status == 200)
            ngx.say(res.body)

            res, err = kc.logout_keycloak(uri .. "/logout", cas_cookie, keycloak_cookie)
            assert(res.status == 200)
        }
    }
--- response_body_like
uri: /uri
cookie: .*
host: 127.0.0.1:1984
user-agent: .*
x-real-ip: 127.0.0.1

类似地,Hurl也使用 DSL 来描述测试。它的后端语言是 Rust。所以在可扩展性方面,它似乎比 test::nginx 差,因为它需要编译代码。然而,Rust 的生态系统比 Perl 的要好得多。所以你可以轻松地编写代码。但无论如何,您需要使用与 DSL 不同的语言来编写代码。

有没有一个简单的测试框架可以满足以下需求?

  1. 没有 DSL,只有简单的 shell 脚本
  2. 易于扩展且独立于编程语言
  3. 可用于初始化和测试任何服务器,不限于nginx,例如envoy

Bash 脚本

Shell是我们日常工作中终端下最重要的工具。每个管理员和开发人员都需要输入命令来完成他们的工作。最有趣的是,shell也是一个编程平台,即脚本。当我们谈论脚本时,我们关心两个方面:shell 语言本身的强大功能和可用的命令,它们就像高级编程语言的标准库。

在计算机历史的远古时代,shell的功能非常弱,命令也非常有限,于是Perl诞生了。但现在,情况发生了变化。许多高级的 shell 已经出现,例如 bash 和 zsh,它们为表达复杂逻辑提供了许多优秀的语言元素。还有越来越多的方便且优雅的命令,例如 jq,它用紧凑的表达式解析 JSON。在Linux和Mac中,默认的shell是bash,所以它就在我们眼皮底下,那么为什么不使用它来完成我们的测试任务呢?为什么要费心去复杂的编程来完成工作,对吧?

Shell 命令看起来非常自然和直接。命令行是由单词组成的,就像人类语言一样,那么为什么要使用 DSL?此外,如果简单的命令行不能满足您的要求,您可以使用变量和流程控制语句对其进行重构,就像任何主流编程语言一样。请注意,脚本编写是可选的,即您不会遇到任何复杂性,因为简单的命令行即可完成所有操作,因此一切都像 DSL 一样工作,但效果更好。

例如,如果我需要发送 GET 并检查 404,两个简单的命令就足够了:

# send request
REQ /anything/foobar

# validate the response headers
HEADER -x "HTTP/3 404"

但我需要检查 Prometheus 是否将 404 事件记录为正确的数字,我该怎么做?解析 Prometheus 指标消息并检查 shell 函数中计数器的变化。一切看起来仍然很简单,对吧?这就是脚本的美妙之处。

count_404() {
    curl http://127.0.0.1:9091/apisix/prometheus/metrics 2>&1 | \
        grep -F 'apisix_http_status{code="404",route="1",matched_uri="/anything/*"' | \
        awk '{print $2}'
}

# send the first request
REQ /anything/foobar

# get current counter
cnt1=`count_404`

# send the second request
REQ /anything/foobar

cnt2=`count_404`

# check if the counter is increased
((cnt2 == cnt1 + 1))

您可以使用流程控制语句来表达任何业务逻辑。

例如,要测试请求限制插件是否工作,可以使用循环。

# consume the quota
for ((i=0;i<2;i++)); do
    # send request
    REQ /httpbin/get -X GET --http3-only

    # validate the response headers
    HEADER -ix "HTTP/3 200"
done

# no quota
REQ /httpbin/get -X GET --http3-only
HEADER -x "HTTP/3 503"
HEADER -ix "x-ratelimit-remaining: 0"

burl: bash + curl

burl是一个基于bash和curl的简单但灵活的HTTP/3测试框架。

设计

  1. 测试文件包含一个或多个测试用例,以及文件头的可选初始部分,例如配置 nginx.conf 以及通过模板渲染启动 nginx。
  2. 每个测试用例由三部分组成:

    1. 构造并发送请求,并将响应头和响应正文保存到文件中以供后续步骤使用。
    2. 验证响应标头,例如使用“grep”。
    3. 解析并验证响应正文,例如使用“jq”表达式。
  3. 易于扩展,您可以使用任何命令或其他高级脚本(例如 Python)验证响应(步骤 2.1 和 2.2)。
  4. 任何命令失败都会停止测试过程(通过“set -euo pipelinefail”bash 选项启用)。
  5. 默认情况下会回显测试过程(通过“set -x”bash 选项启用)。

概要

#!/usr/bin/env burl

# Optional initialization here...
# Before all test cases are executed.
# For example, render nginx.conf and start nginx.
SET NGX_CONF_HTTP <<EOF
upstream test_backend {
    server $(dig +short nghttp2.org):443;

    keepalive 320;
    keepalive_requests 1000;
    keepalive_timeout 60s;
}
EOF

SET NGX_CONF <<'EOF'
location / {
    add_header Alt-Svc 'h3=":443"; ma=86400';
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host "nghttp2.org";
    proxy_pass https://test_backend;
}
EOF

START_NGX

TEST 1: test case

# Send request
# REQ is a curl wrapper so you can apply any curl options to suit your needs.
# Check https://curl.se/docs/manpage.html for details.
REQ /httpbin/anything --http3 -d foo=bar -d hello=world

# Validate the response headers
# HEADER is a grep wrapper so you can apply any grep options and regular expressions to suit your needs.
HEADER -x "HTTP/3 200"

# Validate the response body, e.g. JSON body
# JQ is a jq wrapper so you can apply any jq options and jq expression to suit your needs.
JQ '.method=="POST"'
JQ '.form=={"foo":"bar","hello":"world"}'

TEST 2: another test case
# ...

# More test cases...

例子

APISIX

  1. 测试MTLS白名单
TEST 2: route-level mtls, skip mtls

ADMIN put /ssls/1 -d '{
    "cert": "'"$(<${BURL_ROOT}/examples/certs/server.crt)"'",
    "key": "'"$(<${BURL_ROOT}/examples/certs/server.key)"'",
    "snis": [
        "localhost"
    ],
    "client": {
        "ca": "'"$(<${BURL_ROOT}/examples/certs/ca.crt)"'",
        "depth": 10,
        "skip_mtls_uri_regex": [
            "/httpbin/get"
        ]
    }
}'

sleep 1

REQ /httpbin/get --http3-only

# validate the response headers
HEADER -x "HTTP/3 200"

# validate the response body, e.g. JSON body
JQ '.headers["X-Forwarded-Host"] == "localhost"'
  1. 测试 HTTP/3 Alt-Svc
ADMIN put /ssls/1 -d '{
    "cert": "'"$(<${BURL_ROOT}/examples/certs/server.crt)"'",
    "key": "'"$(<${BURL_ROOT}/examples/certs/server.key)"'",
    "snis": [
        "localhost"
    ]
}'

ADMIN put /routes/1 -s -d '{
    "uri": "/httpbin/*",
    "upstream": {
        "scheme": "https",
        "type": "roundrobin",
        "nodes": {
            "nghttp2.org": 1
        }
    }
}'



TEST 1: check if alt-svc works

altsvc_cache=$(mktemp)
GC "rm -f ${altsvc_cache}"

REQ /httpbin/get -k --alt-svc ${altsvc_cache}
HEADER -x "HTTP/1.1 200 OK"

REQ /httpbin/get -k --alt-svc ${altsvc_cache}
HEADER -x "HTTP/3 200"

SOAP

向 Web 服务发送 SOAP 请求并验证响应。

使用表达式构造 JSON 输入jo并验证 JSON 输出jq。

由 Python zeep.提供支持。

TEST 1: test a simple Web Service: Add two numbers: 1+2==3

SOAP_REQ \
    'https://ecs.syr.edu/faculty/fawcett/Handouts/cse775/code/calcWebService/Calc.asmx?WSDL' \
    Add `jo a=1 b=2` '.==3'

XML

Powered by xmltodict.

TEST 2: GET XML

# send request
REQ /httpbin/xml

# validate the response headers
HEADER -x "HTTP/1.1 200 OK"
HEADER -x "Content-Type: application/xml"

# validate the response XML body
XML '.slideshow["@author"]=="Yours Truly"'

结论

我认为HTTP测试框架并不难,不需要使用高级编程语言来实现。DSL实际上是框架实现和表示之间毫无意义的鸿沟,因为我们需要承担翻译成本,特别是对于编译型编程语言,并且对于测试人员来说,学习它是一种负担。那么为什么不统一它们并编写脚本呢?借助 bash(几乎所有操作系统中日常使用的标准 shell)和curl,我们可以轻松处理所有测试工作。

欢迎大家讨论并贡献burl:

https://github.com/kingluo/burl

评论

暂无评论