source: mod_gnutls/test/README.md @ bbc9b03

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

Detailed documentation on test.yml and mgstest.tests

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