1 The test suite's file format is very simple and extensible, closely 2resembling XML. All data for a single test case resides in a single 3ASCII file. Labels mark the beginning and the end of all sections, and each 4label must be written in its own line. Comments are either XML-style 5(enclosed with <!-- and -->) or C-style (beginning with #) and must appear 6on their own lines and not alongside actual test data. Most test data files 7are syntactically valid XML, although a few files are not (lack of 8support for character entities and the preservation of CR/LF characters at 9the end of lines are the biggest differences). 10 11 The file begins with a 'testcase' tag, which encompasses the remainder of 12the file. 13 14<testcase> 15 16 Each file is split up in three main sections: reply, client and verify. The 17reply section is used for the server to know what to send as a reply for the 18requests curl sends, the client section defines how the client should behave 19while the verify section defines how to verify that the data stored after a 20command has been run ended up correctly. 21 22 Each main section has a number of available subsections that can be 23specified, that will be checked/used if specified. This document includes all 24the subsections currently supported. 25 26Main sections are 'info', 'reply', 'client' and 'verify'. 27 28<info> 29<keywords> 30A newline-separated list of keywords describing what this test case uses and 31tests. Try to use an already used keyword. These keywords will be used for 32statistical/informational purposes and for choosing or skipping classes 33of tests. "Keywords" must begin with an alphabetic character, "-", "[" 34or "{" and may actually consist of multiple words separated by spaces 35which are treated together as a single identifier. 36</keywords> 37</info> 38 39<reply> 40<data [nocheck="yes"] [sendzero="yes"] [base64="yes"]> 41data to be sent to the client on its request and later verified that it arrived 42safely. Set nocheck="yes" to prevent the test script from verifying the arrival 43of this data. 44 45If the data contains 'swsclose' anywhere within the start and end tag, and 46this is a HTTP test, then the connection will be closed by the server after 47this response is sent. If not, the connection will be kept persistent. 48 49If the data contains 'swsbounce' anywhere within the start and end tag, the 50HTTP server will detect if this is a second request using the same test and 51part number and will then increase the part number with one. This is useful 52for auth tests and similar. 53 54'sendzero' set to yes means that the (FTP) server will "send" the data even if 55the size is zero bytes. Used to verify curl's behaviour on zero bytes 56transfers. 57 58'base64' set to yes means that the data provided in the test-file is a chunk 59of data encoded with base64. It is the only way a test case can contain binary 60data. (This attribute can in fact be used on any section, but it doesn't make 61much sense for other sections than "data"). 62</data> 63<dataNUM> 64Send back this contents instead of the <data> one. The num is set by: 65A) The test number in the request line is >10000 and this is the remainder 66of [test case number]%10000. 67B) The request was HTTP and included digest details, which adds 1000 to NUM 68C) If a HTTP request is NTLM type-1, it adds 1001 to num 69D) If a HTTP request is NTLM type-3, it adds 1002 to num 70E) If a HTTP request is Basic and num is already >=1000, it adds 1 to num 71 72Dynamically changing num in this way allows the test harness to be used to 73test authentication negotiation where several different requests must be sent 74to complete a transfer. The response to each request is found in its own data 75section. Validating the entire negotiation sequence can be done by 76specifying a datacheck section. 77</dataNUM> 78<datacheck [nonewline="yes"]> 79if the data is sent but this is what should be checked afterwards. If 80'nonewline' is set, we will cut off the trailing newline of this given data 81before comparing with the one actually received by the client 82</datacheck> 83<size> 84number to return on a ftp SIZE command (set to -1 to make this command fail) 85</size> 86<mdtm> 87what to send back if the client sends a (FTP) MDTM command, set to -1 to 88have it return that the file doesn't exist 89</mdtm> 90<postcmd> 91special purpose server-command to control its behavior *after* the 92reply is sent 93For HTTP/HTTPS, these are supported: 94 95wait [secs] 96 - Pause for the given time 97</postcmd> 98<servercmd> 99Special-commands for the server. 100For FTP, these are supported: 101 102REPLY [command] [return value] [response string] 103 - Changes how the server responds to the [command]. [response string] is 104 evaluated as a perl string, so it can contain embedded \r\n, for example. 105COUNT [command] [num] 106 - Do the REPLY change for [command] only [num] times and then go back to the 107 built-in approach 108DELAY [command] [secs] 109 - Delay responding to this command for the given time 110RETRWEIRDO 111 - Enable the "weirdo" RETR case when multiple response lines appear at once 112 when a file is transfered 113RETRNOSIZE 114 - Make sure the RETR response doesn't contain the size of the file 115NOSAVE 116 - Don't actually save what is received 117SLOWDOWN 118 - Send FTP responses with 0.01 sec delay between each byte 119PASVBADIP 120 - makes PASV send back an illegal IP in its 227 response 121 122For HTTP/HTTPS: 123auth_required if this is set and a POST/PUT is made without auth, the 124 server will NOT wait for the full request body to get sent 125idle do nothing after receiving the request, just "sit idle" 126stream continuously send data to the client, never-ending 127writedelay: [secs] delay this amount between reply packets 128pipe: [num] tell the server to expect this many HTTP requests before 129 sending back anything, to allow pipelining tests 130skip: [num] instructs the server to ignore reading this many bytes from a PUT 131 or POST request 132 133rtp: part [num] channel [num] size [num] 134 stream a fake RTP packet for the given part on a chosen channel 135 with the given payload size 136</servercmd> 137</reply> 138 139<client> 140 141<server> 142What server(s) this test case requires/uses: 143 144file 145ftp 146ftp-ipv6 147ftps 148http 149http-ipv6 150https 151none 152scp 153sftp 154socks4 155socks5 156rtsp 157rtsp-ipv6 158imap 159pop3 160smtp 161http+tls-srp 162 163Give only one per line. This subsection is mandatory. 164</server> 165 166<features> 167A list of features that MUST be present in the client/library for this test to 168be able to run (if these features are not present, the test will be 169SKIPPED). Features testable here are: 170 171axTLS 172crypto 173getrlimit 174GnuTLS 175idn 176ipv6 177large_file 178libz 179netrc_debug 180NSS 181NTLM 182OpenSSL 183SSL 184socks 185unittest 186 187as well as each protocol that curl supports. A protocol only needs to be 188specified if it is different from the server (useful when the server 189is 'none'). 190</features> 191 192<killserver> 193Using the same syntax as in <server> but when mentioned here these servers 194are explicitly KILLED when this test case is completed. Only use this if there 195is no other alternatives. Using this of course requires subsequent tests to 196restart servers. 197</killserver> 198 199<precheck> 200A command line that if set gets run by the test script before the test. If an 201output is displayed by the command or if the return code is non-zero, the test 202will be skipped and the (single-line) output will be displayed as reason for 203not running the test. Variables are substituted as in the <command> section. 204</precheck> 205 206<postcheck> 207A command line that if set gets run by the test script after the test. If 208the command exists with a non-zero status code, the test will be considered 209to have failed. Variables are substituted as in the <command> section. 210</postcheck> 211 212<tool> 213Name of tool to use instead of "curl". This tool must be built and exist 214either in the libtest/ directory (if the tool starts with 'lib') or in the 215unit/ directory (if the tool starts with 'unit'). 216</tool> 217 218<name> 219test case description 220</name> 221 222<setenv> 223variable1=contents1 224variable2=contents2 225 226Set the given environment variables to the specified value before the actual 227command is run. They are cleared again after the command has been run. 228Variables are first substituted as in the <command> section. 229</setenv> 230 231<command [option="no-output"] [timeout="secs"] [delay="secs"] [type="perl"]> 232command line to run, there's a bunch of %variables that get replaced 233accordingly. 234 235Note that the URL that gets passed to the server actually controls what data 236that is returned. The last slash in the URL must be followed by a number. That 237number (N) will be used by the test-server to load test case N and return the 238data that is defined within the <reply><data></data></reply> section. 239 240If a CONNECT is used to the server (to emulate HTTPS etc over proxy), the port 241number given in the CONNECT request will be used to identify which test that 242is being run, if the proxy host name is said to start with 'test'. 243 244Set type="perl" to write the test case as a perl script. It implies that 245there's no memory debugging and valgrind gets shut off for this test. 246 247Set option="no-output" to prevent the test script to slap on the --output 248argument that directs the output to a file. The --output is also not added if 249the verify/stdout section is used. 250 251Set timeout="secs" to override default server logs advisor read lock timeout. 252This timeout is used by the test harness, once that the command has completed 253execution, to wait for the test server to write out server side log files and 254remove the lock that advised not to read them. The "secs" parameter is the not 255negative integer number of seconds for the timeout. This 'timeout' attribute 256is documented for completeness sake, but is deep test harness stuff and only 257needed for very singular and specific test cases. Avoid using it. 258 259Set delay="secs" to introduce a time delay once that the command has completed 260execution and before the <postcheck> section runs. The "secs" parameter is the 261not negative integer number of seconds for the delay. This 'delay' attribute 262is intended for very specific test cases, and normally not needed. 263 264Available substitute variables include: 265%CLIENTIP - IPv4 address of the client running curl 266%CLIENT6IP - IPv6 address of the client running curl 267%HOSTIP - IPv4 address of the host running this test 268%HOSTPORT - Port number of the HTTP server 269%HOST6IP - IPv6 address of the host running this test 270%HOST6PORT - IPv6 port number of the HTTP server 271%HTTPSPORT - Port number of the HTTPS server 272%FTPPORT - Port number of the FTP server 273%FTP6PORT - IPv6 port number of the FTP server 274%FTPSPORT - Port number of the FTPS server 275%FTP2PORT - Port number of the FTP server 2 276%FTPTIME2 - Timeout in seconds that should be just sufficient to receive 277 a response from the test FTP server 278%TFTPPORT - Port number of the TFTP server 279%TFTP6PORT - IPv6 port number of the TFTP server 280%SSHPORT - Port number of the SCP/SFTP server 281%SOCKSPORT - Port number of the SOCKS4/5 server 282%RTSPPORT - Port number of the RTSP server 283%RTSP6PORT - IPv6 port number of the RTSP server 284%SRCDIR - Full path to the source dir 285%PWD - Current directory 286%CURL - Path to the curl executable 287%USER - Login ID of the user running the test 288</command> 289 290<file name="log/filename"> 291This creates the named file with this content before the test case is run, 292which is useful if the test case needs a file to act on. 293Variables are substituted on the contents of the file as in the <command> 294section. 295</file> 296 297<stdin> 298Pass this given data on stdin to the tool. 299</stdin> 300 301</client> 302 303<verify> 304<errorcode> 305numerical error code curl is supposed to return. Specify a list of accepted 306error codes by separating multiple numbers with comma. See test 237 for an 307example. 308</errorcode> 309<strip> 310One regex per line that is removed from the protocol dumps before the 311comparison is made. This is very useful to remove dependencies on dynamically 312changing protocol data such as port numbers or user-agent strings. 313</strip> 314<strippart> 315One perl op per line that operates on the protocol dump. This is pretty 316advanced. Example: "s/^EPRT .*/EPRT stripped/" 317</strippart> 318<protocol [nonewline="yes"]> 319the protocol dump curl should transmit, if 'nonewline' is set, we will cut 320off the trailing newline of this given data before comparing with the one 321actually sent by the client 322Variables are substituted as in the <command> section. 323</protocol> 324<stdout [mode="text"] [nonewline="yes"]> 325This verifies that this data was passed to stdout. Variables are 326substituted as in the <command> section. 327 328Use the mode="text" attribute if the output is in text mode on platforms that 329have a text/binary difference. 330 331If 'nonewline' is set, we will cut off the trailing newline of this given data 332before comparing with the one actually received by the client 333</stdout> 334<file name="log/filename" [mode="text"]> 335The file's contents must be identical to this after the test is complete. 336Use the mode="text" attribute if the output is in text mode on platforms that 337have a text/binary difference. 338Variables are substituted as in the <command> section. 339</file> 340<stripfile> 341One perl op per line that operates on the file before being compared. This is 342pretty advanced. Example: "s/^EPRT .*/EPRT stripped/" 343</stripfile> 344<upload> 345the contents of the upload data curl should have sent 346</upload> 347<valgrind> 348disable - disables the valgrind log check for this test 349</valgrind> 350</verify> 351 352</testcase> 353