=====
nginx
=====

-----
DEP-8
-----

The package ships :doc:`autopkgtest` smoketesting.

autopkgtest is confused by e.g. nginx-light conflicting with
nginx-full, and has trouble properly reinstalling nginx between tests,
so you'll need the lxc or qemu method.

.. code-block:: bash

 autopkgtest -s -B . ../*.deb -- lxc autopkgtest-$DIST-amd64

TODO: check https://github.com/nginx/nginx-tests/


-------------------
ngx_http_lua_module
-------------------

ngx_http_lua_module (previously ngx_lua, or lua-nginx-module) is
bundled in ``debian/modules/`` up to bullseye included, then is
shipped in its own `libnginx-mod-http-lua
<https://tracker.debian.org/pkg/libnginx-mod-http-lua>`_ package.

There are basic examples at:
https://github.com/openresty/lua-nginx-module/

The test suite requires a separate test framework and an additional
module.

Note: bullseye (1.18.0, 2020) ships an older lua module (0.10.13,
2018), as newer versions require luajit which were not available on
all archs at the time (`#941917
<https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=941917>`_). Many
tests fail, which may be related to this desync. The suite is still
useful to run newly backported tests, or identify regressions in
working tests.

.. code-block:: bash

 # Test::Nginx (base test framework)
 apt install libtest-base-perl libtext-diff-perl libtest-longstring-perl libtest-lwp-useragent-perl libwww-perl
 git clone https://github.com/openresty/test-nginx
 cd test-nginx/
 # bullseye (>= 2018)
 git checkout v0.28
 perl Makefile.PL
 make
 
 # Install ngx_memc, required by the test framework's nginx.conf
 cd nginx-x.x.x/
 git clone https://github.com/openresty/memc-nginx-module debian/modules/memc-nginx-module
 # bullseye (>=1.18.0)
 (cd debian/modules/memc-nginx-module && git checkout ab68e851b88324b9bfbacfda90b0d5b5487962d2)
 # debian/rules: add to extras_configure_flags: --add-dynamic-module=$(MODULESDIR)/memc-nginx-module
 debian/rules binary
 cp -a ./debian/build-extras/objs/ngx_http_memc_module.so /usr/lib/nginx/modules/
 apt install memcached
 # remember to remove the module from the packaging...
 
 dpkg -i libnginx-mod-http-lua_*.deb

 # Attempt to load modules in the right order
 # (ndk_* and ngx_stream_module.so first)
 export TEST_NGINX_LOAD_MODULES=$(ls /usr/lib/nginx/modules/ndk_*; ls /usr/lib/nginx/modules/ngx_* | tac)
 #export TEST_NGINX_USE_STAP=1

 # Run tests
 debian/rules config.patch.http-lua
 cd debian/modules/http-lua/
 prove -I .../test-nginx/lib -r t
 prove -I .../test-nginx/lib t/020-subrequest.t
 prove -I .../test-nginx/lib t/016-resp-header.t

See also:
 * https://github.com/openresty/lua-nginx-module/#test-suite
 * https://github.com/openresty/lua-nginx-module/blob/master/util/build.sh
 * https://api7.ai/learning-center/openresty/little-known-usage-of-test-nginx (handling 'plan tests' count)

| Copyright (C) 2020, 2025  Sylvain Beucler