source: mod_gnutls/test/README @ 5d9f34e

debian/masterdebian/stretch-backportsjessie-backportsupstream
Last change on this file since 5d9f34e was 5d9f34e, checked in by Thomas Klute <thomas2.klute@…>, 4 years ago

configure: Check if flock supports --timeout

This builds on the manual disable ("--disable-flock", see commit
412ee84200f0b47786f9ff80ff05835dc6310f76) but does not require any
user action. This should fix the

flock: cannot set up timer: Function not implemented
./runtests failed at line 176!

problem seen on Debian GNU/Hurd without any change to the packaging.

  • Property mode set to 100644
File size: 5.5 KB
RevLine 
[4b53371]1Unit Tests for Apache's mod_gnutls
2==================================
3
[26081ce]4Authors: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
5         Thomas Klute <thomas2.klute@uni-dortmund.de>
[4b53371]6
7There are a lot of ways that a TLS-capable web server can go wrong.  I
8want to at least test for some basic/common configurations.
9
10
11Running the tests
12=================
13
[c3bee83]14From the top level of the source, or from test/ (where this README is),
[0f5c9e1]15just run:
[4b53371]16
[c3bee83]17  make check
[4b53371]18
[c3bee83]19from test/. You can also run specific test cases by passing their
20script names to make in the TESTS variable:
[4b53371]21
[c3bee83]22  TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
[4b53371]23
24This should be handy when you're just trying to experiment with a new
25test and don't want to wait for the full test suite to run.
26
[dff57b4]27The default configuration assumes that a loopback device with IPv4 and
28IPv6 support is available (TEST_IP="[::1] 127.0.0.1") and that
29TEST_HOST="localhost" resolves to at least one of these addresses. If
30this does not apply to your system, you can pass different values to
31./configure, e.g. to use IPv4 only:
[26081ce]32
33  TEST_HOST="localhost" TEST_IP="127.0.0.1" ./configure
[4b53371]34
[fc8e463]35
[4b53371]36Adding a Test
37=============
38
39Please add more tests!
40
[e78bc78]41The simplest way to add a test is (from test/):
[4b53371]42
[c3bee83]43  ./newtest
[4b53371]44
[e78bc78]45This will prompt you for a simple name for the test and then copy a
46starting set of files from tests/00_basic, and create a script which
47you can add to TESTS in Makefile.am when your test is ready for
48inclusion in the test suite.
[4b53371]49
50
51Implementation
52==============
53
[c3bee83]54Each test consists of a script in test/ and a directory in
55test/tests/, which the test suite uses to spin up an isolated Apache
56instance or two (for proxy tests) and try to connect to it with
57gnutls-cli and make a simple HTTP 1.1 or 1.0 request.
[4b53371]58
[c3bee83]59Test directories usually contain the following files:
[4b53371]60
[c3bee83]61 * apache.conf -- Apache configuration to be used
[4b53371]62
[c3bee83]63 * gnutls-cli.args -- the arguments to pass to gnutls-cli
[4b53371]64
65 * input -- the full HTTP request (including the final blank line)
66
[c3bee83]67 * backend.conf [optional] -- Apache configuration for the proxy
68   backend server, if any
69
[4b53371]70 * output [optional] -- the lines of this file will be checked against
71   the same number of lines at the end of the output produced by the
[c3bee83]72   gnutls-cli process. "Date" and "Server" headers are filtered from
73   the response because they are expected to change between runs
74   (date) or builds (server version).
[4b53371]75
76 * fail.server [optional] -- if this file exists, it means we expect
77   the web server to fail to even start due to some serious
78   configuration problem.
79
80 * fail.client [optional] -- if this file exists, it means we expect
81   the client to fail to fetch its file.  If you already have
82   fail.server, do not also specify this; we know that a failed server
83   should result in a failed file retrieval.
84
[c3bee83]85The "runtests" script is used to start one Apache instance and send a
86request based on the files described above. Note that some tests take
87additional steps, e.g. starting another server to act as proxy
88backend, and there is no technical requirement to use "runtests".
89
[b21bf4f]90By default (if "unshare" is available and has the permissions required
91to create network and user namespaces), each test case is run inside
92its own network namespace. This avoids address and port conflicts with
[c3bee83]93other tests as well has the host system.
94
95When writing your own tests, make sure to call netns_reexec (defined
96in common.bash) if you need to start any network services outside of
97runtests (which will create the namespace if it doesn't exist
98already). However, some architectures might not support namespaces, so
99traditional locking (using flock) and serial execution are still
100supported.
101
[4b53371]102
103Robustness and Tuning
104=====================
105
[c3bee83]106Here are some things that you might want to tune about the tests based
107on your expected setup (along with the variables that can be passed to
108"make check" to adjust them):
[4b53371]109
[c3bee83]110 * They need a functioning loopback device.
[4b53371]111
[c3bee83]112 * They expect (by default) to have port 9932 [TEST_PORT] available
[dff57b4]113   and open for connections on the addresses listed in TEST_IP.
[4b53371]114
[c3bee83]115 * Depending on the compile time configuration of the Apache binary
116   installed on your system you may need to load additional Apache
117   modules. The recommended way to do this is to drop a configuration
118   file into the test/apache-conf/ directory. Patches to detect such
119   situations and automatically configure the tests accordingly are
120   welcome.
121
122 * If a machine is particularly slow or under heavy load, it's
[4b53371]123   possible that these tests will fail for timing
[c3bee83]124   reasons. [TEST_QUERY_DELAY (seconds for the HTTP request to be sent
[34e5dc7]125   and responded to)]
[f9f184f]126
[c3bee83]127The first two of these issues are avoided when the tests are isolated
128using network namespaces, which is the default (see "Implementation"
[b21bf4f]129above). The ./configure script tries to detect if namespaces can be
130used (some Linux distributions disable them for unprivileged
131users). If this detection returns a false positive or you do not want
132to use namespace isolation for some other reason, you can run
133configure with the --disable-test-namespaces option.
[c3bee83]134
[f9f184f]135In some situations you may want to see the exact environment as
136configured by make, e.g. if you want to manually run an Apache
137instance with Valgrind using the same configuration as a test
138case. Use "make show-test-env" to dump AM_TESTS_ENVIRONMENT to stdout.
[c3bee83]139
140If you are building on an exotic architecture which does not support
[5d9f34e]141flock (or timeouts using flock -w), ./configure should detect that and
142disable locking, or you can disable it manually by passing
[c3bee83]143"--disable-flock" to ./configure. This will force serial execution of
144tests, including environment setup.
Note: See TracBrowser for help on using the repository browser.