source: mod_gnutls/test/ @ e2200db

Last change on this file since e2200db was 0da2c5d, checked in by Fiona Klute <fiona.klute@…>, 21 months ago

Test suite: Update README and newtest script

  • Property mode set to 100644
File size: 5.8 KB
[4411426]1# Unit Tests for Apache's mod_gnutls
4Daniel Kahn Gillmor <>,
5Fiona Klute <>
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.
11## Running the tests
13From the top level of the source, or from `test/` (where this README is),
14just run:
17$ make check
20You can also run specific test cases by passing their script names to
21make in the `TESTS` variable:
24$ TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
27This should be handy when you're just trying to experiment with a new
[0da2c5d]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/`.
32The default configuration assumes that a loopback device with IPv4 and
33IPv6 support is available (`TEST_IP="[::1]"`) and that
[0da2c5d]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:
39$ TEST_HOST="localhost" TEST_IP="" ./configure
42If tests fail due to expired certificates or PGP signatures, run
45$ make mostlyclean
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.
53## Implementation
[0da2c5d]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 ``.
61Test directories usually contain the following files:
63* `apache.conf` -- Apache configuration to be used
65* `test.yml` -- Defines the client connection(s) including parameters
[bbc9b03]66  for `gnutls-cli`, the request(s), and expected response(s). Please
67  see the module documentation of [mgstest.tests](./mgstest/
68  for details, and [`sample_test.yml`](./sample_test.yml) and
69  [`sample_fail.yml`](./sample_fail.yml) for examples.
71* `backend.conf` [optional] -- Apache configuration for the proxy
72  backend server, if any
74* `ocsp.conf` [optional] -- Apache configuration for the OCSP
75  responder, if any
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.
81* `` [optional] -- Defines hook functions that modify or
[e971a2c]82  override the default behavior of ``. Please see the module
83  documentation of [mgstest.hooks](./mgstest/ for details.
85The [``](./ program is used to start the required
86services send a request (or more) based on the files described
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
97## Robustness and Tuning
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):
103* They need a functioning loopback device.
105* They expect to have ports 9932 (`TEST_PORT` as defined in
106  ``) through 9936 available for test services to bind to,
107  and open for connections on the addresses listed in `TEST_IP`.
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.
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)]
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.
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:
136$ eval $(make show-test-env)
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.
146## Adding a Test
148Please add more tests!
150The simplest way to add a test is (from the directory containing this
154$ ./newtest
157This will prompt you for a simple name for the test, copy a starting
158set of files from `tests/00_basic`, and tell you the test script name
159you can use to run the test and add to the `test_scripts` variable in
160`` when your test is ready for inclusion in the test
161suite. The files in the test directory must be added to `EXTRA_DIST`
162in `tests/`.
Note: See TracBrowser for help on using the repository browser.