source: mod_gnutls/test/README @ c3bee83

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

Update test suite documentation

Most updates are regarding network namespaces and flock usage, but
also added/updated a few other details.

  • Property mode set to 100644
File size: 5.1 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
35
36Adding a Test
37=============
38
39Please add more tests!
40
41The simplest way to add a test is (from test/):
42
43  ./newtest
44
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.
49
50
51Implementation
52==============
53
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.
58
59Test directories usually contain the following files:
60
61 * apache.conf -- Apache configuration to be used
62
63 * gnutls-cli.args -- the arguments to pass to gnutls-cli
64
65 * input -- the full HTTP request (including the final blank line)
66
67 * backend.conf [optional] -- Apache configuration for the proxy
68   backend server, if any
69
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
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).
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
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
90By default (if "unshare" is available and --disable-test-namespaces
91has NOT been passed to configure), each test case is run inside its
92own network namespace. This avoids address and port conflicts with
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
102
103Robustness and Tuning
104=====================
105
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):
109
110 * They need a functioning loopback device.
111
112 * They expect (by default) to have port 9932 [TEST_PORT] available
113   and open for connections on the addresses listed in TEST_IP.
114
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
123   possible that these tests will fail for timing
124   reasons. [TEST_QUERY_DELAY (seconds for the HTTP request to be sent
125   and responded to)]
126
127The first two of these issues are avoided when the tests are isolated
128using network namespaces, which is the default (see "Implementation"
129above).
130
131In some situations you may want to see the exact environment as
132configured by make, e.g. if you want to manually run an Apache
133instance with Valgrind using the same configuration as a test
134case. Use "make show-test-env" to dump AM_TESTS_ENVIRONMENT to stdout.
135
136If you are building on an exotic architecture which does not support
137flock (or timeouts using flock -w), you can disable it by passing
138"--disable-flock" to ./configure. This will force serial execution of
139tests, including environment setup.
Note: See TracBrowser for help on using the repository browser.