source: mod_gnutls/test/README @ 339a49d

debian/masterdebian/stretch-backportsupstream
Last change on this file since 339a49d was 6c030c1, checked in by Thomas Klute <thomas2.klute@…>, 18 months ago

Test suite: Make timeouts for server locks and HTTPS requests configurable

If TEST_LOCK_WAIT or TEST_QUERY_TIMEOUT are provided at configure
time, their values are stored and used instead of the default.

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