# 27 | test::nginx 包罗万象的测试方法 你好，我是温铭。 通过上节课的学习，你已经对 `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 库，并调用函数来做白盒测试。下面是节选的一段测试代码，并不能完整运行。它来自一个真实的开源项目，如果你对此有兴趣，可以点击[链接](https://github.com/iresty/apisix/blob/master/t/plugin/key-auth.t#L11)查看完整的测试，也可以尝试在本机运行。 ``` === 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，你觉得有什么优势和劣势吗？欢迎留言和我探讨，也欢迎你把这篇文章分享出去，一起交流和思考。