source: mod_gnutls/test/README.md @ 4411426

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

Convert test/README to markdown, plus small fixes

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