1 | # Unit Tests for Apache's mod_gnutls |
---|
2 | |
---|
3 | Authors: |
---|
4 | Daniel Kahn Gillmor <dkg@fifthhorseman.net>, |
---|
5 | Fiona Klute <fiona.klute@gmx.de> |
---|
6 | |
---|
7 | There are a lot of ways that a TLS-capable web server can go wrong. I |
---|
8 | want to at least test for some basic/common configurations. |
---|
9 | |
---|
10 | |
---|
11 | ## Running the tests |
---|
12 | |
---|
13 | From the top level of the source, or from `test/` (where this README is), |
---|
14 | just run: |
---|
15 | |
---|
16 | $ make check |
---|
17 | |
---|
18 | You can also run specific test cases by passing their script names to |
---|
19 | make in the `TESTS` variable: |
---|
20 | |
---|
21 | $ TESTS="test-03_cachetimeout_in_vhost.bash" make -e check |
---|
22 | |
---|
23 | This should be handy when you're just trying to experiment with a new |
---|
24 | test and don't want to wait for the full test suite to run. |
---|
25 | |
---|
26 | The default configuration assumes that a loopback device with IPv4 and |
---|
27 | IPv6 support is available (`TEST_IP="[::1] 127.0.0.1"`) and that |
---|
28 | `TEST_HOST="localhost"` resolves to at least one of these |
---|
29 | addresses. If this does not apply to your system, you can pass |
---|
30 | different values to `./configure`, e.g. to use IPv4 only: |
---|
31 | |
---|
32 | $ TEST_HOST="localhost" TEST_IP="127.0.0.1" ./configure |
---|
33 | |
---|
34 | If tests fail due to expired certificates or PGP signatures, run |
---|
35 | |
---|
36 | $ make mostlyclean |
---|
37 | |
---|
38 | to delete them and create fresh ones on the next test run. You could |
---|
39 | also use `make clean`, but in that case the keys will be deleted as |
---|
40 | well and have to be recreated, too, which takes more time. |
---|
41 | |
---|
42 | |
---|
43 | ## Adding a Test |
---|
44 | |
---|
45 | Please add more tests! |
---|
46 | |
---|
47 | The simplest way to add a test is (from the directory containing this |
---|
48 | file): |
---|
49 | |
---|
50 | $ ./newtest |
---|
51 | |
---|
52 | This will prompt you for a simple name for the test, copy a starting |
---|
53 | set of files from `tests/00_basic`, and create a script which you can |
---|
54 | add to the `test_scripts` variable in `Makefile.am` when your test is |
---|
55 | ready for inclusion in the test suite. The files in the test directory |
---|
56 | must be added to `EXTRA_DIST` in `tests/Makefile.am`. |
---|
57 | |
---|
58 | |
---|
59 | ## Implementation |
---|
60 | |
---|
61 | Each test consists of a script in the directory containing this README |
---|
62 | and a directory in tests/, which the test suite uses to spin up an |
---|
63 | isolated Apache instance (or more, for tests that need a proxy or OCSP |
---|
64 | responder) and try to connect to it with gnutls-cli and make a simple |
---|
65 | HTTP 1.1 or 1.0 request. |
---|
66 | |
---|
67 | Test 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 | |
---|
87 | The [`runtest.py`](./runtest.py) program is used to start the required |
---|
88 | services send a request (or more) based on the files described |
---|
89 | above. Note that currently some tests take additional steps in their |
---|
90 | test scripts, though `hooks.py` is the preferred mechanism. |
---|
91 | |
---|
92 | By default (if the `unshare` command is available and has the |
---|
93 | permissions required to create network and user namespaces), each test |
---|
94 | case is run inside its own network namespace. This avoids address and |
---|
95 | port conflicts with other tests as well has the host system. Otherwise |
---|
96 | the tests use a lock file to prevent port conflicts between |
---|
97 | themselves. |
---|
98 | |
---|
99 | When writing your own tests, make sure to call `runtest.py` through |
---|
100 | `netns_py.bash` like the current tests do to ensure compatibility with |
---|
101 | the namespace and lock file mechanisms. |
---|
102 | |
---|
103 | ## Robustness and Tuning |
---|
104 | |
---|
105 | Here are some things that you might want to tune about the tests based |
---|
106 | on 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 | |
---|
126 | The first two of these issues are avoided when the tests are isolated |
---|
127 | using network namespaces, which is the default (see "Implementation" |
---|
128 | above). The `./configure` script tries to detect if namespaces can be |
---|
129 | used (some Linux distributions disable them for unprivileged |
---|
130 | users). If this detection returns a false positive or you do not want |
---|
131 | to use namespace isolation for some other reason, you can run |
---|
132 | configure with the `--disable-test-namespaces` option. |
---|
133 | |
---|
134 | In some situations you may want to see the exact environment as |
---|
135 | configured by make, e.g. if you want to manually run an Apache |
---|
136 | instance with Valgrind using the same configuration as a test |
---|
137 | case. Use `make show-test-env` to dump `AM_TESTS_ENVIRONMENT` to |
---|
138 | stdout. If you want to load the test environment into the current bash |
---|
139 | instance, you can use: |
---|
140 | |
---|
141 | $ eval $(make show-test-env) |
---|
142 | |
---|
143 | If you are building on an exotic architecture which does not support |
---|
144 | flock (or timeouts using `flock -w`), `./configure` should detect that |
---|
145 | and disable locking, or you can disable it manually by passing |
---|
146 | `--disable-flock` to `./configure`. This will force serial execution |
---|
147 | of tests, including environment setup. |
---|