tests/README.md

   1 <!--
   2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
   3
   4 SPDX-License-Identifier: curl
   5 -->
   6
   7 # The curl Test Suite
   8
   9 # Running
  10
  11   See the "Requires to run" section for prerequisites.
  12
  13   In the root of the curl repository:
  14
  15     ./configure && make && make test
  16
  17   To run a specific set of tests (e.g. 303 and 410):
  18
  19     make test TFLAGS="303 410"
  20
  21   To run the tests faster, pass the -j (parallelism) flag:
  22
  23     make test TFLAGS="-j10"
  24
  25   "make test" builds the test suite support code and invokes the 'runtests.pl'
  26   perl script to run all the tests. The value of `TFLAGS` is passed
  27   directly to 'runtests.pl'.
  28
  29   When you run tests via make, the flags `-a` and `-s` are passed, meaning
  30   to continue running tests even after one fails, and to emit short output.
  31
  32   If you'd like to not use those flags, you can run 'runtests.pl' directly.
  33   You must `chdir` into the tests directory, then you can run it like so:
  34
  35     ./runtests.pl 303 410
  36
  37   You must have run `make test` at least once first to build the support code.
  38
  39   To see what flags are available for runtests.pl, and what output it emits, run:
  40
  41     man ./tests/runtests.1
  42
  43   After a test fails, examine the tests/log directory for stdout, stderr, and
  44   output from the servers used in the test.
  45
  46 ## Requires to run
  47
  48   - perl (and a unix-style shell)
  49   - python (and a unix-style shell, for SMB and TELNET tests)
  50   - python-impacket (for SMB tests)
  51   - diff (when a test fails, a diff is shown)
  52   - stunnel (for HTTPS and FTPS tests)
  53   - OpenSSH or SunSSH (for SCP and SFTP tests)
  54   - nghttpx (for HTTP/2 and HTTP/3 tests)
  55   - nroff (for --manual tests)
  56   - An available `en_US.UTF-8` locale
  57
  58 ### Installation of python-impacket
  59
  60   The Python-based test servers support both recent Python 2 and 3.
  61   You can figure out your default Python interpreter with python -V
  62
  63   Please install python-impacket in the correct Python environment.
  64   You can use pip or your OS' package manager to install 'impacket'.
  65
  66   On Debian/Ubuntu the package names are:
  67
  68   -  Python 2: 'python-impacket'
  69   -  Python 3: 'python3-impacket'
  70
  71   On FreeBSD the package names are:
  72
  73   -  Python 2: 'py27-impacket'
  74   -  Python 3: 'py37-impacket'
  75
  76   On any system where pip is available:
  77
  78   -  Python 2: 'pip2 install impacket'
  79   -  Python 3: 'pip3 install impacket'
  80
  81   You may also need to manually install the Python package 'six'
  82   as that may be a missing requirement for impacket on Python 3.
  83
  84 ### Port numbers used by test servers
  85
  86   All test servers run on "random" port numbers. All tests should be written
  87   to use suitable variables instead of fixed port numbers so that test cases
  88   continue to work independent on what port numbers the test servers actually
  89   use.
  90
  91   See [`FILEFORMAT`](FILEFORMAT.md) for the port number variables.
  92
  93 ### Test servers
  94
  95   The test suite runs stand-alone servers on random ports to which it makes
  96   requests. For SSL tests, it runs stunnel to handle encryption to the regular
  97   servers. For SSH, it runs a standard OpenSSH server.
  98
  99   The listen port numbers for the test servers are picked randomly to allow
 100   users to run multiple test cases concurrently and to not collide with other
 101   existing services that might listen to ports on the machine.
 102
 103   The HTTP server supports listening on a Unix domain socket, the default
 104   location is 'http.sock'.
 105
 106   For HTTP/2 and HTTP/3 testing an installed `nghttpx` is used. HTTP/3
 107   tests check if nghttpx supports the protocol. To override the nghttpx
 108   used, set the environment variable `NGHTTPX`. The default can also be
 109   changed by specifying `--with-test-nghttpx=<path>` as argument to `configure`.
 110
 111 ### Shell startup scripts
 112
 113   Tests which use the ssh test server, SCP/SFTP tests, might be badly
 114   influenced by the output of system wide or user specific shell startup
 115   scripts, .bashrc, .profile, /etc/csh.cshrc, .login, /etc/bashrc, etc. which
 116   output text messages or escape sequences on user login. When these shell
 117   startup messages or escape sequences are output they might corrupt the
 118   expected stream of data which flows to the sftp-server or from the ssh
 119   client which can result in bad test behavior or even prevent the test server
 120   from running.
 121
 122   If the test suite ssh or sftp server fails to start up and logs the message
 123   'Received message too long' then you are certainly suffering the unwanted
 124   output of a shell startup script. Locate, cleanup or adjust the shell
 125   script.
 126
 127 ### Memory test
 128
 129   The test script will check that all allocated memory is freed properly IF
 130   curl has been built with the `CURLDEBUG` define set. The script will
 131   automatically detect if that is the case, and it will use the
 132   `memanalyze.pl` script to analyze the memory debugging output.
 133
 134   Also, if you run tests on a machine where valgrind is found, the script will
 135   use valgrind to run the test with (unless you use `-n`) to further verify
 136   correctness.
 137
 138   The `runtests.pl` `-t` option enables torture testing mode. It runs each
 139   test many times and makes each different memory allocation fail on each
 140   successive run. This tests the out of memory error handling code to ensure
 141   that memory leaks do not occur even in those situations. It can help to
 142   compile curl with `CPPFLAGS=-DMEMDEBUG_LOG_SYNC` when using this option, to
 143   ensure that the memory log file is properly written even if curl crashes.
 144
 145 ### Debug
 146
 147   If a test case fails, you can conveniently get the script to invoke the
 148   debugger (gdb) for you with the server running and the same command line
 149   parameters that failed. Just invoke `runtests.pl <test number> -g` and then
 150   just type 'run' in the debugger to perform the command through the debugger.
 151
 152 ### Logs
 153
 154   All logs are generated in the log/ subdirectory (it is emptied first in the
 155   runtests.pl script). They remain in there after a test run.
 156
 157 ### Log Verbosity
 158
 159   A curl build with `--enable-debug` offers more verbose output in the logs.
 160   This applies not only for test cases, but also when running it standalone
 161   with `curl -v`. While a curl debug built is
 162   ***not suitable for production***, it is often helpful in tracking down
 163   problems.
 164
 165   Sometimes, one needs detailed logging of operations, but does not want
 166   to drown in output. The newly introduced *connection filters* allows one to
 167   dynamically increase log verbosity for a particular *filter type*. Example:
 168
 169     CURL_DEBUG=ssl curl -v https://curl.se
 170
 171   will make the `ssl` connection filter log more details. One may do that for
 172   every filter type and also use a combination of names, separated by `,` or
 173   space.
 174
 175     CURL_DEBUG=ssl,http/2 curl -v https://curl.se
 176
 177    The order of filter type names is not relevant. Names used here are
 178    case insensitive. Note that these names are implementation internals and
 179    subject to change.
 180
 181    Some, likely stable names are `tcp`, `ssl`, `http/2`. For a current list,
 182    one may search the sources for `struct Curl_cftype` definitions and find
 183    the names there. Also, some filters are only available with certain build
 184    options, of course.
 185
 186 ### Test input files
 187
 188   All test cases are put in the `data/` subdirectory. Each test is stored in
 189   the file named according to the test number.
 190
 191   See [`FILEFORMAT`](FILEFORMAT.md) for a description of the test case file
 192   format.
 193
 194 ### Code coverage
 195
 196   gcc provides a tool that can determine the code coverage figures for the
 197   test suite. To use it, configure curl with `CFLAGS='-fprofile-arcs
 198   -ftest-coverage -g -O0'`. Make sure you run the normal and torture tests to
 199   get more full coverage, i.e. do:
 200
 201     make test
 202     make test-torture
 203
 204   The graphical tool `ggcov` can be used to browse the source and create
 205   coverage reports on \*nix hosts:
 206
 207     ggcov -r lib src
 208
 209   The text mode tool `gcov` may also be used, but it doesn't handle object
 210   files in more than one directory correctly.
 211
 212 ### Remote testing
 213
 214   The runtests.pl script provides some hooks to allow curl to be tested on a
 215   machine where perl can not be run. The test framework in this case runs on
 216   a workstation where perl is available, while curl itself is run on a remote
 217   system using ssh or some other remote execution method. See the comments at
 218   the beginning of runtests.pl for details.
 219
 220 ## Test case numbering
 221
 222   Test cases used to be numbered by category ranges, but the ranges filled
 223   up. Subsets of tests can now be selected by passing keywords to the
 224   runtests.pl script via the make `TFLAGS` variable.
 225
 226   New tests are added by finding a free number in `tests/data/Makefile.inc`.
 227
 228 ## Write tests
 229
 230   Here's a quick description on writing test cases. We basically have three
 231   kinds of tests: the ones that test the curl tool, the ones that build small
 232   applications and test libcurl directly and the unit tests that test
 233   individual (possibly internal) functions.
 234
 235 ### test data
 236
 237   Each test has a master file that controls all the test data. What to read,
 238   what the protocol exchange should look like, what exit code to expect and
 239   what command line arguments to use etc.
 240
 241   These files are `tests/data/test[num]` where `[num]` is just a unique
 242   identifier described above, and the XML-like file format of them is
 243   described in the separate [`FILEFORMAT`](FILEFORMAT.md) document.
 244
 245 ### curl tests
 246
 247   A test case that runs the curl tool and verifies that it gets the correct
 248   data, it sends the correct data, it uses the correct protocol primitives
 249   etc.
 250
 251 ### libcurl tests
 252
 253   The libcurl tests are identical to the curl ones, except that they use a
 254   specific and dedicated custom-built program to run instead of "curl". This
 255   tool is built from source code placed in `tests/libtest` and if you want to
 256   make a new libcurl test that is where you add your code.
 257
 258 ### unit tests
 259
 260   Unit tests are placed in `tests/unit`. There's a tests/unit/README
 261   describing the specific set of checks and macros that may be used when
 262   writing tests that verify behaviors of specific individual functions.
 263
 264   The unit tests depend on curl being built with debug enabled.