tests/runtests.1

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" * SPDX-License-Identifier: curl
  22 .\" *
  23 .\" **************************************************************************
  24 .\"
  25 .TH runtests.pl 1 "October 24, 2023" "untests 8.5.0" runtests
  26
  27 .SH NAME
  28 runtests.pl \- run one or more test cases
  29 .SH SYNOPSIS
  30 .B runtests.pl [options] [tests]
  31 .SH DESCRIPTION
  32 \fIruntests.pl\fP runs one, several or all the existing test cases in curl's
  33 test suite. It is often called from the root Makefile of the curl package with
  34 \&'make test'.
  35 .SH "TESTS"
  36 Specify which test(s) to run by specifying test numbers or keywords.
  37
  38 If no test number or keyword is given, all existing tests that the script can
  39 find will be considered for running. You can specify single test cases to run
  40 by specifying test numbers space-separated, like "1 3 5 7 11", and you can
  41 specify a range of tests like "45 to 67".
  42
  43 Specify tests to not run with a leading exclamation point, like "!66", which
  44 runs all available tests except number 66.
  45
  46 Prefix a test number with a tilde (~) to still run it, but ignore the results.
  47
  48 It is also possible to specify tests based on a keyword describing the test(s)
  49 to run, like "FTPS". The keywords are strings used in the individual tests.
  50
  51 You can also specify keywords with a leading exclamation point and the keyword
  52 or phrase, like "!HTTP NTLM auth" to run all tests \fBexcept\fP those using
  53 this keyword. Remember that the exclamation marks and spaces will need to be
  54 quoted somehow when entered at many command shells.
  55
  56 Prefix a keyword with a tilde (~) to still run it, but ignore the results.
  57
  58 .SH "OUTPUT"
  59
  60 When running without -s (short output), for instance when running runtests.pl
  61 directly rather than via make, each test will emits a pair of lines like this:
  62
  63 Test 0045...[simple HTTP Location: without protocol in initial URL]
  64 --pd---e-v- OK (45  out of 1427, remaining: 16:08, took 6.188s, duration: 00:31)
  65
  66 the first line contains the test number and a description. On the second line,
  67 the characters at the beginning are flags indicating which aspects of curl's
  68 behavior were checked by the test:
  69
  70     s stdout
  71     r stderr
  72     p protocol
  73     d data
  74     u upload
  75     P proxy
  76     o output
  77     e exit code
  78     m memory
  79     v valgrind
  80     E the test was run event-based
  81
  82 The remainder of the second line contains the test result, current test sequence,
  83 total number of tests to be run and an estimated amount of time to complete the
  84 test run.
  85
  86 .SH OPTIONS
  87 .IP "-a"
  88 Continue running the rest of the test cases even if one test fails. By
  89 default, the test script stops as soon as an error is detected.
  90 .IP "-ac <curl>"
  91 Provide a path to a curl binary to talk to APIs (currently only CI test APIs).
  92 .IP "-am"
  93 Display test results in automake style output (PASS/FAIL: [number] [name]).
  94 .IP "-c <curl>"
  95 Provide a path to a custom curl binary to run the tests with. Default is the
  96 curl executable in the build tree.
  97 .IP "-d"
  98 Enable protocol debug: have the servers display protocol output.  If used in
  99 conjunction with parallel testing, it will be difficult to associate the logs
 100 with the test being run.
 101 .IP "-E <exclude_file>"
 102 Load the \fBexclude_file\fP with additional reasons why certain tests
 103 should be skipped. Useful when testing with external HTTP proxies in
 104 which case some of the tests aren't appropriate.
 105 The file contains colon-delimited lines. The first field contains the
 106 type of exclusion, the second field contains a pattern and the final
 107 field contains the reason why matching tests should be skipped.
 108 The exclusion types are \fkeyword\fP, \ftest\fP, and \ftool\fP.
 109 .IP "-e"
 110 Run the test event-based (if possible). This will make runtests invoke curl
 111 with --test-event option. This option only works if both curl and libcurl were
 112 built debug-enabled.
 113 .IP "-f"
 114 Force the test to run even if mentioned in DISABLED.
 115 .IP "-g"
 116 Run the given test(s) with gdb. This is best used on a single test case and
 117 curl built --disable-shared. This then fires up gdb with command line set to
 118 run the specified test case. Simply (set a break-point and) type 'run' to
 119 start.
 120 .IP "-gw"
 121 Run the given test(s) with gdb as a windowed application.
 122 .IP "-h, --help"
 123 Displays a help text about this program's command line options.
 124 .IP "-j[num]"
 125 Spawn num processes to run tests. This defaults to 0 to run tests serially
 126 within a single process. Using a number greater than one allows multiple tests
 127 to run in parallel, speeding up a test run. The optimum number is dependent on
 128 the system and set of tests to run, but 7*number of CPU cores is a good figure
 129 to start with, or 1.3*number of CPU cores if Valgrind is in use. Enabling
 130 parallel tests is not recommended in conjunction with the \-g option.
 131 .IP "-k"
 132 Keep output and log files in log/ after a test run, even if no error was
 133 detected. Useful for debugging.
 134 .IP "-L <file>"
 135 Load and execute the specified file which should contain perl code.
 136 This option allows one to change \fIruntests.pl\fP behaviour by overwriting
 137 functions and variables and is useful when testing external proxies
 138 using curl's regression test suite.
 139 .IP "-l"
 140 Lists all test case names.
 141 .IP "-n"
 142 Disable the check for and use of valgrind.
 143 .IP "--no-debuginfod"
 144 Delete the DEBUGINFOD_URLS variable if that is defined. Makes valgrind, gdb
 145 etc not able to use this functionality.
 146 .IP "-o <variablename=value>"
 147 Overwrite the specified internal \fBvariable\fP with \fBvalue\fP.
 148 Useful to change variables that didn't get a dedicated flag to change them.
 149 Check the source to see which variables are available.
 150 .IP "-P <proxy>"
 151 Use the specified HTTP proxy when executing tests, even if the tests
 152 themselves don't specify a proxy. This option allows one to test external
 153 proxies using curl's regression test suite.
 154 .IP "-p"
 155 Prints out all files in "log/" to stdout when a test case fails. Very
 156 practical when used in the automated and distributed tests since then the
 157 people checking the failures and the reasons for them might not have physical
 158 access to the machine and logs.
 159 .IP "-R"
 160 Run the tests in a scrambled, or randomized, order instead of sequentially.
 161
 162 The random seed initially set for this is fixed per month and can be set with
 163 \fI--seed\fP.
 164 .IP "-r"
 165 Display run time statistics. (Requires Perl Time::HiRes module)
 166 .IP "-rf"
 167 Display full run time statistics. (Requires Perl Time::HiRes module)
 168 .IP "-rm"
 169 Force removal of files by killing locking processes. (Windows only,
 170 requires Sysinternals handle[64].exe to be on PATH)
 171 .IP "--repeat=[num]"
 172 This will repeat the given set of test numbers this many times. If no test
 173 numbers are given, it will repeat ALL tests this many times. It iteratively
 174 adds the new sequence at the end of the initially given one.
 175
 176 If \fB-R\fP is also used, the scrambling is done after the repeats have
 177 extended the test sequence.
 178 .IP "-s"
 179 Shorter output. Speaks less than default.
 180 .IP "--seed=[num]"
 181 When using \fI--shallow\fP or \fI-R\fP that randomize certain aspects of the
 182 behavior, this option can set the initial seed. If not set, the random seed
 183 will be set based on the currently set local year and month and the first line
 184 of the "curl -V" output.
 185 .IP "--shallow=[num]"
 186 Used together with \fB-t\fP. This limits the number of tests to fail in
 187 torture mode to no more than 'num' per test case. If this reduces the amount,
 188 the script will randomly discard entries to fail until the amount is 'num'.
 189
 190 The random seed initially set for this is fixed per month and can be set with
 191 \fI--seed\fP.
 192 .IP "-t[num]"
 193 Selects a \fBtorture\fP test for the given tests. This makes runtests.pl first
 194 run the tests once and count the number of memory allocations made. It then
 195 reruns the test that number of times, each time forcing one of the allocations
 196 to fail until all allocs have been tested. By setting \fInum\fP you can force
 197 the allocation with that number to be set to fail at once instead of looping
 198 through everyone, which is very handy when debugging and then often in
 199 combination with \fI-g\fP.
 200 .IP "-u"
 201 Error instead of warning on server unexpectedly alive.
 202 .IP "-v"
 203 Enable verbose output. Speaks more than by default. If used in conjunction with
 204 parallel testing, it will be difficult to associate the logs with the test
 205 being run.
 206 .IP "-vc <curl>"
 207 Provide a path to a custom curl binary to run when verifying that the servers
 208 running are indeed our test servers. Default is the curl executable in the
 209 build tree.
 210 .SH "RUNNING TESTS"
 211 Many tests have conditions that must be met before the test case can run
 212 fine. They could depend on built-in features in libcurl or features present in
 213 the operating system or even in third-party libraries that curl may or may not
 214 use.
 215 .P
 216 The test script checks most of these by itself to determine when it is
 217 safe to attempt to run each test.  Those which cannot be run due to
 218 failed requirements will simply be skipped and listed at the completion
 219 of all test cases.  In some unusual configurations, the test script
 220 cannot make the correct determination for all tests.  In these cases,
 221 the problematic tests can be skipped using the "!keyword" skip feature
 222 documented earlier.
 223 .SH "WRITING TESTS"
 224 The simplest way to write test cases is to start with a similar existing test,
 225 save it with a new number and then adjust it to fit. There's an attempt to
 226 document the test case file format in the tests/FILEFORMAT.md.