NAME
Test::Nginx::Socket - Socket-backed test scaffold for the Nginx C modules
SYNOPSIS
use Test::Nginx::Socket;
plan tests => $Test::Nginx::Socket::RepeatEach * 2 * blocks();
run_tests();
__DATA__
=== TEST 1: sanity
--- config
location /echo {
echo_before_body hello;
echo world;
}
--- request
GET /echo
--- response_body
hello
world
--- error_code: 200
=== TEST 2: set Server
--- config
location /foo {
echo hi;
more_set_headers 'Server: Foo';
}
--- request
GET /foo
--- response_headers
Server: Foo
--- response_body
hi
=== TEST 3: clear Server
--- config
location /foo {
echo hi;
more_clear_headers 'Server: ';
}
--- request
GET /foo
--- response_headers_like
Server: nginx.*
--- response_body
hi
=== TEST 3: chunk size too small
--- config
chunkin on;
location /main {
echo_request_body;
}
--- more_headers
Transfer-Encoding: chunked
--- request eval
"POST /main
4\r
hello\r
0\r
\r
"
--- error_code: 400
--- response_body_like: 400 Bad RequestDESCRIPTION
This module provides a test scaffold based on non-blocking IO::Socket for automated testing in Nginx C module development.
This class inherits from Test::Base, thus bringing all its declarative power to the Nginx C module testing practices.
You need to terminate or kill any Nginx processes before running the test suite if you have changed the Nginx server binary. Normally it's as simple as
killall nginx
PATH=/path/to/your/nginx-with-memc-module:$PATH prove -r tThis module will create a temporary server root under t/servroot/ of the current working directory and starts and uses the nginx executable in the PATH environment.
You will often want to look into t/servroot/logs/error.log when things go wrong ;)
Sections supported
The following sections are supported:
config
Content of this section will be included in the "server" part of the generated config file. This is the place where you want to put the "location" directive enabling the module you want to test. Example: location /echo { echo_before_body hello; echo world; }
Sometimes you simply don't want to bother copying ten times the same configuration for the ten tests you want to run against your module. One way to do this is to write a config section only for the first test in your .t file. All subsequent tests will re-use the same config. Please note that this depends on the order of test, so you should run prove with variable TEST_NGINX_NO_SHUFFLE=1 (see below for more on this variable).
Please note that config section goes through environment variable expansion provided the variables to expand start with TEST_NGINX. So, the following is a perfectly legal (provided TEST_NGINX_HTML_DIR is set correctly): location /main { echo_subrequest POST /sub -f $TEST_NGINX_HTML_DIR/blah.txt; }
http_config
Content of this section will be included in the "http" part of the generated config file. This is the place where you want to put the "upstream" directive you might want to test. Example: upstream database { postgres_server 127.0.0.1:$TEST_NGINX_POSTGRESQL_PORT dbname=ngx_test user=ngx_test password=wrong_pass; }
As you guessed from the example above, this section goes through environment variable expansion (variables have to start with TEST_NGINX).
main_config
Content of this section will be included in the "main" part of the generated config file. This is very rarely used, except if you are testing nginx core itself.
This section goes through environment variable expansion (variables have to start with TEST_NGINX).
request
This is probably the most important section. It defines the request(s) you are going to send to the nginx server. It offers a pretty powerful grammar which we are going to walk through one example at a time.
In its most basic form, this section looks like that: --- request GET
This will just do a GET request on the root (i.e. /) of the server using HTTP/1.1.
Of course, you might want to test something else than the root of your web server and even use a different version of HTTP. This is possible: --- request GET /foo HTTP/1.0
Please note that specifying HTTP/1.0 will not prevent Test::Nginx from sending the Host header. Actually Test::Nginx always sends 2 headers: Host (with value localhost) and Connection (with value Close for simple requests and keep-alive for all but the last pipelined_request).
You can also add a content to your request: --- request POST /foo Hello world
Test::Nginx will automatically calculate the content length and add the corresponding header for you.
This being said, as soon as you want to POST real data, you will be interested in using the more_headers section and using the power of Test::Base filters to urlencode the content you are sending. Which gives us a slightly more realistic example: --- more_headers Content-type: application/x-www-form-urlencoded --- request eval use URI::Escape; "POST /rrd/foo value=".uri_escape("N:12345")
Sometimes a test is more than one request. Typically you want to POST some data and make sure the data has been taken into account with a GET. You can do it using arrays: --- request eval ["POST /users name=foo", "GET /users/foo"]
This way, REST-like interfaces are pretty easy to test.
When you develop nifty nginx modules you will eventually want to test things with buffers and "weird" network conditions. This is where you split your request into network packets: --- request eval [["POST /users\nna", "me=foo"]]
Here, Test::Nginx will first send the request line, the headers it automatically added for you and the first two letters of the body ("na" in our example) in ONE network packet. Then, it will send the next packet (here it's "me=foo"). When we talk about packets here, this is nto exactly correct as there is no way to guarantee the behavior of the TCP/IP stack. What Test::Nginx can guarantee is that this will result in two calls to syswrite.
A good way to make almost sure the two calls result in two packets is to introduce a delay (let's say 2 seconds)before sending the second packet: --- request eval [["POST /users\nna", {value => "me=foo", delay_before => 2}]]
Of course, everything can be combined till your brain starts boiling ;) : --- request eval use URI::Escape; my $val="value=".uri_escape("N:12346"); [["POST /rrd/foo ".substr($val, 0, 6), {value => substr($val, 6, 5), delay_before=>5}, substr($val, 11)], "GET /rrd/foo"]
request_eval
Use of this section is deprecated and tests using it should replace it with a request section with an eval filter. More explicitly: --- request_eval "POST /echo_body hello\x00\x01\x02 world\x03\x04\xff"
should be replaced by: --- request eval "POST /echo_body hello\x00\x01\x02 world\x03\x04\xff"
more_headers
Adds the content of this section as headers to the request being sent. Example: --- more_headers X-Foo: blah
This will add X-Foo: blah to the request (on top of the automatically generated headers like Host, Connection and potentially Content-Length).
response_body
The expected value for the body of the submitted request. --- response_body hello
If the test is made of multiple requests, then the response_body MUST be an array and each request MUST return the corresponding expected body: --- request eval ["GET /hello", "GET /world"] --- response_body eval ["hello", "world"]
response_body_eval
Use of this section is deprecated and tests using it should replace it with a request section with an eval filter. Therefore: --- response_body_eval "hello\x00\x01\x02 world\x03\x04\xff"
should be replaced by: --- response_body eval "hello\x00\x01\x02 world\x03\x04\xff"
response_body_like
The body returned by the request MUST match the pattern provided by this section. Example: --- response_body_like ^elapsed 0\.00[0-5] sec\.$
If the test is made of multiple requests, then response_body_like MUST be an array and each request MUST match the corresponding pattern.
response_headers
The headers specified in this section are in the response sent by nginx. --- response_headers Content-Type: application/x-resty-dbd-stream
Of course, you can specify many headers in this section: --- response_headers X-Resty-DBD-Module: Content-Type: application/x-resty-dbd-stream
The test will be successful only if all headers are found in the response with the appropriate values.
If the test is made of multiple requests, then response_headers MUST be an array and each element of the array is checked against the response to the corresponding request.
response_headers_like
The value of the headers returned by nginx match the patterns. --- response_headers_like X-Resty-DBD-Module: ngx_drizzle \d+\.\d+\.\d+ Content-Type: application/x-resty-dbd-stream
This will check that the response's Content-Type is application/x-resty-dbd-stream and that the X-Resty-DBD-Module matches ngx_drizzle \d+\.\d+\.\d+.
The test will be successful only if all headers are found in the response and if the values match the patterns.
If the test is made of multiple requests, then response_headers_like MUST be an array and each element of the array is checked against the response to the corresponding request.
raw_response_headers_like
Checks the headers part of the response against this pattern. This is particularly useful when you want to write tests of redirect functions that are not bound to the value of the port your nginx server (under test) is listening to: --- raw_response_headers_like: Location: http://localhost(?::\d+)?/foo\r\n
As usual, if the test is made of multiple requests, then raw_response_headers_like MUST be an array.
error_code
The expected value of the HTTP response code. If not set, this is assumed to be 200. But you can expect other things such as a redirect: --- error_code: 302
If the test is made of multiple requests, then error_code MUST be an array with the expected value for the response status of each request in the test.
raw_request
The exact request to send to nginx. This is useful when you want to test soem behaviors that are not available with "request" such as an erroneous Content-Length header or splitting packets right in the middle of headers: --- raw_request eval ["POST /rrd/taratata HTTP/1.1\r Host: localhost\r Connection: Close\r Content-Type: application/", "x-www-form-urlencoded\r Content-Length:15\r\n\r\nvalue=N%3A12345"]
This can also be useful to tests "invalid" request lines: --- raw_request GET /foo HTTP/2.0 THE_FUTURE_IS_NOW
user_files
With this section you can create a file that will be copied in the html directory of the nginx server under test. For example: --- user_files >>> blah.txt Hello, world
will create a file named blah.txt in the html directory of the nginx server tested. The file will contain the text "Hello, world".
skip_nginx
skip_nginx2
Both string scalar and string arrays are supported as values.
raw_request_middle_delay
Delay in sec between sending successive packets in the "raw_request" array value. Also used when a request is split in packets.
Samples
You'll find live samples in the following Nginx 3rd-party modules:
- ngx_echo
- ngx_chunkin
- ngx_memc
- ngx_drizzle
- ngx_rds_json
- ngx_xss
- ngx_srcache
- ngx_lua
- ngx_set_misc
- ngx_array_var
- ngx_form_input
- ngx_iconv
- ngx_set_cconv
- ngx_postgres
- ngx_coolkit
SOURCE REPOSITORY
This module has a Git repository on Github, which has access for all.
http://github.com/agentzh/test-nginxIf you want a commit bit, feel free to drop me a line.
AUTHOR
agentzh (章亦春) <agentzh@gmail.com>
COPYRIGHT & LICENSE
Copyright (c) 2009-2011, Taobao Inc., Alibaba Group (http://www.taobao.com).
Copyright (c) 2009-2011, agentzh <agentzh@gmail.com>.
This module is licensed under the terms of the BSD license.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the Taobao Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.