.\" Man page generated from reStructuredText. . .TH VTC 7 "" "" "" .SH NAME VTC \- Varnish Test Case Syntax . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH OVERVIEW .sp This document describes the syntax used by Varnish Test Cases files (.vtc). A vtc file describe a scenario with different scripted HTTP\-talking entities, and generally one or more Varnish instances to test. .SH PARSING .sp A vtc file will be read word after word, with very little tokenization, meaning a syntax error won\(aqt be detected until the test actually reach the relevant action in the test. .sp A parsing error will most of the time result in an assert being triggered. If this happens, please refer yourself to the related source file and line number. However, this guide should help you avoid the most common mistakes. .SS Words and strings .sp The parser splits words by detecting whitespace characters and a string is a word, or a series of words on the same line enclosed by double\-quotes ("..."), or, for multi\-line strings, enclosed in curly brackets ({...}). .SS Comments .sp The leading whitespaces of lines are ignored. Empty lines (or ones consisting only of whitespaces) are ignored too, as are the lines starting with "#" that are comments. .SS Lines and commands .sp Test files take at most one command per line, with the first word of the line being the command and the following ones being its arguments. To continue over to a new line without breaking the argument string, you can escape the newline character (n) with a backslash (). .SH SYNTAX .SS barrier .sp NOTE: this can be used from the top\-level as well as from client and server specifications. .sp Barriers allows you to synchronize different threads to make sure events occur in the right order. It\(aqs even possible to use them in VCL. .sp First, it\(aqs necessary to declare the barrier: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C barrier bNAME TYPE NUMBER [\-cyclic] .ft P .fi .UNINDENT .UNINDENT .sp With the arguments being: .INDENT 0.0 .TP .B bNAME this is the name of the barrier, used to identify it when you\(aqll create sync points. It must start with \(aqb\(aq. .TP .B TYPE it can be "cond" (mutex) or "sock" (socket) and sets internal behavior. If you don\(aqt need VCL synchronization, use cond. .TP .B NUMBER number of sync point needed to go through the barrier. .TP .B \-cyclic if present, the barrier will reset itself and be ready for another round once gotten through. .UNINDENT .sp Then, to add a sync point: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C barrier bNAME sync .ft P .fi .UNINDENT .UNINDENT .sp This will block the parent thread until the number of sync points for bNAME reaches the NUMBER given in the barrier declaration. .sp If you wish to synchronize the VCL, you need to declare a "sock" barrier. This will emit a macro definition named "bNAME_sock" that you can use in VCL (after importing the debug vmod): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C debug.barrier_sync("${bNAME_sock}"); .ft P .fi .UNINDENT .UNINDENT .sp This function returns 0 if everything went well and is the equivalent of \fBbarrier bNAME sync\fP at the VTC top\-level. .SS client/server .sp Client and server threads are fake HTTP entities used to test your Varnish and VCL. They take any number of arguments, and the one that are not recognized, assuming they don\(aqt start with \(aq\-\(aq, are treated as specifications, laying out the actions to undertake: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C client cNAME [...] server sNAME [...] .ft P .fi .UNINDENT .UNINDENT .sp Clients and server are identified by a string that\(aqs the first argument, clients\(aq names start with \(aqc\(aq and servers\(aq names start with \(aqs\(aq. .sp As the client and server commands share a good deal of arguments and specification actions, they are grouped in this single section, specific items will be explicitly marked as such. .SS Arguments .INDENT 0.0 .TP .B \-start Start the thread in background, processing the last given specification. .TP .B \-wait Block until the thread finishes. .TP .B \-run (client only) Equivalent to "\-start \-wait". .TP .B repeat NUMBER Instead of processing the specification only once, do it NUMBER times. .TP .B \-break (server only) Stop the server. .TP .B \-listen STRING (server only) Dictate the listening socket for the server. STRING is of the form "IP PORT". .TP .B \-connect STRING (client only) Indicate the server to connect to. STRING is also of the form "IP PORT". .TP .B \-dispatch (server only, s0 only) Normally, to keep things simple, server threads only handle one connection at a time, but the \-dispatch switch allows to accept any number of connection and handle them following the given spec. .sp However, \-dispatch is only allowed for the server name "s0". .TP .B \-proxy1 STRING (client only) Use the PROXY protocol version 1 for this connection. STRING is of the form "CLIENTIP:PORT SERVERIP:PORT". .TP .B \-proxy2 STRING (client only) Use the PROXY protocol version 2 for this connection. STRING is of the form "CLIENTIP:PORT SERVERIP:PORT". .UNINDENT .SS Macros and automatic behaviour .sp To make things easier in the general case, clients will connect by default to the first Varnish server declared and the \-vcl+backend switch of the \fBvarnish\fP command will add all the declared servers as backends. .sp Be careful though, servers will by default listen to the 127.0.0.1 IP and will pick a random port, and publish 3 macros: sNAME_addr, sNAME_port and sNAME_sock, but only once they are started. For varnishtest to create the vcl with the correct values, the server must be started when you use \-vcl+backend. .SS Specification .sp It\(aqs a string, either double\-quoted "like this", but most of the time enclosed in curly brackets, allowing multilining. Write a command per line in it, empty line are ignored, and long line can be wrapped by using a backslash. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C client c1 { txreq \-url /foo \e \-hdr "bar: baz" rxresp } \-run .ft P .fi .UNINDENT .UNINDENT .SS accept (server) .sp Close the potential current connection, and accept a new one. Note that this new connection is H/1. .INDENT 0.0 .TP .B accept (server only) Close the active connection (if any) and accept a new one. .TP .B barrier Same as for the top\-level barrier .TP .B chunked STRING Send STRING as chunked encoding. .TP .B chunkedlen NUMBER Do as \fBchunked\fP except that varnishtest will generate the string for you, with a length of NUMBER characters. .UNINDENT .SS close (server) .sp Close the connection. Not that if operating in H/2 mode, no extra (GOAWAY) frame is sent, it\(aqs simply a TCP close. .SS close (server) .sp Close the connection. Not that if operating in H/2 mode, no extra (GOAWAY) frame is sent, it\(aqs simply a TCP close. .INDENT 0.0 .TP .B delay Same as for the top\-level delay. .TP .B delay Same as for the top\-level delay. .TP .B expect STRING1 OP STRING2 Test if "STRING1 OP STRING2" is true, and if not, fails the test. OP can be ==, <, <=, >, >= when STRING1 and STRING2 represent numbers in which case it\(aqs an order operator. If STRING1 and STRING2 are meant as strings OP is a matching operator, either == (exact match) or ~ (regex match). .sp varnishtet will first try to resolve STRING1 and STRING2 by looking if they have special meanings, in which case, the resolved value is use for the test. Note that this value can be a string representing a number, allowing for tests such as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C expect req.http.x\-num > 2 .ft P .fi .UNINDENT .UNINDENT .sp Here\(aqs the list of recognized strings, most should be obvious as they either match VCL logic, or the txreq/txresp options: .INDENT 7.0 .IP \(bu 2 remote.ip .IP \(bu 2 remote.port .IP \(bu 2 req.method .IP \(bu 2 req.url .IP \(bu 2 req.proto .IP \(bu 2 resp.proto .IP \(bu 2 resp.status .IP \(bu 2 resp.reason .IP \(bu 2 resp.chunklen .IP \(bu 2 req.bodylen .IP \(bu 2 req.body .IP \(bu 2 resp.bodylen .IP \(bu 2 resp.body .IP \(bu 2 req.http.NAME .IP \(bu 2 resp.http.NAME .UNINDENT .UNINDENT .SS expect_close (server) .sp Reads from the connection, expecting nothing to read but an EOF. .SS expect_close (server) .sp Reads from the connection, expecting nothing to read but an EOF. .INDENT 0.0 .TP .B fatal|non\-fatal Control whether a failure of this entity should stop the test. .TP .B loop NUMBER STRING Process STRING as a specification, NUMBER times. .TP .B recv NUMBER Read NUMBER bytes from the connection. .TP .B rxchunk Receive an HTTP chunk .UNINDENT .SS rxpri (server) .sp Receive a preface, and if it matches, sets the server to H/2, aborts otherwise. .INDENT 0.0 .TP .B rxreq (server only) Receive and parse a request\(aqs headers and body. .TP .B rxreqbody (server only) Receive a request\(aqs body. .TP .B rxreqhdrs Receive and parse a request\(aqs headers (but not the body). .TP .B rxreqhdrs Receive and parse a request\(aqs headers (but not the body). .TP .B rxresp [\-no_obj] (client only) Receive and parse a response\(aqs headers and body. If \-no_obj is present, only get the headers. .TP .B rxrespbody Receive a response\(aqs body. .TP .B send STRING Push STRING on the connection. .TP .B send_n NUMBER STRING Write STRING on the socket NUMBER times. .TP .B send_urgent STRING Send string as TCP OOB urgent data. You will never need this. .TP .B sendhex STRING Send bytes as described by STRING. STRING should consist of hex pairs possibly separated by whitespace or newlines. For example: "0F EE a5 3df2". .TP .B settings \-dectbl INT Force internal H/2 settings to certain values. Currently only support setting the decoding table size. .TP .B timeout NUMBER Set the TCP timeout for this entity. .UNINDENT .SS txpri (client) .sp Send an H/2 preface ("PRI * HTTP/2.0\er\en\er\enSM\er\en\er\en") and set client to H/2. .INDENT 0.0 .TP .B txreq|txresp [...] Send a minimal request or response, but overload it if necessary. .sp txreq is client\-specific and txresp is server\-specific. .sp The only thing different between a request and a response, apart from who can send them is that the first line (request line vs status line), so all the options are prety much the same. .INDENT 7.0 .TP .B \-req STRING (txreq only) What method to use (default: "GET"). .TP .B \-url STRING (txreq only) What location to use (default "/"). .TP .B \-proto STRING What protocol use in the status line. (default: "HTTP/1.1"). .TP .B \-status NUMBER (txresp only) What status code to return (default 200). .TP .B \-msg STRING (txresp only) What message to put in the status line (default: "OK"). .UNINDENT .sp These three switches can appear in any order but must come before the following ones. .INDENT 7.0 .TP .B \-nolen Don\(aqt include a Content\-Length header in the response. .TP .B \-hdr STRING Add STRING as a header, it must follow this format: "name: value". It can be called multiple times. .UNINDENT .sp You can then use the arguments related to the body: .INDENT 7.0 .TP .B \-body STRING Input STRING as body. .TP .B \-bodylen NUMBER Generate and input a body that is NUMBER bytes\-long. .TP .B \-gziplevel NUMBER Set the gzip level (call it before any of the other gzip switches). .TP .B \-gzipresidual NUMBER Add extra gzip bits. You should never need it. .TP .B \-gzipbody STRING Zip STRING and send it as body. .TP .B \-gziplen NUMBER Combine \-body and \-gzipbody: create a body of length NUMBER, zip it and send as body. .UNINDENT .UNINDENT .SS stream .sp H/2 introduces the concept of streams, and these come with their own specification, and as it\(aqs quite big, have bee move to their own chapter. .SS err_shell .sp This is very similar to the the \fBshell\fP command, except it takes a first string as argument before the command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C err_shell "foo" "echo foo" .ft P .fi .UNINDENT .UNINDENT .sp err_shell expect the shell command to fail AND stdout to match the string, failing the test case otherwise. .SS feature .sp Test that the required feature(s) for a test are available, and skip the test otherwise. feature takes any number of arguments from this list: .INDENT 0.0 .TP .B SO_RCVTIMEO_WORKS The SO_RCVTIMEO socket option is working .TP .B 64bit The environment is 64 bits .TP .B !OSX The environment is not OSX .TP .B dns DNS lookups are working .TP .B topbuild varnishtest has been started with \(aq\-i\(aq .TP .B root varnishtest has been invoked by the root user .TP .B user_varnish The varnish user is present .TP .B user_vcache The vcache user is present .TP .B group_varnish The varnish group is present .TP .B cmd A command line that should execute with a zero exit status .UNINDENT .SS logexpect .sp Reads the VSL and looks for records matching a given specification. It will process records trying to match the first pattern, and when done, will continue processing, trying to match the following pattern. If a pattern isn\(aqt matched, the test will fail. .sp logexpect threads are declared this way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logexpect lNAME \-v [\-g ] [\-d 0|1] [\-q query] \e [vsl arguments] { expect expect ... } [\-start|\-wait] .ft P .fi .UNINDENT .UNINDENT .sp And once declared, you can start them, or wait on them: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logexpect lNAME <\-start|\-wait> .ft P .fi .UNINDENT .UNINDENT .sp With: .INDENT 0.0 .TP .B lNAME Name the logexpect thread, it must start with \(aql\(aq. .TP .B \-v id Specify the varnish instance to use (most of the time, id=v1). .TP .B \-g Start processing log records at the head of the log instead of the tail. .TP .B \-q query Filter records using a query expression, see \fBman vsl\-query\fP for more information. .TP .B \-start Start the logexpect thread in the background. .TP .B \-wait Wait for the logexpect thread to finish .UNINDENT .sp VSL arguments (similar to the varnishlog options): .INDENT 0.0 .TP .B \-b|\-c Process only backend/client records. .TP .B \-C Use caseless regex .TP .B \-i Include tags .TP .B \-I <[taglist:]regex> Include by regex .TP .B \-T Transaction end timeout .UNINDENT .sp And the arguments of the specifications lines are: .INDENT 0.0 .TP .B skip: [uint|*] Max number of record to skip .TP .B vxid: [uint|*|=] vxid to match .TP .B tag: [tagname|*|=] Tag to match against .TP .B regex: regular expression to match against (optional) (\(aq*\(aq is anything, \(aq=\(aq is the value of the last matched record) .UNINDENT .SS shell .sp Pass the string given as argument to a shell. If you have multiple commands to run, you can use curly barces to describe a multi\-lines script, eg: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C shell { echo begin cat /etc/fstab echo end } .ft P .fi .UNINDENT .UNINDENT .sp The vtc will fail if the return code of the shell is not 0. .SS stream .sp (note: this section is at the top\-level for easier navigation, but it\(aqs part of the client/server specification) .sp Streams map roughly to a request in H/2, a request is sent on stream N, the response too, then the stream is discarded. The main exception is the first stream, 0, that serves as coordinator. .sp Stream syntax follow the client/server one: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C stream ID [SPEC] [ACTION] .ft P .fi .UNINDENT .UNINDENT .sp ID is the H/2 stream number, while SPEC describes what will be done in that stream. .sp Note that, when parsing a stream action, if the entity isn\(aqt operating in H/2 mode, these spec is ran before: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C txpri/rxpri # client/server stream 0 { txsettings rxsettings txsettings \-ack rxsettings expect settings.ack == true } \-run .ft P .fi .UNINDENT .UNINDENT .sp And H/2 mode is then activated before parsing the specification. .SS Actions .INDENT 0.0 .TP .B \-start Run the specification in a thread, giving back control immediately. .TP .B \-wait Wait for the started thread to finish running the spec. .TP .B \-run equivalent to calling \fB\-start\fP then \fB\-wait\fP\&. .UNINDENT .SS Specification .sp The specification of a stream follows the exact same rules as one for a client or a server. .SS txreq, txresp, txcont, txpush .sp These four commands are about sending headers. txreq, txresp will send HEADER frames, txcont will send CONTINUATION frames, and txpush PUSH frames. The only difference between txreq and txresp are the default headers set by each of them. .INDENT 0.0 .TP .B \-noadd Do not add default headers. Useful to avoid duplicates when sending default headers using \fB\-hdr\fP, \fB\-idxHdr\fP and \fB\-litIdxHdr\fP\&. .TP .B \-status INT (txresp) Set the :status pseudo\-header. .TP .B \-url STRING (txreq, txpush) Set the :path pseudo\-header. .TP .B \-req STRING (txreq, txpush) Set the :method pseudo\-header. .TP .B \-scheme STRING (txreq, txpush) Set the :scheme pseudo\-header. .TP .B \-hdr STRING1 STRING2 Insert a header, STRING1 being the name, and STRING2 the value. .TP .B \-idxHdr INT Insert an indexed header, using INT as index. .TP .B \-litIdxHdr inc|not|never INT huf|plain STRING Insert an literal, indexed header. The first argument specify if the header should be added to the table, shouldn\(aqt, or mustn\(aqt be compressed if/when retransmitted. .sp INT is the idex of the header name to use. .sp The third argument informs about the Huffman encoding: yes (huf) or no (plain). .sp The last term is the literal value of the header. .TP .B \-litHdr inc|not|never huf|plain STRING1 huf|plain STRING2 Insert a literal header, with the same first argument as \fB\-litIdxHdr\fP\&. .sp The second and third terms tell what the name of the header is and if it should be Huffman\-encoded, while the last two do the same regarding the value. .TP .B \-body STRING (txreq, txresp) Specify a body, effectively putting STRING into a DATA frame after the HEADER frame is sent. .TP .B \-bodylen INT (txreq, txresp) Do the same thing as \fB\-body\fP but generate an string of INT length for you. .TP .B \-nostrend (txreq, txresp) Don\(aqt set the END_STREAM flag automatically, making the peer expect a body after the headers. .TP .B \-nohdrend Don\(aqt set the END_HEADERS flag automatically, making the peer expect more HEADER frames. .TP .B \-dep INT (txreq, txresp) Tell the peer that this content depends on the stream with the INT id. .TP .B \-ex (txreq, txresp) Make the dependency exclusive (\fB\-dep\fP is still needed). .TP .B \-weight (txreq, txresp) Set the weight for the dependency. .TP .B \-promised INT (txpush) The id of the promised stream. .TP .B \-pad STRING / \-padlen INT (txreq, txresp, txpush) Add string as padding to the frame, either the one you provided with \-pad, or one that is generated for you, of length INT is \-padlen case. .UNINDENT .SS txdata .sp By default, data frames are empty. The receiving end will know the whole body has been delivered thanks to the END_STREAM flag set in the last DATA frame, and txdata automatically set it. .INDENT 0.0 .TP .B \-data STRING Data to be embedded into the frame. .TP .B \-datalen INT Generate and INT\-bytes long string to be sent in the frame. .TP .B \-pad STRING / \-padlen INT Add string as padding to the frame, either the one you provided with \-pad, or one that is generated for you, of length INT is \-padlen case. .TP .B \-nostrend Don\(aqt set the END_STREAM flag, allowing to send more data on this stream. .UNINDENT .SS rxreq, rxresp .sp These are two convenience functions to receive headers and body of an incoming request or response. The only difference is that rxreq can only be by a server, and rxresp by a client. .SS rxpush .sp This works like \fBrxhdrs\fP, expecting a PUSH frame and then zero or more CONTINUATION frames. .INDENT 0.0 .TP .B \-all Keep waiting for CONTINUATION frames until END_HEADERS flag is seen. .TP .B \-some INT Retrieve INT \- 1 CONTINUATION frames after the PUSH frame. .UNINDENT .SS rxhdrs .sp \fBrxhdrs\fP will expect one HEADER frame, then, depending on the arguments, zero or more CONTINUATION frame. .INDENT 0.0 .TP .B \-all Keep waiting for CONTINUATION frames until END_HEADERS flag is seen. .TP .B \-some INT Retrieve INT \- 1 CONTINUATION frames after the HEADER frame. .UNINDENT .SS rxdata .sp Receiving data is done using the \fBrxdata\fP keywords and will retrieve one DATA frame, if you wish to receive more, you can use these two convenience arguments: .INDENT 0.0 .TP .B \-all keep waiting for DATA frame until one sets the END_STREAM flag .TP .B \-some INT retrieve INT DATA frames. .UNINDENT .SS delay .sp Take a float as argument and sleep for that number of seconds. .sp Receive a frame, any frame. .SS sendhex .sp Push bytes directly on the wire. sendhex takes exactly one argument: a string describing the bytes, in hex notation, will possible whitespaces between them. Here\(aqs an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sendhex "00 00 08 00 0900 8d" .ft P .fi .UNINDENT .UNINDENT .SS rxgoaway .sp Receive a GOAWAY frame .SS rxgoaway .sp Possible options include: .INDENT 0.0 .TP .B \-err STRING|INT set the error code to eplain the termination. The second argument can be a integer or the string version of the error code as found in rfc7540#7. .TP .B \-laststream INT the id of the "highest\-numbered stream identifier for which the sender of the GOAWAY frame might have taken some action on or might yet take action on". .TP .B \-debug specify the debug data, if any to append to the frame. .UNINDENT .SS rxping .sp Receive a PING frame .SS txping .sp Send PING frame. .INDENT 0.0 .TP .B \-data STRING specify the payload of the frame, with STRING being an 8\-char string. .TP .B \-ack set the ACK flag. .UNINDENT .SS rxprio .sp Receive a PRIORITY frame .SS txprio .sp Send a PRIORITY frame .INDENT 0.0 .TP .B \-stream INT indicate the id of the stream the sender stream depends on. .TP .B \-ex the dependency should be made exclusive (only this streams depends on the parent stream). .TP .B \-weight INT an 8\-bits integer is used to balance priority between streams depending on the same streams. .UNINDENT .SS rxrst .sp Receive a RST_STREAM frame .SS txrst .sp Send a RST_STREAM frame. By default, txrst will send a 0 error code (NO_ERROR). .INDENT 0.0 .TP .B \-err STRING|INT Sets the error code to be sent. The argument can be an integer or a string describing the error, such as NO_ERROR, or CANCEL (see rfc7540#11.4 for more strings). .UNINDENT .SS rxsettings .sp Receive a SETTINGS frame .SS txsettings .sp SETTINGS frames must be acknowledge, arguments are as follow (most of them are from rfc7540#6.5.2): .INDENT 0.0 .TP .B \-hdrtbl INT headers table size .TP .B \-push BOOL whether push frames are accepted or not .TP .B \-maxstreams INT maximum concurrent streams allowed .TP .B \-winsize INT sender\(aqs initial window size .TP .B \-framesize INT largest frame size authorized .TP .B \-hdrsize INT maximum size of the header list authorized .TP .B \-ack set the ack bit .UNINDENT .SS rxwinup .sp Receive a WINDOW_UPDATE frame .SS txwinup .sp Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the connection (from stream 0) or of the stream (any other stream). .INDENT 0.0 .TP .B \-size INT give INT credits to the peer. .UNINDENT .SS expect .sp expect in stream works as it does in client or server, except that the elements compared will be different. .sp Most of these elements will be frame specific, meaning that the last frame received on that stream must of the correct type. .sp Here the list of keywords you can look at. .SS varnish .sp Define and interact with varnish instances. .sp To define a Varnish server, you\(aqll use this syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C varnish vNAME [\-arg STRING] [\-vcl STRING] [\-vcl+backend STRING] [\-errvcl STRING STRING] [\-jail STRING] [\-proto PROXY] .ft P .fi .UNINDENT .UNINDENT .sp The first \fBvarnish vNAME\fP invocation will start the varnishd master process in the background, waiting for the \fB\-start\fP switch to actually start the child. .sp With: .INDENT 0.0 .TP .B vNAME Identify the Varnish server with a string, it must starts with \(aqv\(aq. .TP .B \-arg STRING Pass an argument to varnishd, for example "\-h simple_list". .TP .B \-vcl STRING Specify the VCL to load on this Varnish instance. You\(aqll probably want to use multi\-lines strings for this ({...}). .TP .B \-vcl+backend STRING Do the exact same thing as \-vcl, but adds the definition block of known backends (ie. already defined). .TP .B \-errvcl STRING1 STRING2 Load STRING2 as VCL, expecting it to fail, and Varnish to send an error string matching STRING2 .TP .B \-jail STRING Look at \fBman varnishd\fP (\-j) for more information. .TP .B \-proto PROXY Have Varnish use the proxy protocol. Note that PROXY here is the actual string. .UNINDENT .sp You can decide to start the Varnish instance and/or wait for several events: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C varnish vNAME [\-start] [\-wait] [\-wait\-running] [\-wait\-stopped] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-start Start the child process. .TP .B \-stop Stop the child process. .TP .B \-syntax Set the VCL syntax level (default: 4.0) .TP .B \-wait Wait for that instance to terminate. .TP .B \-wait\-running Wait for the Varnish child process to be started. .TP .B \-wait\-stopped Wait for the Varnish child process to stop. .TP .B \-cleanup Once Varnish is stopped, clean everything after it. This is only used in one test and you should never need it. .UNINDENT .sp Once Varnish is started, you can talk to it (as you would through \fBvarnishadm\fP) with these additional switches: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C varnish vNAME [\-cli STRING] [\-cliok STRING] [\-clierr STRING] [\-expect STRING OP NUMBER] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-cli STRING|\-cliok STRING|\-clierr STATUS STRING All three of these will send STRING to the CLI, the only difference is what they expect the return code to be. \-cli doesn\(aqt expect anything, \-cliok expects 200 and \-clierr expects STATUS .TP .B \-expect STRING OP NUMBER Look into the VSM and make sure the counter identified by STRING has a correct value. OP can be ==, >, >=, <, <=. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C varnish v1 \-expect SMA.s1.g_space > 1000000 .ft P .fi .UNINDENT .UNINDENT .TP .B \-vsc PATTERN Dump VSC counters matching PATTERN. The PATTERN is a \(aqglob\(aq style pattern (ie: fnmatch(3)) as used in shell filename expansion. To see all counters use pattern "*", to see all counters about requests use "\fIreq\fP". .UNINDENT .SS varnishtest .sp This should be the first command in your vtc as it will identify the test case with a short yet descriptive sentence. It takes exactly one argument, a string, eg: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C varnishtest "Check that varnishtest is actually a valid command" .ft P .fi .UNINDENT .UNINDENT .sp It will also print that string in the log. .SH HISTORY .sp This document has been written by Guillaume Quintard. .SH SEE ALSO .INDENT 0.0 .IP \(bu 2 \fIvarnishtest(1)\fP .UNINDENT .SH COPYRIGHT .sp This document is licensed under the same licence as Varnish itself. See LICENCE for details. .INDENT 0.0 .IP \(bu 2 Copyright (c) 2006\-2016 Varnish Software AS .UNINDENT .\" Generated by docutils manpage writer. .