Testing

There are no unit tests inside this repository. All functional tests live in nginx/nginx-tests, a separate Perl-based suite that exercises a real running nginx binary.

What nginx-tests is

A prove (Perl Test::Harness) suite where each .t file:

1. Generates a nginx.conf for a temporary working directory
2. Starts nginx with that config (TEST_NGINX_BINARY points at your build)
3. Drives traffic through it (HTTP, raw sockets, TLS, HTTP/2, HTTP/3, mail, stream)
4. Asserts on responses, log lines, exit codes
5. Tears the instance down

The harness handles port assignment, log capture, timeouts, and parallelism. Test files are named after the directive or feature they cover: http_proxy.t, http_ssl.t, stream_proxy.t, mail_smtp.t, quic.t, h2.t, etc.

Running the suite

git clone https://github.com/nginx/nginx-tests.git
cd nginx-tests
TEST_NGINX_BINARY=/abs/path/to/objs/nginx prove -j8 .

Useful environment variables:

Variable	What it does
TEST_NGINX_BINARY	Path to the nginx binary under test (required)
TEST_NGINX_MODULES	Path to a directory of .so dynamic modules
TEST_NGINX_GLOBALS	Extra directives injected into the main context
TEST_NGINX_GLOBALS_HTTP	Extra directives injected into the http context
TEST_NGINX_VERBOSE=1	Print the generated config and the running command
TEST_NGINX_LEAVE=1	Leave the test working directory after the run (for debug)
TEST_NGINX_UNSAFE=1	Allow tests that bind privileged ports
TEST_NGINX_CATLOG=1	Print error log on test failure

Running a single test

TEST_NGINX_BINARY=$(realpath ../nginx/objs/nginx) prove -v http_proxy.t

-v shows each subtest's name and pass/fail; combined with TEST_NGINX_VERBOSE=1 it prints the rendered config so you can copy it and reproduce manually.

What modules a test needs

Most tests start with plan(skip_all => '...') if a required module wasn't compiled in. To run TLS tests you need --with-http_ssl_module; HTTP/2 tests need --with-http_v2_module; HTTP/3 tests need --with-http_v3_module; mail tests need --with-mail; stream tests need --with-stream. A "build everything" debug configure is the simplest way to make prove . cover the full suite:

auto/configure --with-debug \
  --with-http_ssl_module --with-http_v2_module --with-http_v3_module \
  --with-stream --with-stream_ssl_module --with-mail --with-mail_ssl_module \
  --with-threads --with-file-aio
make -j$(nproc)

Writing a new test

A minimal test:

#!/usr/bin/perl

use warnings;
use strict;

use Test::More;

BEGIN { use FindBin; chdir($FindBin::Bin); }
use lib 'lib';
use Test::Nginx;

my $t = Test::Nginx->new()->has(qw/http proxy/)->plan(2);

$t->write_file_expand('nginx.conf', <<'EOF');
%%TEST_GLOBALS%%
events { }
http {
    %%TEST_GLOBALS_HTTP%%
    server {
        listen       127.0.0.1:8080;
        location /  { return 200 hello; }
    }
}
EOF

$t->run();

like(http_get('/'), qr/hello/, 'basic GET');
like(http_get('/'), qr/200 OK/, 'status line');

Conventions inside the suite:

• Test::Nginx (in lib/Test/Nginx.pm) provides new, has, plan, run, stop.
• http_get, http_head, http_post, http, IO::Socket::INET6 are the common request helpers.
• For TLS/HTTP/2/HTTP/3 there are Test::Nginx::HTTP2, Test::Nginx::HTTP3, Test::Nginx::Stream, etc.
• %%TEST_GLOBALS%% and %%TEST_GLOBALS_HTTP%% are macro placeholders the harness expands.

PRs that add a new feature should add a corresponding .t (or extend an existing one). Reviewers will ask.

Manual smoke tests

For debugging during development the fastest loop is:

make && ./objs/nginx -p $PWD -c conf/nginx.conf -g 'daemon off; error_log stderr debug;'
# in another shell
curl -v localhost:80

Combined with --with-debug, the error_log ... debug; directive emits an exhaustive trace of what nginx is doing per request.

Sanitizers

Nginx builds cleanly under AddressSanitizer and UndefinedBehaviorSanitizer. The conventional incantation:

auto/configure --with-debug --with-cc-opt='-O0 -g -fsanitize=address,undefined' --with-ld-opt='-fsanitize=address,undefined' ...
make

Run the test suite under the resulting binary the same way; ASAN abuse will show up in the error log.

Continuous integration

Public CI for this repo runs the lint-style workflows in .github/workflows/. The actual cross-platform compile + test matrix is handled by F5's external buildbot, which the buildbot.yml workflow calls into. Test results are not always visible in the GitHub PR UI; reviewers will mention failures explicitly.