Changes in test/README [fc8e463b:8ac7c0d] in mod_gnutls

1 edited


  • test/README

    rfc8e463b r8ac7c0d  
    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:
    17  make check
     17  make check
    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:
    22  TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
     22  TESTS="test-03_cachetimeout_in_vhost.bash" make -e check
    2424This should be handy when you're just trying to experiment with a new
    2525test and don't want to wait for the full test suite to run.
    27 The default configuration assumes that an IPv6 loopback device is
    28 available (TEST_IP=[::1]) and that TEST_HOST="localhost" resolves to
    29 the IPv6 loopback address [::1]. If this does not apply to your
    30 system, you can pass different values to ./configure, e.g. to use IPv4
    31 instead:
     27The default configuration assumes that a loopback device with IPv4 and
     28IPv6 support is available (TEST_IP="[::1]") and that
     29TEST_HOST="localhost" resolves to at least one of these addresses. If
     30this does not apply to your system, you can pass different values to
     31./configure, e.g. to use IPv4 only:
    3333  TEST_HOST="localhost" TEST_IP="" ./configure
     35If tests fail due to expired certificates or PGP signatures, run
     37  make mostlyclean
     39to delete them and create fresh ones on the next test run. You could
     40also use "make clean", but in that case the keys will be deleted as
     41well and have to be recreated, too, which takes more time.
    4149The simplest way to add a test is (from test/):
    43  ./newtest
     51  ./newtest
    4553This will prompt you for a simple name for the test and then copy a
    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.
     62Each test consists of a script in test/ and a directory in
     63test/tests/, which the test suite uses to spin up an isolated Apache
     64instance or two (for proxy tests) and try to connect to it with
     65gnutls-cli and make a simple HTTP 1.1 or 1.0 request.
    58 By default, these tests are expected to succeed, by having
     67Test directories usually contain the following files:
    60 In each directory, you can put the following files:
     69 * apache.conf -- Apache configuration to be used
    62  * apache.conf --  the apache configuration to be used
    64  * gnutls-cli.args --  the arguments to pass to gnutls-cli
     71 * gnutls-cli.args -- the arguments to pass to gnutls-cli
    6673 * input -- the full HTTP request (including the final blank line)
     75 * backend.conf [optional] -- Apache configuration for the proxy
     76   backend server, if any
    6878 * output [optional] -- the lines of this file will be checked against
    6979   the same number of lines at the end of the output produced by the
    70    gnutls-cli process.
     80   gnutls-cli process. "Date" and "Server" headers are filtered from
     81   the response because they are expected to change between runs
     82   (date) or builds (server version).
    7284 * fail.server [optional] -- if this file exists, it means we expect
    7991   should result in a failed file retrieval.
     93The "runtests" script is used to start one Apache instance and send a
     94request based on the files described above. Note that some tests take
     95additional steps, e.g. starting another server to act as proxy
     96backend, and at least one does not use "runtests" at all.
     98By default (if "unshare" is available and has the permissions required
     99to create network and user namespaces), each test case is run inside
     100its own network namespace. This avoids address and port conflicts with
     101other tests as well has the host system.
     103When writing your own tests, make sure to call netns_reexec (defined
     104in common.bash) if you need to start any network services outside of
     105runtests (which will create the namespace if it doesn't exist
     106already). However, some architectures might not support namespaces, so
     107traditional locking (using flock) and serial execution are still
    82111Robustness and Tuning
    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.
     114Here are some things that you might want to tune about the tests based
     115on your expected setup (along with the variables that can be passed to
     116"make check" to adjust them):
    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):
     118 * They need a functioning loopback device.
    92  * they need a functioning loopback device.
     120 * They expect (by default) to have port 9932 [TEST_PORT] available
     121   and open for connections on the addresses listed in TEST_IP.
    94  * they expect (by default) the TEST_IP to have port 9932
    95    open. [TEST_PORT]
     123 * Depending on the compile time configuration of the Apache binary
     124   installed on your system you may need to load additional Apache
     125   modules. The recommended way to do this is to drop a configuration
     126   file into the test/apache-conf/ directory. Patches to detect such
     127   situations and automatically configure the tests accordingly are
     128   welcome.
    97  * if a machine is particularly slow or under heavy load, it's
     130 * If a machine is particularly slow or under heavy load, it's
    98131   possible that these tests will fail for timing
    99    reasons. [TEST_QUERY_DELAY (seconds for the http request to be sent
     132   reasons. [TEST_QUERY_DELAY (seconds for the HTTP request to be sent
    100133   and responded to)]
     135The first two of these issues are avoided when the tests are isolated
     136using network namespaces, which is the default (see "Implementation"
     137above). The ./configure script tries to detect if namespaces can be
     138used (some Linux distributions disable them for unprivileged
     139users). If this detection returns a false positive or you do not want
     140to use namespace isolation for some other reason, you can run
     141configure with the --disable-test-namespaces option.
    102143In some situations you may want to see the exact environment as
    104145instance with Valgrind using the same configuration as a test
    105146case. Use "make show-test-env" to dump AM_TESTS_ENVIRONMENT to stdout.
     148If you are building on an exotic architecture which does not support
     149flock (or timeouts using flock -w), ./configure should detect that and
     150disable locking, or you can disable it manually by passing
     151"--disable-flock" to ./configure. This will force serial execution of
     152tests, including environment setup.
Note: See TracChangeset for help on using the changeset viewer.