README.md
1# NAME
2
3Test::Nginx - Data-driven test scaffold for Nginx C module and Nginx/OpenResty-based libraries and applications
4
5Table of Contents
6=================
7
8* [NAME](#name)
9* [DESCRIPTION](#description)
10* [User Guide](#user-guide)
11* [Nginx C modules that use Test::Nginx to drive their test suites](#nginx-c-modules-that-use-testnginx-to-drive-their-test-suites)
12* [INSTALLATION](#installation)
13* [SOURCE REPOSITORY](#source-repository)
14* [DEBIAN PACKAGES](#debian-packages)
15* [Community](#community)
16 * [English Mailing List](#english-mailing-list)
17 * [Chinese Mailing List](#chinese-mailing-list)
18* [AUTHORS](#authors)
19* [COPYRIGHT & LICENSE](#copyright--license)
20* [SEE ALSO](#see-also)
21
22# DESCRIPTION
23
24This distribution provides two testing modules for Nginx C module development:
25
26- [Test::Nginx::Socket](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ASocket) (This is highly recommended.)
27
28 This library also has the following subclasses:
29
30 - [Test::Nginx::Socket::Lua](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ASocket%3A%3ALua)
31 - [Test::Nginx::Socket::Lua::Stream](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ASocket%3A%3ALua%3A%3AStream)
32 - [Test::Nginx::Socket::Lua::Dgram](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ASocket%3A%3ALua%3A%3ADgram)
33
34- [Test::Nginx::LWP](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ALWP) (This is obsolete.)
35
36All of them are based on [Test::Base](https://metacpan.org/pod/Test%3A%3ABase).
37
38Usually, [Test::Nginx::Socket](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ASocket) is preferred because it works on a much lower
39level and not that fault tolerant like [Test::Nginx::LWP](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ALWP).
40
41Also, a lot of connection hang issues (like wrong `r->main->count` value in nginx
420.8.x) can only be captured by [Test::Nginx::Socket](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ASocket) because Perl's [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent) client
43will close the connection itself which will conceal such issues from
44the testers.
45
46Test::Nginx automatically starts an nginx instance (from the `PATH` env)
47rooted at t/servroot/ and the default config template makes this nginx
48instance listen on the port `1984` by default. One can specify a different
49port number by setting his port number to the `TEST_NGINX_PORT` environment,
50as in
51
52 export TEST_NGINX_PORT=1989
53
54# User Guide
55
56You can find a comprehensive user guide on this test framework in my upcoming book "Programming OpenResty":
57
58[https://openresty.gitbooks.io/programming-openresty/content/testing/index.html](https://openresty.gitbooks.io/programming-openresty/content/testing/index.html)
59
60# Nginx C modules that use Test::Nginx to drive their test suites
61
62- ngx\_echo
63
64 [https://github.com/openresty/echo-nginx-module](https://github.com/openresty/echo-nginx-module)
65
66- ngx\_headers\_more
67
68 [https://github.com/openresty/headers-more-nginx-module](https://github.com/openresty/headers-more-nginx-module)
69
70- ngx\_chunkin
71
72 [http://wiki.nginx.org/NginxHttpChunkinModule](http://wiki.nginx.org/NginxHttpChunkinModule)
73
74- ngx\_memc
75
76 [http://wiki.nginx.org/NginxHttpMemcModule](http://wiki.nginx.org/NginxHttpMemcModule)
77
78- ngx\_drizzle
79
80 [https://github.com/openresty/drizzle-nginx-module](https://github.com/openresty/drizzle-nginx-module)
81
82- ngx\_rds\_json
83
84 [https://github.com/openresty/rds-json-nginx-module](https://github.com/openresty/rds-json-nginx-module)
85
86- ngx\_rds\_csv
87
88 [https://github.com/openresty/rds-csv-nginx-module](https://github.com/openresty/rds-csv-nginx-module)
89
90- ngx\_xss
91
92 [https://github.com/openresty/xss-nginx-module](https://github.com/openresty/xss-nginx-module)
93
94- ngx\_srcache
95
96 [https://github.com/openresty/srcache-nginx-module](https://github.com/openresty/srcache-nginx-module)
97
98- ngx\_lua
99
100 [https://github.com/openresty/lua-nginx-module](https://github.com/openresty/lua-nginx-module)
101
102- ngx\_set\_misc
103
104 [https://github.com/openresty/set-misc-nginx-module](https://github.com/openresty/set-misc-nginx-module)
105
106- ngx\_array\_var
107
108 [https://github.com/openresty/array-var-nginx-module](https://github.com/openresty/array-var-nginx-module)
109
110- ngx\_form\_input
111
112 [https://github.com/calio/form-input-nginx-module](https://github.com/calio/form-input-nginx-module)
113
114- ngx\_iconv
115
116 [https://github.com/calio/iconv-nginx-module](https://github.com/calio/iconv-nginx-module)
117
118- ngx\_set\_cconv
119
120 [https://github.com/liseen/set-cconv-nginx-module](https://github.com/liseen/set-cconv-nginx-module)
121
122- ngx\_postgres
123
124 [https://github.com/FRiCKLE/ngx\_postgres](https://github.com/FRiCKLE/ngx_postgres)
125
126- ngx\_coolkit
127
128 [https://github.com/FRiCKLE/ngx\_coolkit](https://github.com/FRiCKLE/ngx_coolkit)
129
130- Naxsi
131
132 [https://github.com/nbs-system/naxsi](https://github.com/nbs-system/naxsi)
133
134- ngx\_shibboleth
135
136 [https://github.com/nginx-shib/nginx-http-shibboleth](https://github.com/nginx-shib/nginx-http-shibboleth)
137
138[Back to TOC](#table-of-contents)
139
140# INSTALLATION
141
142If you have \`cpan\` installed, you can simply run the command to install this module:
143
144 sudo cpan Test::Nginx
145
146If you want to install from the source code directory directly, you can run
147
148 sudo cpan .
149
150If you prefer `cpanm` to `cpan` (like I do!), you can replace `cpan` in the commands above with `cpanm`.
151
152Otherwise you can install this module in the good old way below:
153
154 perl Makefile.PL
155 make
156 sudo make install
157
158[Back to TOC](#table-of-contents)
159
160# SOURCE REPOSITORY
161
162This module has a Git repository on Github, which has access for all.
163
164[https://github.com/openresty/test-nginx](https://github.com/openresty/test-nginx)
165
166If you want a commit bit, feel free to drop me a line.
167
168[Back to TOC](#table-of-contents)
169
170# DEBIAN PACKAGES
171
172António P. P. Almeida is maintaining a Debian package for this module
173in his Debian repository: [http://debian.perusio.net](http://debian.perusio.net)
174
175[Back to TOC](#table-of-contents)
176
177# Community
178
179## English Mailing List
180
181The `openresty-en` mailing list is for English speakers: [https://groups.google.com/group/openresty-en](https://groups.google.com/group/openresty-en)
182
183[Back to TOC](#table-of-contents)
184
185## Chinese Mailing List
186
187The `openresty` mailing list is for Chinese speakers: [https://groups.google.com/group/openresty](https://groups.google.com/group/openresty)
188
189[Back to TOC](#table-of-contents)
190
191# AUTHORS
192
193Yichun Zhang (agentzh) `<agentzh@gmail.com>`, OpenResty Inc.
194
195Antoine BONAVITA `<antoine.bonavita@gmail.com>`
196
197[Back to TOC](#table-of-contents)
198
199# COPYRIGHT & LICENSE
200
201Copyright (c) 2009-2017, Yichun Zhang (agentzh) `<agentzh@gmail.com>`, OpenResty Inc.
202
203Copyright (c) 2011-2012, Antoine Bonavita `<antoine.bonavita@gmail.com>`.
204
205This module is licensed under the terms of the BSD license.
206
207Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
208
209- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
210- 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.
211- Neither the name of the authors nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
212
213THIS 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.
214
215[Back to TOC](#table-of-contents)
216
217# SEE ALSO
218
219[Test::Nginx::LWP](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ALWP), [Test::Nginx::Socket](https://metacpan.org/pod/Test%3A%3ANginx%3A%3ASocket), [Test::Base](https://metacpan.org/pod/Test%3A%3ABase).
220
221[Back to TOC](#table-of-contents)
222
223