source: mod_gnutls/test/README.md @ d2f2f62

proxy-ticket
Last change on this file since d2f2f62 was 883efd2, checked in by Fiona Klute <fiona.klute@…>, 9 months ago

Document how to override which Valgrind suppressions to use

  • Property mode set to 100644
File size: 6.6 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```bash
17$ make check
18```
19
20You can also run specific test cases by passing their script names to
21make in the `TESTS` variable:
22
23```bash
24$ TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
25```
26
27This should be handy when you're just trying to experiment with a new
28test and don't want to wait for the full test suite to run. Note that
29the test scripts are generated by `make`, using the names of
30directories in `tests/`.
31
32The default configuration assumes that a loopback device with IPv4 and
33IPv6 support is available (`TEST_IP="[::1] 127.0.0.1"`) and that
34`TEST_HOST="localhost"` resolves to both of these addresses. If this
35does not apply to your system, you can pass different values to
36`./configure`, e.g. to use IPv4 only:
37
38```bash
39$ TEST_HOST="localhost" TEST_IP="127.0.0.1" ./configure
40```
41
42If tests fail due to expired certificates or PGP signatures, run
43
44```bash
45$ make mostlyclean
46```
47
48to delete them and create fresh ones on the next test run. You could
49also use `make clean`, but in that case the keys will be deleted as
50well and have to be recreated, too, which takes more time.
51
52
53## Implementation
54
55Each test is defined by a directory in tests/, which the test suite
56uses to spin up an isolated Apache instance (or more, for tests that
57need a proxy or OCSP responder) and try to connect to it with
58gnutls-cli and make a simple HTTP 1.1 or 1.0 request. Make generates a
59minimal test script to start each test from `test-template.bash.in`.
60
61Test directories usually contain the following files:
62
63* `apache.conf` -- Apache configuration to be used
64
65* `test.yml` -- Defines the client connection(s) including parameters
66  for `gnutls-cli`, the request(s), and expected response(s). Please
67  see the module documentation of [mgstest.tests](./mgstest/tests.py)
68  for details, and [`sample_test.yml`](./sample_test.yml) and
69  [`sample_fail.yml`](./sample_fail.yml) for examples.
70
71* `backend.conf` [optional] -- Apache configuration for the proxy
72  backend server, if any
73
74* `ocsp.conf` [optional] -- Apache configuration for the OCSP
75  responder, if any
76
77* `fail.server` [optional] -- if this file exists, it means we expect
78  the web server to fail to even start due to some serious
79  configuration problem.
80
81* `hooks.py` [optional] -- Defines hook functions that modify or
82  override the default behavior of `runtest.py`. Please see the module
83  documentation of [mgstest.hooks](./mgstest/hooks.py) for details.
84
85The [`runtest.py`](./runtest.py) program is used to start the required
86services send a request (or more) based on the files described
87above.
88
89By default (if the `unshare` command is available and has the
90permissions required to create network and user namespaces), each test
91case is run inside its own network namespace. This avoids address and
92port conflicts with other tests as well has the host system. Otherwise
93the tests use a lock file to prevent port conflicts between
94themselves.
95
96
97## Robustness and Tuning
98
99Here are some things that you might want to tune about the tests based
100on your expected setup (along with the variables that can be passed to
101"make check" to adjust them):
102
103* They need a functioning loopback device.
104
105* They expect to have ports 9932 (`TEST_PORT` as defined in
106  `Makefile.am`) through 9936 available for test services to bind to,
107  and open for connections on the addresses listed in `TEST_IP`.
108
109* Depending on the compile time configuration of the Apache binary
110  installed on your system you may need to load additional Apache
111  modules. The recommended way to do this is to drop a configuration
112  file into the `apache-conf/` directory. Patches to detect such
113  situations and automatically configure the tests accordingly are
114  welcome.
115
116* If a machine is particularly slow or under heavy load, it's possible
117  that tests fail for timing reasons. [`TEST_QUERY_TIMEOUT` (timeout
118  for the HTTPS request in seconds)]
119
120The first two of these issues are avoided when the tests are isolated
121using network namespaces, which is the default (see "Implementation"
122above). The `./configure` script tries to detect if namespaces can be
123used (some Linux distributions disable them for unprivileged
124users). If this detection returns a false positive or you do not want
125to use namespace isolation for some other reason, you can run
126configure with the `--disable-test-namespaces` option.
127
128In some situations you may want to see the exact environment as
129configured by make, e.g. if you want to manually run an Apache
130instance with Valgrind using the same configuration as a test
131case. Use `make show-test-env` to dump `AM_TESTS_ENVIRONMENT` to
132stdout. If you want to load the test environment into the current bash
133instance, you can use:
134
135```bash
136$ eval $(make show-test-env)
137```
138
139If you are building on an exotic architecture which does not support
140flock (or timeouts using `flock -w`), `./configure` should detect that
141and disable locking, or you can disable it manually by passing
142`--disable-flock` to `./configure`. This will force serial execution
143of tests, including environment setup.
144
145
146## Testing with Valgrind memcheck
147
148The primary HTTPD instance will run under Valgrind if you run
149`./configure` with `--enable-valgrind-test`. While very slow that can
150be useful to catch memory leaks early.
151
152The [`suppressions.valgrind`](./suppressions.valgrind) file contains
153some suppressions for known reported errors that are deemed not to be
154mod\_gnutls issues. Note that the suppressions in that file are aimed
155at Debian x86_64 (or similar) systems, you may need to adjust them on
156other platforms. The Valgrind suppressions files to use are read from
157the `VALGRIND_SUPPRESS` variable in [`Makefile.am`](./Makefile.am).
158You can add suppression files on the command line by overriding
159`VALGRIND_SUPPRESS` like this:
160
161```bash
162VALGRIND_SUPPRESS="suppressions.valgrind extra.valgrind" make -e check
163```
164
165
166## Adding a Test
167
168Please add more tests!
169
170The simplest way to add a test is (from the directory containing this
171file):
172
173```bash
174$ ./newtest
175```
176
177This will prompt you for a simple name for the test, copy a starting
178set of files from `tests/00_basic`, and tell you the test script name
179you can use to run the test and add to the `test_scripts` variable in
180`Makefile.am` when your test is ready for inclusion in the test
181suite. The files in the test directory must be added to `EXTRA_DIST`
182in `tests/Makefile.am`.
Note: See TracBrowser for help on using the repository browser.