[4b53371] | 1 | Unit Tests for Apache's mod_gnutls |
---|
| 2 | ================================== |
---|
| 3 | |
---|
[26081ce] | 4 | Authors: Daniel Kahn Gillmor <dkg@fifthhorseman.net> |
---|
| 5 | Thomas Klute <thomas2.klute@uni-dortmund.de> |
---|
[4b53371] | 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 | |
---|
[c3bee83] | 14 | From the top level of the source, or from test/ (where this README is), |
---|
[0f5c9e1] | 15 | just run: |
---|
[4b53371] | 16 | |
---|
[c3bee83] | 17 | make check |
---|
[4b53371] | 18 | |
---|
[c3bee83] | 19 | from test/. You can also run specific test cases by passing their |
---|
| 20 | script names to make in the TESTS variable: |
---|
[4b53371] | 21 | |
---|
[c3bee83] | 22 | TESTS="test-03_cachetimeout_in_vhost.bash" make -e check |
---|
[4b53371] | 23 | |
---|
| 24 | This should be handy when you're just trying to experiment with a new |
---|
| 25 | test and don't want to wait for the full test suite to run. |
---|
| 26 | |
---|
[dff57b4] | 27 | The default configuration assumes that a loopback device with IPv4 and |
---|
| 28 | IPv6 support is available (TEST_IP="[::1] 127.0.0.1") and that |
---|
| 29 | TEST_HOST="localhost" resolves to at least one of these addresses. If |
---|
| 30 | this does not apply to your system, you can pass different values to |
---|
| 31 | ./configure, e.g. to use IPv4 only: |
---|
[26081ce] | 32 | |
---|
| 33 | TEST_HOST="localhost" TEST_IP="127.0.0.1" ./configure |
---|
[4b53371] | 34 | |
---|
[fc8e463] | 35 | |
---|
[4b53371] | 36 | Adding a Test |
---|
| 37 | ============= |
---|
| 38 | |
---|
| 39 | Please add more tests! |
---|
| 40 | |
---|
[e78bc78] | 41 | The simplest way to add a test is (from test/): |
---|
[4b53371] | 42 | |
---|
[c3bee83] | 43 | ./newtest |
---|
[4b53371] | 44 | |
---|
[e78bc78] | 45 | This will prompt you for a simple name for the test and then copy a |
---|
| 46 | starting set of files from tests/00_basic, and create a script which |
---|
| 47 | you can add to TESTS in Makefile.am when your test is ready for |
---|
| 48 | inclusion in the test suite. |
---|
[4b53371] | 49 | |
---|
| 50 | |
---|
| 51 | Implementation |
---|
| 52 | ============== |
---|
| 53 | |
---|
[c3bee83] | 54 | Each test consists of a script in test/ and a directory in |
---|
| 55 | test/tests/, which the test suite uses to spin up an isolated Apache |
---|
| 56 | instance or two (for proxy tests) and try to connect to it with |
---|
| 57 | gnutls-cli and make a simple HTTP 1.1 or 1.0 request. |
---|
[4b53371] | 58 | |
---|
[c3bee83] | 59 | Test directories usually contain the following files: |
---|
[4b53371] | 60 | |
---|
[c3bee83] | 61 | * apache.conf -- Apache configuration to be used |
---|
[4b53371] | 62 | |
---|
[c3bee83] | 63 | * gnutls-cli.args -- the arguments to pass to gnutls-cli |
---|
[4b53371] | 64 | |
---|
| 65 | * input -- the full HTTP request (including the final blank line) |
---|
| 66 | |
---|
[c3bee83] | 67 | * backend.conf [optional] -- Apache configuration for the proxy |
---|
| 68 | backend server, if any |
---|
| 69 | |
---|
[4b53371] | 70 | * output [optional] -- the lines of this file will be checked against |
---|
| 71 | the same number of lines at the end of the output produced by the |
---|
[c3bee83] | 72 | gnutls-cli process. "Date" and "Server" headers are filtered from |
---|
| 73 | the response because they are expected to change between runs |
---|
| 74 | (date) or builds (server version). |
---|
[4b53371] | 75 | |
---|
| 76 | * fail.server [optional] -- if this file exists, it means we expect |
---|
| 77 | the web server to fail to even start due to some serious |
---|
| 78 | configuration problem. |
---|
| 79 | |
---|
| 80 | * fail.client [optional] -- if this file exists, it means we expect |
---|
| 81 | the client to fail to fetch its file. If you already have |
---|
| 82 | fail.server, do not also specify this; we know that a failed server |
---|
| 83 | should result in a failed file retrieval. |
---|
| 84 | |
---|
[c3bee83] | 85 | The "runtests" script is used to start one Apache instance and send a |
---|
| 86 | request based on the files described above. Note that some tests take |
---|
| 87 | additional steps, e.g. starting another server to act as proxy |
---|
| 88 | backend, and there is no technical requirement to use "runtests". |
---|
| 89 | |
---|
[b21bf4f] | 90 | By default (if "unshare" is available and has the permissions required |
---|
| 91 | to create network and user namespaces), each test case is run inside |
---|
| 92 | its own network namespace. This avoids address and port conflicts with |
---|
[c3bee83] | 93 | other tests as well has the host system. |
---|
| 94 | |
---|
| 95 | When writing your own tests, make sure to call netns_reexec (defined |
---|
| 96 | in common.bash) if you need to start any network services outside of |
---|
| 97 | runtests (which will create the namespace if it doesn't exist |
---|
| 98 | already). However, some architectures might not support namespaces, so |
---|
| 99 | traditional locking (using flock) and serial execution are still |
---|
| 100 | supported. |
---|
| 101 | |
---|
[4b53371] | 102 | |
---|
| 103 | Robustness and Tuning |
---|
| 104 | ===================== |
---|
| 105 | |
---|
[c3bee83] | 106 | Here are some things that you might want to tune about the tests based |
---|
| 107 | on your expected setup (along with the variables that can be passed to |
---|
| 108 | "make check" to adjust them): |
---|
[4b53371] | 109 | |
---|
[c3bee83] | 110 | * They need a functioning loopback device. |
---|
[4b53371] | 111 | |
---|
[c3bee83] | 112 | * They expect (by default) to have port 9932 [TEST_PORT] available |
---|
[dff57b4] | 113 | and open for connections on the addresses listed in TEST_IP. |
---|
[4b53371] | 114 | |
---|
[c3bee83] | 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 test/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 |
---|
[4b53371] | 123 | possible that these tests will fail for timing |
---|
[c3bee83] | 124 | reasons. [TEST_QUERY_DELAY (seconds for the HTTP request to be sent |
---|
[34e5dc7] | 125 | and responded to)] |
---|
[f9f184f] | 126 | |
---|
[c3bee83] | 127 | The first two of these issues are avoided when the tests are isolated |
---|
| 128 | using network namespaces, which is the default (see "Implementation" |
---|
[b21bf4f] | 129 | above). The ./configure script tries to detect if namespaces can be |
---|
| 130 | used (some Linux distributions disable them for unprivileged |
---|
| 131 | users). If this detection returns a false positive or you do not want |
---|
| 132 | to use namespace isolation for some other reason, you can run |
---|
| 133 | configure with the --disable-test-namespaces option. |
---|
[c3bee83] | 134 | |
---|
[f9f184f] | 135 | In some situations you may want to see the exact environment as |
---|
| 136 | configured by make, e.g. if you want to manually run an Apache |
---|
| 137 | instance with Valgrind using the same configuration as a test |
---|
| 138 | case. Use "make show-test-env" to dump AM_TESTS_ENVIRONMENT to stdout. |
---|
[c3bee83] | 139 | |
---|
| 140 | If you are building on an exotic architecture which does not support |
---|
[5d9f34e] | 141 | flock (or timeouts using flock -w), ./configure should detect that and |
---|
| 142 | disable locking, or you can disable it manually by passing |
---|
[c3bee83] | 143 | "--disable-flock" to ./configure. This will force serial execution of |
---|
| 144 | tests, including environment setup. |
---|