27 | test::nginx 包罗万象的测试方法

Jul 26, 2019

27 | test::nginx 包罗万象的测试方法-极客时间



下载APP





关闭

讲堂部落提薪训练营云原生训练营架构实战营企业版极客商城兑换中心 App下载浏览器插件

渠道合作

推荐作者

27 | test::nginx 包罗万象的测试方法

2019-07-26 温铭来自北京

《OpenResty从入门到实战》

课程介绍



讲述：温铭

时长12:20大小11.29M



你好，我是温铭。
通过上节课的学习，你已经对 test::nginx 有了一个初步的认识，并运行了最简单的示例。不过，在实际的开源项目中，test::nginx 编写的测试案例显然要比示例代码复杂得多，也更加难以掌握，不然它也就称不上是拦路虎了。
在本节课中，我会带你来熟悉下 test::nginx 中经常用到的指令和测试方法，目的是让你可以看明白 OpenResty 项目中大部分的测试案例集，并有能力来编写更真实的测试案例。即使你还没有给 OpenResty 贡献过代码，但熟悉了 OpenResty 的测试框架，对于你平时工作中设计和编写测试案例，还是会有不少启发的。
test::nginx 的测试，本质上是根据每一个测试案例的配置，先去生成 nginx.conf，并启动一个 Nginx 进程；然后，模拟客户端发起请求，其中包含指定的请求体和请求头；紧接着，测试案例中的 Lua 代码会处理请求并作出响应，这时，test::nginx 解析响应体、响应头、错误日志等关键信息，并和测试配置做对比。如果发现不符，就报错退出，测试失败；否则就算成功。
test::nginx 中提供了很多 DSL 的原语，我按照 Nginx 配置、发送请求、处理响应、检查日志这个流程，做了一个简单的分类。这  20% 的功能可以覆盖 80% 的应用场景，所以你一定要牢牢掌握。至于其他更高级的原语和使用方法，我们留到下一节再来介绍。
Nginx 配置我们首先来看下 Nginx 配置。test::nginx 的原语中带有 config 这个关键字的，就和 Nginx 配置相关，比如上一节中提到的 config、stream_config、http_config 等。
它们的作用都是一样的，即在 Nginx 的不同上下文中，插入指定的 Nginx 配置。这些配置可以是 Nginx 指令，也可以是 content_by_lua_block 封装起来的 Lua 代码。
在做单元测试的时候，config 是最常用的原语，我们会在其中加载 Lua 库，并调用函数来做白盒测试。下面是节选的一段测试代码，并不能完整运行。它来自一个真实的开源项目，如果你对此有兴趣，可以点击链接查看完整的测试，也可以尝试在本机运行。
=== TEST 1: sanity
--- config
    location /t {
        content_by_lua_block {
            local plugin = require("apisix.plugins.key-auth")
            local ok, err = plugin.check_schema({key = 'test-key'})
            if not ok then
                ngx.say(err)
            end
            ngx.say("done")
        }
    }
这个测试案例的目的，是为了测试代码文件 plugins.key-auth 中， check_schema 这个函数能否正常工作。它在location /t 中使用 content_by_lua_block 这个 Nginx 指令，require 需要测试的模块，并直接调用需要检查的函数。
这就是在 test::nginx 进行白盒测试的通用手段。不过，只有这段配置自然是无法完成测试的，下面我们继续看下，如何发起客户端的请求。
发送请求模拟客户端发送请求，会涉及到不少的细节，所以，我们就先从最简单的发送单个请求入手吧。
request还是继续上面的测试案例，如果你想要单元测试的代码被运行，那就要发起一个 HTTP 请求，访问的地址是 config 中注明的 /t，正如下面的测试代码所示：
--- request
GET /t
这段代码在 request 原语中，发起了一个 GET 请求，地址是 /t。这里，我们并没有注明访问的 ip 地址、域名和端口，也没有指定是 HTTP 1.0 还是 HTTP 1.1，这些细节都被 test::nginx 隐藏了，你不用去关心。这就是 DSL 的好处之一——你只需要关心业务逻辑，不用被各种细节所打扰。
同时，这也提供了部分的灵活性。比如默认是 HTTP 1.1 的协议，如果你想测试 HTTP 1.0，也可以单独指定：
--- request
GET /t  HTTP/1.0
除了 GET 方法之外，POST 方法也是需要支持的。下面这个示例，可以 POST hello world 这个字符串到指定的地址：
--- request
POST /t  
hello world
同样的， test::nginx 在这里为你自动计算了请求体长度，并自动增加了 host 和 connection 这两个请求头，以保证这是一个正常的请求。
当然，出于可读性的考虑，你可以在其中增加注释。以 # 开头的，就会被识别为代码注释：
--- request
   # post request
POST /t  
hello world
request 还支持更为复杂和灵活的模式，那就是配合 eval 这个 filter，直接嵌入 perl 代码，毕竟 test::nginx 就是 perl 编写的。这种做法，类似于在 DSL 之外开了一个后门，如果当前的 DSL 原语都不能满足你的需求，那么 eval 这种直接执行 perl 代码的方法，就可以说是“终极武器”了。
关于 eval的用法，这里我们先看几个简单的例子，其他更复杂的，我们下节课继续介绍：
--- request eval
"POST /t
hello\x00\x01\x02
world\x03\x04\xff"
第一个例子中，我们用 eval 来指定不可打印的字符，这也是它的用处之一。双引号之间的内容，会被当做 perl 的字符串来处理后，再传给 request 来作为参数。
下面是一个更有趣的例子：
--- request eval
"POST /t\n" . "a" x 1024
不过，要看懂这个例子，需要懂一些 perl 的字符串知识，这里我简单提两句：
在 perl 中，我们用一个点号来表示字符串拼接，这是不是和 Lua 的两个点号有些类似呢？
用小写的 x 来表示字符的重复次数。比如上面的 "a" x 1024，就表示字符 a 重复 1024 次。
所以，第二个例子的含义是，用 POST 方法，向 /t 地址，发送包含 1024 个字符 a 的请求。
pipelined_requests了解完如何发送单个请求后，我们再来看下如何发送多个请求。在 test::nginx 中，你可以使用 pipelined_requests 这个原语，在同一个 keep-alive 的连接里面，依次发送多个请求：
--- pipelined_requests eval
["GET /hello", "GET /world", "GET /foo", "GET /bar"]
比如这个示例就会在同一个连接中，依次访问这 4 个接口。这样做会有两个好处：
第一是可以省去不少重复的测试代码，把 4 个测试案例压缩到一个测试案例中完成；
第二也是最重要的原因，你可以用流水线的请求，来检测代码逻辑在多次访问的情况下，是否会有异常。
你可能会奇怪，我依次写多个测试案例，那么执行的时候，代码也会被多次执行，不也可以覆盖上面的第二个问题吗？
其实，这就涉及到 test::nginx 的执行模式了，它并非像你想象中的那样去运转。事实上，在执行完每一个测试案例后， test::nginx 都会关闭当前的 Nginx 进程，自然的，内存中所有数据也都随之消失了。当运行下一个测试案例时，又会重新生成 nginx.conf，并启动新的 Nginx worker。这种机制是为了保证测试案例之间不会互相影响。
所以，当你要测试多个请求时，就需要用到 pipelined_requests 这个原语了。基于它，你可以模拟出限流、限速、限并发等多种情况，用更真实和复杂的场景来检测你的系统是否正常。这一点，我们也留在下节课继续拆解，因为它会涉及到多个指令和原语的配合。
repeat_each刚才我们提到了测试多个请求的情况，那么应该如何对同一个测试执行多次呢？
针对这个问题，test::nginx 提供了一个全局的设置：repeat_each。它其实是一个 perl 函数，默认情况下是 repeat_each(1)，表示测试案例只运行一次。所以之前的测试案例中，我们都没有去单独设置它。
自然，你可以在 run_test() 函数之前来设置它，比如将参数改为 2：
repeat_each(2);
run_tests();
那么，每个测试案例就都会被运行两次，以此类推。
more_headers聊完了请求体，我们再来看下请求头。上面我们提到，test::nginx 在发送请求的时候，默认会带上 host 和 connection 这两个请求头。那么其他的请求头如何设置呢？
其实，more_headers 就是专门做这件事儿的：
--- more_headers
X-Foo: blah
你可以用它来设置各种自定义的头。如果想设置多个头，那设置多行就可以了：
--- more_headers
X-Foo: 3
User-Agent: openresty
处理响应发送完请求后，test::nginx 中最重要的部分就来了，那就是处理响应，我们会在这里判断响应是否符合预期。这里我们分为 4 个部分依次介绍，分别是响应体、响应头、响应码和日志。
response_body与 request 原语对应的就是 response_body，下面是它们两个配置使用的例子：
=== TEST 1: sanity
--- config
    location /t {
        content_by_lua_block {
            ngx.say("hello")
        }
    }
--- request
GET /t
--- response_body
hello
这个测试案例，在响应体是 hello 的情况下会通过，其他情况就会报错。但如何返回体很长，我们怎么检测才合适呢？别着急，test::nginx 已经为你考虑好了，它支持用用正则表达式来检测响应体，比如下面这样的写法：
--- response_body_like
^he\w+$
这样你就可以对响应体进行非常灵活的检测了。不仅如此，test::nginx 还支持 unlike 的操作：
--- response_body_unlike
^he\w+$
这时候，如果响应体是hello，测试就不能通过了。
同样的思路，了解完单个请求的检测后，我们再来看下多个请求的检测。下面是配合 pipelined_requests 一起使用的示例：
--- pipelined_requests eval
["GET /hello", "GET /world", "GET /foo", "GET /bar"]
--- response_body eval
["hello", "world", "oo", "bar"]
当然，这里需要注意的是，你发送了多少个请求，就需要有多少个响应来对应。
response_headers第二个我们来说说响应头。响应头和请求头类似，每一行对应一个 header 的 key 和 value：
--- response_headers
X-RateLimit-Limit: 2
X-RateLimit-Remaining: 1
和响应体的检测一样，响应头也支持正则表达式和 unlike 操作，分别是 response_headers_like 、raw_response_headers_like 和 raw_response_headers_unlike。
error_code第三个来看响应码。响应码的检测支持直接的比较，同时也支持 like 操作，比如下面两个示例：
--- error_code: 302
--- error_code_like: ^(?:500)?$
而对于多个请求的情况，error_code 自然也需要检测多次：
--- pipelined_requests eval
["GET /hello", "GET /hello", "GET /hello", "GET /hello"]
--- error_code eval
[200, 200, 503, 503]
error_log最后一个检测项，就是错误日志了。在大部分的测试案例中，都不会产生错误日志。我们可以用 no_error_log 来检测：
--- no_error_log
[error]
在上面的例子中，如果 Nginx 的错误日志 error.log 中，出现 [error] 这个字符串，测试就会失败。这是一个很常用的功能，建议在你正常的测试中，都加上对错误日志的检测。
自然，另一方面，我们也需要编写很多异常的测试案例，以便验证在出错的情况下，我们的代码是否正常处理。这种情况下，我们就需要错误日志中出现指定的字符串，这就是 error_log 的用武之地了：
--- error_log
hello world
上面这段配置，其实就在检测 error.log 中是否出现了 hello world。当然，你可以在其中，用 eval 嵌入 perl 代码的方式，来实现正则表达式的检测，比如下面这样的写法：
--- error_log eval
qr/\[notice\] .*?  \d+ hello world/
写在最后今天，我们学习的是如何在 test::nginx 中发送请求和检测响应，包含了 body、header、响应码和错误日志等。通过这些原语的组合，你可以实现比较完整的测试案例集。
最后，给你留一个思考题：test::nginx 这种抽象一层的 DSL，你觉得有什么优势和劣势吗？欢迎留言和我探讨，也欢迎你把这篇文章分享出去，一起交流和思考。

分享给需要的人，Ta购买本课程，你将得18元

生成海报并分享

赞 2

提建议

26 | 代码贡献者的拦路虎：test::nginx 简介

28 | test::nginx 还可以这样用？

 写留言

精选留言(5)

yousa
2019-11-23
test nginx可以构造http2请求吗
1
Geek_584aa7
2022-06-18
请问这个测试框架支持并发执行吗？还有如果要对非error日志断言的话可以用其他什么方式？比如我要对自定义路径下的某个日志断言要怎么处理？
一只苦逼
2020-03-24
打卡
wusiration
2019-07-26
优势是抽象程度高，编写测试用例更为简单；劣势是有一定学习成本；
许童童
2019-07-26
优势是编写测试用例更方便，效率更高。劣势是需要学习成本，框架层面的变动很麻烦。

