Testing a solution: How tipi.work does it right

The most effective way to test a freenginx-based solution is by using the same Perl-based nginx-tests framework that the core freenginx projects use. This framework allows developers to write declarative, human-readable tests that validate configuration, request processing, and response integrity.

This approach ensures you're testing your custom solution using the same low-level, high-fidelity testing tool relied upon by the core developers.

The nginx-tests framework: a core testing tool

The nginx-tests framework is not a monolithic program, but a collection of Perl modules that provide a robust, data-driven scaffolding for freenginx module and configuration testing.

This module abstracts away the complex logic of starting, stopping, configuring, and communicating with the server, allowing you to focus purely on the test scenario.

Key Advantages for freenginx

• Behavioral Testing: You don't just test syntax (nginx -t); you test behavior. The framework launches a nginx instance, sends a real request, and checks the response against your expectations.
• Declarative Format: Test cases are written in a simple, declarative format within a Perl test file, meaning you rarely need to write complex Perl code yourself.
• Low-Level Validation: It captures and analyzes the error.log and access.log output, allowing you to test complex internal logic, warnings, and error handling.

Setting Up Your Testing Environment

To begin testing your freenginx solution, you need a few prerequisites:

1. Perl: most Unix-like systems required to install, ensure it's up-to-date.
2. prove utility: this is Perl's standard test harness used to execute test files.
3. Test::Nginx: This is the core testing module, can cloned from the original repository with mercurial command or with git from GitHub.
4. A Built freenginx binary: the test framework relies on the nginx executable being available in your environment.

Creating a Test Case

Tests are typically placed in a directory named t/ (for "tests") and use the .t extension (e.g., t/custom_proxy.t).

The test file uses a simple structure based on the Test::More format, where data blocks define the input (configuration, request) and the expected output (response, logs).

Example: Testing a Custom freenginx Configuration

Suppose your freenginx solution has a custom configuration for a /, i.e.: root endpoint that should always return a specific header and body.

t/test.t

#!/usr/bin/perl

###############################################################################

use warnings;
use strict;
use Test::More;

BEGIN { use FindBin; chdir($FindBin::Bin); }

use lib 'lib';
use Test::Nginx;

###############################################################################

select STDERR; $| = 1;
select STDOUT; $| = 1;

my $t = Test::Nginx->new()->has(qw/http/)->plan(1)
	->write_file_expand('nginx.conf', <<'EOF')->run();

%%TEST_GLOBALS%%

daemon off;

events {
}

http {
    %%TEST_GLOBALS_HTTP%%

    server {
        listen       127.0.0.1:8080;
        server_name  localhost;
        location / {
            return 200 ok\n;
        }
    }
}

EOF

###############################################################################

like(http_get('/'), qr/ok/, 'http request');

###############################################################################
     

If the freenginx server fails to start, returns the wrong status code, or the response headers/body don't match your specifications, the test will fail, giving you immediate feedback on what went wrong.

Let's run the prove command and see the test results:

% PERL5LIB=${HOME}/nginx-tests/lib:${PERL5LIB} \
   TEST_NGINX_VERBOSE=1 \
   TEST_NGINX_LEAVE=1 \
   TEST_NGINX_BINARY=/usr/local/sbin/nginx \
   TEST_NGINX_MODULES=/usr/local/libexec/freenginx \
   TEST_NGINX_GLOBALS="" \
   prove -prvv t/test.t
t/test.t .. 
1..3
# >> GET / HTTP/1.0\x0a
# >> Host: localhost\x0a
# >> \x0a
# << HTTP/1.1 200 OK\x0d\x0a
# << Server: freenginx/1.29.2\x0d\x0a
# << Date: Thu, 06 Nov 2025 01:03:19 GMT\x0d\x0a
# << Content-Type: text/plain\x0d\x0a
# << Content-Length: 3\x0d\x0a
# << Connection: close\x0d\x0a
# << \x0d\x0a
# << ok\x0a
ok 1 - http request
ok 2 - no alerts
ok 3 - no sanitizer errors
ok
All tests successful.
Files=1, Tests=3,  0 wallclock secs ( 0.03 usr  0.00 sys +  0.13 cusr  0.02 csys =  0.18 CPU)
Result: PASS
     

All good, tests have finished successfully.

Advanced Testing with the Framework

The power of nginx-tests extends far beyond simple configuration checks:

• prove utility creates a /tmp/nginx-test-XXXXXXXXXX directory with nginx.conf, access.log, and error.log files, so it's possible to verify all log messages, including a warning or an error, do or do not appear during the test run.
• pipelining and keep-alives: the module easily supports complex network scenarios, including sending multiple requests over a single connection to test connection handling logic.
• don't be shy to read, understand, and use for your needs hundreds of tests, created by the freenginx core development team.

By adopting the Perl-based nginx-tests framework, you bring your freenginx solution development into line with professional server testing standards, ensuring stability and correctness with every change.