source: mod_gnutls/test/README @ b47dc70

debian/master
Last change on this file since b47dc70 was 3c123cd, checked in by Fiona Klute <fiona.klute@…>, 20 months ago

Update my name, prepare changelog for the next release

  • Property mode set to 100644
File size: 5.7 KB
RevLine 
[4b53371]1Unit Tests for Apache's mod_gnutls
2==================================
3
[26081ce]4Authors: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
[3c123cd]5         Fiona Klute <fiona.klute@gmx.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
[7aeabcb]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
[fc8e463]43
[4b53371]44Adding a Test
45=============
46
47Please add more tests!
48
[e78bc78]49The simplest way to add a test is (from test/):
[4b53371]50
[c3bee83]51  ./newtest
[4b53371]52
[e78bc78]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.
[4b53371]57
58
59Implementation
60==============
61
[c3bee83]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.
[4b53371]66
[c3bee83]67Test directories usually contain the following files:
[4b53371]68
[c3bee83]69 * apache.conf -- Apache configuration to be used
[4b53371]70
[c3bee83]71 * gnutls-cli.args -- the arguments to pass to gnutls-cli
[4b53371]72
73 * input -- the full HTTP request (including the final blank line)
74
[c3bee83]75 * backend.conf [optional] -- Apache configuration for the proxy
76   backend server, if any
77
[4b53371]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
[c3bee83]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).
[4b53371]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
[c3bee83]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
[8ac7c0d]96backend, and at least one does not use "runtests" at all.
[c3bee83]97
[b21bf4f]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
[c3bee83]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
[4b53371]110
111Robustness and Tuning
112=====================
113
[c3bee83]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):
[4b53371]117
[c3bee83]118 * They need a functioning loopback device.
[4b53371]119
[c3bee83]120 * They expect (by default) to have port 9932 [TEST_PORT] available
[dff57b4]121   and open for connections on the addresses listed in TEST_IP.
[4b53371]122
[c3bee83]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
[4b53371]131   possible that these tests will fail for timing
[6c030c1]132   reasons. [TEST_QUERY_TIMEOUT (timeout for the HTTPS request in
133   seconds)]
[f9f184f]134
[c3bee83]135The first two of these issues are avoided when the tests are isolated
136using network namespaces, which is the default (see "Implementation"
[b21bf4f]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.
[c3bee83]142
[f9f184f]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.
[c3bee83]147
148If you are building on an exotic architecture which does not support
[5d9f34e]149flock (or timeouts using flock -w), ./configure should detect that and
150disable locking, or you can disable it manually by passing
[c3bee83]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.