tests: document more test identifiers and variables
[platform/upstream/curl.git] / tests / FILEFORMAT
index 5432b43..e484272 100644 (file)
@@ -59,6 +59,12 @@ transfers.
 of data encoded with base64. It is the only way a test case can contain binary
 data. (This attribute can in fact be used on any section, but it doesn't make
 much sense for other sections than "data").
+
+For FTP file listings, the <data> section will be used *only* if you make sure
+that there has been a CWD done first to a directory named 'test-[num]' where
+[num] is the test case number. Otherwise the ftp server can't know from which
+test file to load the list content.
+
 </data>
 <dataNUM>
 Send back this contents instead of the <data> one. The num is set by:
@@ -75,6 +81,11 @@ to complete a transfer. The response to each request is found in its own data
 section.  Validating the entire negotiation sequence can be done by
 specifying a datacheck section.
 </dataNUM>
+<connect>
+The connect section is used instead of the 'data' for all CONNECT
+requests. The remainder of the rules for the data section then apply but with
+a connect prefix.
+</connect>
 <datacheck [nonewline="yes"]>
 if the data is sent but this is what should be checked afterwards. If
 'nonewline' is set, we will cut off the trailing newline of this given data
@@ -97,11 +108,13 @@ wait [secs]
 </postcmd>
 <servercmd>
 Special-commands for the server.
-For FTP, these are supported:
+For FTP/SMTP/POP/IMAP, these are supported:
 
 REPLY [command] [return value] [response string]
  - Changes how the server responds to the [command]. [response string] is
    evaluated as a perl string, so it can contain embedded \r\n, for example.
+   There's a special [command] named "welcome" (without quotes) which is the
+   string sent immediately on connect as a welcome.
 COUNT [command] [num]
  - Do the REPLY change for [command] only [num] times and then go back to the
    built-in approach
@@ -118,6 +131,13 @@ SLOWDOWN
  - Send FTP responses with 0.01 sec delay between each byte
 PASVBADIP
  - makes PASV send back an illegal IP in its 227 response
+CAPA [capabilities]
+ - Enables support for and specifies a list of space separated capabilities to
+   return to the client for the IMAP CAPABILITY, POP3 CAPA and SMTP EHLO
+   commands
+AUTH [mechanisms]
+ - Enables support for SASL authentication and specifies a list of space
+   separated mechanisms for IMAP, POP3 and SMTP
 
 For HTTP/HTTPS:
 auth_required   if this is set and a POST/PUT is made without auth, the
@@ -133,6 +153,14 @@ skip: [num]     instructs the server to ignore reading this many bytes from a PU
 rtp: part [num] channel [num] size [num]
                stream a fake RTP packet for the given part on a chosen channel
                with the given payload size
+
+connection-monitor When used, this will log [DISCONNECT] to the server.input
+               log when the connection is disconnected.
+
+
+For TFTP:
+writedelay: [secs] delay this amount between reply packets (each packet being
+                   512 bytes payload)
 </servercmd>
 </reply>
 
@@ -147,20 +175,20 @@ ftp-ipv6
 ftps
 http
 http-ipv6
+http-proxy
 https
+httptls+srp
+httptls+srp-ipv6
+imap
 none
+pop3
+rtsp
+rtsp-ipv6
 scp
 sftp
+smtp
 socks4
 socks5
-rtsp
-rtsp-ipv6
-imap
-pop3
-smtp
-httptls+srp
-httptls+srp-ipv6
-http-proxy
 
 Give only one per line.  This subsection is mandatory.
 </server>
@@ -172,20 +200,22 @@ SKIPPED). Features testable here are:
 
 axTLS
 crypto
+debug
 getrlimit
 GnuTLS
 idn
 ipv6
 large_file
 libz
+Metalink
 NSS
 NTLM
 OpenSSL
-SSL
 socks
-unittest
-debug
+SSL
 TLS-SRP
+TrackMemory
+unittest
 
 as well as each protocol that curl supports.  A protocol only needs to be
 specified if it is different from the server (useful when the server
@@ -241,9 +271,12 @@ that is returned. The last slash in the URL must be followed by a number. That
 number (N) will be used by the test-server to load test case N and return the
 data that is defined within the <reply><data></data></reply> section.
 
-If a CONNECT is used to the server (to emulate HTTPS etc over proxy), the port
-number given in the CONNECT request will be used to identify which test that
-is being run, if the proxy host name is said to start with 'test'.
+If there's no test number found above, the HTTP test server will use the
+number following the last dot in the given hostname (made so that a CONNECT
+can still pass on test number) so that "foo.bar.123" gets treated as test case
+123. Alternatively, if an ipv6-address is provided to CONNECT, the last
+hexadecimal group in the address will be used as the test numer! For example
+the address "[1234::ff]" would be treated as test case 255.
 
 Set type="perl" to write the test case as a perl script. It implies that
 there's no memory debugging and valgrind gets shut off for this test.
@@ -269,29 +302,41 @@ not negative integer number of seconds for the delay. This 'delay' attribute
 is intended for very specific test cases, and normally not needed.
 
 Available substitute variables include:
-%CLIENTIP   - IPv4 address of the client running curl
-%CLIENT6IP  - IPv6 address of the client running curl
-%HOSTIP    - IPv4 address of the host running this test
-%HTTPPORT  - Port number of the HTTP server
-%HOST6IP   - IPv6 address of the host running this test
-%HTTP6PORT - IPv6 port number of the HTTP server
-%HTTPSPORT - Port number of the HTTPS server
-%PROXYPORT - Port number of the HTTP proxy
-%FTPPORT   - Port number of the FTP server
+%CLIENT6IP - IPv6 address of the client running curl
+%CLIENTIP  - IPv4 address of the client running curl
+%CURL      - Path to the curl executable
+%FTP2PORT  - Port number of the FTP server 2
 %FTP6PORT  - IPv6 port number of the FTP server
+%FTPPORT   - Port number of the FTP server
 %FTPSPORT  - Port number of the FTPS server
-%FTP2PORT  - Port number of the FTP server 2
 %FTPTIME2  - Timeout in seconds that should be just sufficient to receive
              a response from the test FTP server
-%TFTPPORT  - Port number of the TFTP server
-%TFTP6PORT - IPv6 port number of the TFTP server
-%SSHPORT   - Port number of the SCP/SFTP server
-%SOCKSPORT - Port number of the SOCKS4/5 server
-%RTSPPORT  - Port number of the RTSP server
+%FTPTIME3  - Even longer than %FTPTIME2
+%GOPHER6PORT  - IPv6 port number of the Gopher server
+%GOPHERPORT   - Port number of the Gopher server
+%HOST6IP      - IPv6 address of the host running this test
+%HOSTIP       - IPv4 address of the host running this test
+%HTTP6PORT    - IPv6 port number of the HTTP server
+%HTTPPIPEPORT - Port number of the HTTP pipelining server
+%HTTPPORT     - Port number of the HTTP server
+%HTTPSPORT    - Port number of the HTTPS server
+%HTTPTLS6PORT - IPv6 port number of the HTTP TLS server
+%HTTPTLSPORT  - Port number of the HTTP TLS server
+%IMAP6PORT - IPv6 port number of the IMAP server
+%IMAPPORT  - Port number of the IMAP server
+%POP36PORT - IPv6 ort number of the POP3 server
+%POP3PORT  - Port number of the POP3 server
+%PROXYPORT - Port number of the HTTP proxy
+%PWD       - Current directory
 %RTSP6PORT - IPv6 port number of the RTSP server
+%RTSPPORT  - Port number of the RTSP server
+%SMTP6PORT - IPv6 port number of the SMTP server
+%SMTPPORT  - Port number of the SMTP server
+%SOCKSPORT - Port number of the SOCKS4/5 server
 %SRCDIR    - Full path to the source dir
-%PWD       - Current directory
-%CURL      - Path to the curl executable
+%SSHPORT   - Port number of the SCP/SFTP server
+%TFTP6PORT - IPv6 port number of the TFTP server
+%TFTPPORT  - Port number of the TFTP server
 %USER      - Login ID of the user running the test
 </command>
 
@@ -302,8 +347,11 @@ Variables are substituted on the contents of the file as in the <command>
 section.
 </file>
 
-<stdin>
+<stdin [nonewline="yes"]>
 Pass this given data on stdin to the tool.
+
+If 'nonewline' is set, we will cut off the trailing newline of this given data
+before comparing with the one actually received by the client
 </stdin>
 
 </client>