source: mod_gnutls/test/README.md @ f826b5f

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

test/README.md: Enable syntax highlighting

  • 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```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)
83
84* `backend.conf` [optional] -- Apache configuration for the proxy
85  backend server, if any
86
87* `ocsp.conf` [optional] -- Apache configuration for the OCSP
88  responder, if any
89
90* `fail.server` [optional] -- if this file exists, it means we expect
91  the web server to fail to even start due to some serious
92  configuration problem.
93
94* `hooks.py` [optional] -- Defines hook functions that modify or
95  override the default behavior of `runtest.py`. Please see the module
96  documentation of [mgstest.hooks](./mgstest/hooks.py) for details.
97
98The [`runtest.py`](./runtest.py) program is used to start the required
99services send a request (or more) based on the files described
100above. Note that currently some tests take additional steps in their
101test scripts, though `hooks.py` is the preferred mechanism.
102
103By default (if the `unshare` command is available and has the
104permissions required to create network and user namespaces), each test
105case is run inside its own network namespace. This avoids address and
106port conflicts with other tests as well has the host system. Otherwise
107the tests use a lock file to prevent port conflicts between
108themselves.
109
110When writing your own tests, make sure to call `runtest.py` through
111`netns_py.bash` like the current tests do to ensure compatibility with
112the namespace and lock file mechanisms.
113
114## Robustness and Tuning
115
116Here are some things that you might want to tune about the tests based
117on your expected setup (along with the variables that can be passed to
118"make check" to adjust them):
119
120* They need a functioning loopback device.
121
122* They expect to have ports 9932 (`TEST_PORT` as defined in
123  `Makefile.am`) through 9936 available for test services to bind to,
124  and open for connections on the addresses listed in `TEST_IP`.
125
126* Depending on the compile time configuration of the Apache binary
127  installed on your system you may need to load additional Apache
128  modules. The recommended way to do this is to drop a configuration
129  file into the `apache-conf/` directory. Patches to detect such
130  situations and automatically configure the tests accordingly are
131  welcome.
132
133* If a machine is particularly slow or under heavy load, it's possible
134  that tests fail for timing reasons. [`TEST_QUERY_TIMEOUT` (timeout
135  for the HTTPS request in seconds)]
136
137The first two of these issues are avoided when the tests are isolated
138using network namespaces, which is the default (see "Implementation"
139above). The `./configure` script tries to detect if namespaces can be
140used (some Linux distributions disable them for unprivileged
141users). If this detection returns a false positive or you do not want
142to use namespace isolation for some other reason, you can run
143configure with the `--disable-test-namespaces` option.
144
145In some situations you may want to see the exact environment as
146configured by make, e.g. if you want to manually run an Apache
147instance with Valgrind using the same configuration as a test
148case. Use `make show-test-env` to dump `AM_TESTS_ENVIRONMENT` to
149stdout. If you want to load the test environment into the current bash
150instance, you can use:
151
152```bash
153$ eval $(make show-test-env)
154```
155
156If you are building on an exotic architecture which does not support
157flock (or timeouts using `flock -w`), `./configure` should detect that
158and disable locking, or you can disable it manually by passing
159`--disable-flock` to `./configure`. This will force serial execution
160of tests, including environment setup.
Note: See TracBrowser for help on using the repository browser.