source: mod_gnutls/test/README.md @ 3deb86e

proxy-ticket
Last change on this file since 3deb86e was e971a2c, checked in by Fiona Klute <fiona.klute@…>, 11 months ago

Document supported test hooks

  • Property mode set to 100644
File size: 5.7 KB
Line 
1# Unit Tests for Apache's mod_gnutls
2
3Authors:
4Daniel Kahn Gillmor <dkg@fifthhorseman.net>,
5Fiona 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
11## Running the tests
12
13From the top level of the source, or from `test/` (where this README is),
14just run:
15
16    $ make check
17
18You can also run specific test cases by passing their script names to
19make in the `TESTS` variable:
20
21    $ TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
22
23This should be handy when you're just trying to experiment with a new
24test and don't want to wait for the full test suite to run.
25
26The default configuration assumes that a loopback device with IPv4 and
27IPv6 support is available (`TEST_IP="[::1] 127.0.0.1"`) and that
28`TEST_HOST="localhost"` resolves to at least one of these
29addresses. If this does not apply to your system, you can pass
30different values to `./configure`, e.g. to use IPv4 only:
31
32    $ TEST_HOST="localhost" TEST_IP="127.0.0.1" ./configure
33
34If tests fail due to expired certificates or PGP signatures, run
35
36    $ make mostlyclean
37
38to delete them and create fresh ones on the next test run. You could
39also use `make clean`, but in that case the keys will be deleted as
40well and have to be recreated, too, which takes more time.
41
42
43## Adding a Test
44
45Please add more tests!
46
47The simplest way to add a test is (from the directory containing this
48file):
49
50    $ ./newtest
51
52This will prompt you for a simple name for the test, copy a starting
53set of files from `tests/00_basic`, and create a script which you can
54add to the `test_scripts` variable in `Makefile.am` when your test is
55ready for inclusion in the test suite. The files in the test directory
56must be added to `EXTRA_DIST` in `tests/Makefile.am`.
57
58
59## Implementation
60
61Each test consists of a script in the directory containing this README
62and a directory in tests/, which the test suite uses to spin up an
63isolated Apache instance (or more, for tests that need a proxy or OCSP
64responder) and try to connect to it with gnutls-cli and make a simple
65HTTP 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* `test.yml` -- Defines the client connection(s) including parameters
72  for gnutls-cli, the request(s), and expected response(s)
73
74* `backend.conf` [optional] -- Apache configuration for the proxy
75  backend server, if any
76
77* `ocsp.conf` [optional] -- Apache configuration for the OCSP
78  responder, if any
79
80* `fail.server` [optional] -- if this file exists, it means we expect
81  the web server to fail to even start due to some serious
82  configuration problem.
83
84* `hooks.py` [optional] -- Defines hook functions that modify or
85  override the default behavior of `runtest.py`. Please see the module
86  documentation of [mgstest.hooks](./mgstest/hooks.py) for details.
87
88The [`runtest.py`](./runtest.py) program is used to start the required
89services send a request (or more) based on the files described
90above. Note that currently some tests take additional steps in their
91test scripts, though `hooks.py` is the preferred mechanism.
92
93By default (if the `unshare` command is available and has the
94permissions required to create network and user namespaces), each test
95case is run inside its own network namespace. This avoids address and
96port conflicts with other tests as well has the host system. Otherwise
97the tests use a lock file to prevent port conflicts between
98themselves.
99
100When writing your own tests, make sure to call `runtest.py` through
101`netns_py.bash` like the current tests do to ensure compatibility with
102the namespace and lock file mechanisms.
103
104## Robustness and Tuning
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 to have ports 9932 (`TEST_PORT` as defined in
113  `Makefile.am`) through 9936 available for test services to bind to,
114  and open for connections on the addresses listed in `TEST_IP`.
115
116* Depending on the compile time configuration of the Apache binary
117  installed on your system you may need to load additional Apache
118  modules. The recommended way to do this is to drop a configuration
119  file into the `apache-conf/` directory. Patches to detect such
120  situations and automatically configure the tests accordingly are
121  welcome.
122
123* If a machine is particularly slow or under heavy load, it's possible
124  that tests fail for timing reasons. [`TEST_QUERY_TIMEOUT` (timeout
125  for the HTTPS request in seconds)]
126
127The first two of these issues are avoided when the tests are isolated
128using network namespaces, which is the default (see "Implementation"
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.
134
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
139stdout. If you want to load the test environment into the current bash
140instance, you can use:
141
142    $ eval $(make show-test-env)
143
144If you are building on an exotic architecture which does not support
145flock (or timeouts using `flock -w`), `./configure` should detect that
146and disable locking, or you can disable it manually by passing
147`--disable-flock` to `./configure`. This will force serial execution
148of tests, including environment setup.
Note: See TracBrowser for help on using the repository browser.