source: mod_gnutls/test/README @ 5fd0170

proxy-ticket
Last change on this file since 5fd0170 was 5fd0170, checked in by Fiona Klute <fiona.klute@…>, 6 months ago

Update outdated information in test/README

  • Property mode set to 100644
File size: 5.5 KB
Line 
1Unit Tests for Apache's mod_gnutls
2==================================
3
4Authors: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
5         Fiona Klute <fiona.klute@gmx.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 the directory containing this
50file):
51
52  ./newtest
53
54This will prompt you for a simple name for the test and then copy a
55starting set of files from tests/00_basic, and create a script which
56you can add to the test_scripts variable in Makefile.am when your test
57is ready for inclusion in the test suite. The files in the test
58directory must be added to EXTRA_DIST in tests/Makefile.am.
59
60
61Implementation
62==============
63
64Each test consists of a script in the directory containing this README
65and a directory in tests/, which the test suite uses to spin up an
66isolated Apache instance (or more, for tests that need a proxy or OCSP
67responder) and try to connect to it with gnutls-cli and make a simple
68HTTP 1.1 or 1.0 request.
69
70Test directories usually contain the following files:
71
72 * apache.conf -- Apache configuration to be used
73
74 * test.yml -- Defines the client connection(s) including parameters
75   for gnutls-cli, the request(s), and expected response(s)
76
77 * backend.conf [optional] -- Apache configuration for the proxy
78   backend server, if any
79
80 * ocsp.conf [optional] -- Apache configuration for the OCSP
81   responder, if any
82
83 * fail.server [optional] -- if this file exists, it means we expect
84   the web server to fail to even start due to some serious
85   configuration problem.
86
87 * hooks.py [optional] -- Defines hook functions that modify or
88   override the default behavior of runtest.py
89
90The "runtest.py" program is used to start the required services send a
91request (or more) based on the files described above. Note that
92currently some tests take additional steps in their test scripts,
93though hooks.py is the preferred mechanism.
94
95By default (if "unshare" is available and has the permissions required
96to create network and user namespaces), each test case is run inside
97its own network namespace. This avoids address and port conflicts with
98other tests as well has the host system. Otherwise the tests use a
99lock file to prevent port conflicts between themselves.
100
101When writing your own tests, make sure to call runtest.py through
102netns_py.bash like the current tests do to ensure compatibility with
103the namespace and lock file mechanisms.
104
105Robustness and Tuning
106=====================
107
108Here are some things that you might want to tune about the tests based
109on your expected setup (along with the variables that can be passed to
110"make check" to adjust them):
111
112 * They need a functioning loopback device.
113
114 * They expect to have ports 9932 (TEST_PORT as defined in
115   Makefile.am) through 9936 available for test services to bind to,
116   and open for connections on the addresses listed in TEST_IP.
117
118 * Depending on the compile time configuration of the Apache binary
119   installed on your system you may need to load additional Apache
120   modules. The recommended way to do this is to drop a configuration
121   file into the test/apache-conf/ directory. Patches to detect such
122   situations and automatically configure the tests accordingly are
123   welcome.
124
125 * If a machine is particularly slow or under heavy load, it's
126   possible that tests fail for timing reasons. [TEST_QUERY_TIMEOUT
127   (timeout for the HTTPS request in seconds)]
128
129The first two of these issues are avoided when the tests are isolated
130using network namespaces, which is the default (see "Implementation"
131above). The ./configure script tries to detect if namespaces can be
132used (some Linux distributions disable them for unprivileged
133users). If this detection returns a false positive or you do not want
134to use namespace isolation for some other reason, you can run
135configure with the --disable-test-namespaces option.
136
137In some situations you may want to see the exact environment as
138configured by make, e.g. if you want to manually run an Apache
139instance with Valgrind using the same configuration as a test
140case. Use "make show-test-env" to dump AM_TESTS_ENVIRONMENT to stdout.
141
142If you are building on an exotic architecture which does not support
143flock (or timeouts using flock -w), ./configure should detect that and
144disable locking, or you can disable it manually by passing
145"--disable-flock" to ./configure. This will force serial execution of
146tests, including environment setup.
Note: See TracBrowser for help on using the repository browser.