Changeset c3bee83 in mod_gnutls


Ignore:
Timestamp:
Jan 26, 2016, 2:14:15 PM (3 years ago)
Author:
Thomas Klute <thomas2.klute@…>
Branches:
debian/master, debian/stretch-backports, jessie-backports, master, upstream
Children:
600cf16
Parents:
948c181
git-author:
Thomas Klute <thomas2.klute@…> (01/26/16 14:11:40)
git-committer:
Thomas Klute <thomas2.klute@…> (01/26/16 14:14:15)
Message:

Update test suite documentation

Most updates are regarding network namespaces and flock usage, but
also added/updated a few other details.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • test/README

    r948c181 rc3bee83  
    1212=================
    1313
    14 from the top level of the source, or from test/ (where this README is),
     14From the top level of the source, or from test/ (where this README is),
    1515just run:
    1616
    17  make check
     17  make check
    1818
    19 from test/ you can also run specific tests by passing their script
    20 names to make in the TESTS variable:
     19from test/. You can also run specific test cases by passing their
     20script names to make in the TESTS variable:
    2121
    22  TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
     22  TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
    2323
    2424This should be handy when you're just trying to experiment with a new
     
    4141The simplest way to add a test is (from test/):
    4242
    43  ./newtest
     43  ./newtest
    4444
    4545This will prompt you for a simple name for the test and then copy a
     
    5252==============
    5353
    54 Each test consists of a directory in test/tests/, which will cause the
    55 test suite to spin up an isolated apache instance and try to connect
    56 to it with gnutls-cli and make a simple HTTP 1.1 request.
     54Each test consists of a script in test/ and a directory in
     55test/tests/, which the test suite uses to spin up an isolated Apache
     56instance or two (for proxy tests) and try to connect to it with
     57gnutls-cli and make a simple HTTP 1.1 or 1.0 request.
    5758
    58 By default, these tests are expected to succeed, by having
     59Test directories usually contain the following files:
    5960
    60 In each directory, you can put the following files:
     61 * apache.conf -- Apache configuration to be used
    6162
    62  * apache.conf --  the apache configuration to be used
    63 
    64  * gnutls-cli.args --  the arguments to pass to gnutls-cli
     63 * gnutls-cli.args -- the arguments to pass to gnutls-cli
    6564
    6665 * input -- the full HTTP request (including the final blank line)
    6766
     67 * backend.conf [optional] -- Apache configuration for the proxy
     68   backend server, if any
     69
    6870 * output [optional] -- the lines of this file will be checked against
    6971   the same number of lines at the end of the output produced by the
    70    gnutls-cli process.
     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).
    7175
    7276 * fail.server [optional] -- if this file exists, it means we expect
     
    7983   should result in a failed file retrieval.
    8084
     85The "runtests" script is used to start one Apache instance and send a
     86request based on the files described above. Note that some tests take
     87additional steps, e.g. starting another server to act as proxy
     88backend, and there is no technical requirement to use "runtests".
     89
     90By default (if "unshare" is available and --disable-test-namespaces
     91has NOT been passed to configure), each test case is run inside its
     92own network namespace. This avoids address and port conflicts with
     93other tests as well has the host system.
     94
     95When writing your own tests, make sure to call netns_reexec (defined
     96in common.bash) if you need to start any network services outside of
     97runtests (which will create the namespace if it doesn't exist
     98already). However, some architectures might not support namespaces, so
     99traditional locking (using flock) and serial execution are still
     100supported.
     101
    81102
    82103Robustness and Tuning
    83104=====================
    84105
    85 These tests aren't nearly as robust as i'd like them to be, but they
    86 work for the moment and they're better than no tests at all.
     106Here are some things that you might want to tune about the tests based
     107on your expected setup (along with the variables that can be passed to
     108"make check" to adjust them):
    87109
    88 Here are some things that you might want to tune based on your
    89 expected setup (along with the variables that can be passed to "make
    90 check" to adjust them):
     110 * They need a functioning loopback device.
    91111
    92  * they need a functioning loopback device.
    93 
    94  * they expect (by default) to have port 9932 [TEST_PORT] available
     112 * They expect (by default) to have port 9932 [TEST_PORT] available
    95113   and open for connections on the addresses listed in TEST_IP.
    96114
    97  * if a machine is particularly slow or under heavy load, it's
     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
    98123   possible that these tests will fail for timing
    99    reasons. [TEST_QUERY_DELAY (seconds for the http request to be sent
     124   reasons. [TEST_QUERY_DELAY (seconds for the HTTP request to be sent
    100125   and responded to)]
     126
     127The first two of these issues are avoided when the tests are isolated
     128using network namespaces, which is the default (see "Implementation"
     129above).
    101130
    102131In some situations you may want to see the exact environment as
     
    104133instance with Valgrind using the same configuration as a test
    105134case. Use "make show-test-env" to dump AM_TESTS_ENVIRONMENT to stdout.
     135
     136If you are building on an exotic architecture which does not support
     137flock (or timeouts using flock -w), you can disable it by passing
     138"--disable-flock" to ./configure. This will force serial execution of
     139tests, including environment setup.
Note: See TracChangeset for help on using the changeset viewer.