1VTC(7) VTC(7)
2
6 VTC - Varnish Test Case Syntax
7
9 This document describes the syntax used by Varnish Test Cases files
10 (.vtc). A vtc file describe a scenario with different scripted
11 HTTP-talking entities, and generally one or more Varnish instances to
12 test.
13
15 A vtc file will be read word after word, with very little tokenization,
16 meaning a syntax error won't be detected until the test actually reach
17 the relevant action in the test.
18 A parsing error will most of the time result in an assert being trig‐
20 gered. If this happens, please refer yourself to the related source
21 file and line number. However, this guide should help you avoid the
22 most common mistakes.
23 Words and strings
25 The parser splits words by detecting whitespace characters and a string
26 is a word, or a series of words on the same line enclosed by dou‐
27 ble-quotes ("..."), or, for multi-line strings, enclosed in curly
28 brackets ({...}).
29 Comments
31 The leading whitespaces of lines are ignored. Empty lines (or ones con‐
32 sisting only of whitespaces) are ignored too, as are the lines starting
33 with "#" that are comments.
34 Lines and commands
36 Test files take at most one command per line, with the first word of
37 the line being the command and the following ones being its arguments.
38 To continue over to a new line without breaking the argument string,
39 you can escape the newline character (\n) with a backslash (\).
40
42 barrier
43 NOTE: This command is available everywhere commands are given.
44 Barriers allows you to synchronize different threads to make sure
46 events occur in the right order. It's even possible to use them in VCL.
47 First, it's necessary to declare the barrier:
49 barrier bNAME TYPE NUMBER [-cyclic]
51 With the arguments being:
53 bNAME this is the name of the barrier, used to identify it when you'll
55 create sync points. It must start with 'b'.
56 TYPE it can be "cond" (mutex) or "sock" (socket) and sets internal
58 behavior. If you don't need VCL synchronization, use cond.
59 NUMBER number of sync point needed to go through the barrier.
61 -cyclic
63 if present, the barrier will reset itself and be ready for an‐
64 other round once gotten through.
65 Then, to add a sync point:
67 barrier bNAME sync
69 This will block the parent thread until the number of sync points for
71 bNAME reaches the NUMBER given in the barrier declaration.
72 If you wish to synchronize the VCL, you need to declare a "sock" bar‐
74 rier. This will emit a macro definition named "bNAME_sock" that you
75 can use in VCL (after importing the debug vmod):
76 debug.barrier_sync("${bNAME_sock}");
78 This function returns 0 if everything went well and is the equivalent
80 of barrier bNAME sync at the VTC top-level.
81 client/server
83 Client and server threads are fake HTTP entities used to test your Var‐
84 nish and VCL. They take any number of arguments, and the one that are
85 not recognized, assuming they don't start with '-', are treated as
86 specifications, laying out the actions to undertake:
87 client cNAME [...]
89 server sNAME [...]
90 Clients and server are identified by a string that's the first argu‐
92 ment, clients' names start with 'c' and servers' names start with 's'.
93 As the client and server commands share a good deal of arguments and
95 specification actions, they are grouped in this single section, spe‐
96 cific items will be explicitly marked as such.
97 Arguments
99 -start Start the thread in background, processing the last given speci‐
100 fication.
101 -wait Block until the thread finishes.
103 -run (client only)
105 Equivalent to "-start -wait".
106 -repeat NUMBER
108 Instead of processing the specification only once, do it NUMBER
109 times.
110 -keepalive
112 For repeat, do not open new connections but rather run all iter‐
113 ations in the same connection
114 -break (server only)
116 Stop the server.
117 -listen STRING (server only)
119 Dictate the listening socket for the server. STRING is of the
120 form "IP PORT", or "/PATH/TO/SOCKET" for a Unix domain socket.
121 In the latter case, the path must begin with '/', and the server
122 must be able to create it.
123 -connect STRING (client only)
125 Indicate the server to connect to. STRING is also of the form
126 "IP PORT", or "/PATH/TO/SOCKET". As with "server -listen", a
127 Unix domain socket is recognized when STRING begins with a '/'.
128 -dispatch (server only, s0 only)
130 Normally, to keep things simple, server threads only handle one
131 connection at a time, but the -dispatch switch allows to accept
132 any number of connection and handle them following the given
133 spec.
134 However, -dispatch is only allowed for the server name "s0".
136 -proxy1 STRING (client only)
138 Use the PROXY protocol version 1 for this connection. STRING is
139 of the form "CLIENTIP:PORT SERVERIP:PORT".
140 -proxy2 STRING (client only)
142 Use the PROXY protocol version 2 for this connection. STRING is
143 of the form "CLIENTIP:PORT SERVERIP:PORT".
144 Macros and automatic behaviour
146 To make things easier in the general case, clients will connect by de‐
147 fault to a Varnish server called v1. To connect to a different Varnish
148 server, use '-connect ${vNAME_sock}'.
149 The -vcl+backend switch of the varnish command will add all the de‐
151 clared servers as backends. Be careful though, servers will by default
152 listen to the 127.0.0.1 IP and will pick a random port, and publish 3
153 macros: sNAME_addr, sNAME_port and sNAME_sock, but only once they are
154 started. For 'varnish -vcl+backend' to create the vcl with the correct
155 values, the server must be started first.
156 Specification
158 It's a string, either double-quoted "like this", but most of the time
159 enclosed in curly brackets, allowing multilining. Write a command per
160 line in it, empty line are ignored, and long line can be wrapped by us‐
161 ing a backslash. For example:
162 client c1 {
164 txreq -url /foo \
165 -hdr "bar: baz"
166 rxresp
168 } -run
169 accept (server only)
171 Close the current connection, if any, and accept a new one. Note
172 that this new connection is HTTP/1.x.
173 chunked STRING
175 Send STRING as chunked encoding.
176 chunkedlen NUMBER
178 Do as chunked except that the string will be generated for you,
179 with a length of NUMBER characters.
180 close (server only)
182 Close the connection. Note that if operating in HTTP/2 mode no
183 extra (GOAWAY) frame is sent, it's simply a TCP close.
184 expect STRING1 OP STRING2
186 Test if "STRING1 OP STRING2" is true, and if not, fails the
187 test. OP can be ==, <, <=, >, >= when STRING1 and STRING2 rep‐
188 resent numbers in which case it's an order operator. If STRING1
189 and STRING2 are meant as strings OP is a matching operator, ei‐
190 ther == (exact match) or ~ (regex match).
191 varnishtest will first try to resolve STRING1 and STRING2 by
193 looking if they have special meanings, in which case, the re‐
194 solved value is use for the test. Note that this value can be a
195 string representing a number, allowing for tests such as:
196 expect req.http.x-num > 2
198 Here's the list of recognized strings, most should be obvious as
200 they either match VCL logic, or the txreq/txresp options:
201 • remote.ip
203 • remote.port
205 • remote.path
207 • req.method
209 • req.url
211 • req.proto
213 • resp.proto
215 • resp.status
217 • resp.reason
219 • resp.chunklen
221 • req.bodylen
223 • req.body
225 • resp.bodylen
227 • resp.body
229 • req.http.NAME
231 • resp.http.NAME
233 expect_close
235 Reads from the connection, expecting nothing to read but an EOF.
236 fatal|non_fatal
238 Control whether a failure of this entity should stop the test.
239 gunzip Gunzip the body in place.
241 recv NUMBER
243 Read NUMBER bytes from the connection.
244 rxchunk
246 Receive an HTTP chunk.
247 rxpri (server only)
249 Receive a preface. If valid set the server to HTTP/2, abort oth‐
250 erwise.
251 rxreq (server only)
253 Receive and parse a request's headers and body.
254 rxreqbody (server only)
256 Receive a request's body.
257 rxreqhdrs (server only)
259 Receive and parse a request's headers (but not the body).
260 rxresp [-no_obj] (client only)
262 Receive and parse a response's headers and body. If -no_obj is
263 present, only get the headers.
264 rxrespbody (client only)
266 Receive (part of) a response's body.
267 -max : max length of this receive, 0 for all
269 rxresphdrs (client only)
271 Receive and parse a response's headers.
272 send STRING
274 Push STRING on the connection.
275 send_n NUMBER STRING
277 Write STRING on the socket NUMBER times.
278 send_urgent STRING
280 Send string as TCP OOB urgent data. You will never need this.
281 sendhex STRING
283 Send bytes as described by STRING. STRING should consist of hex
284 pairs possibly separated by whitespace or newlines. For example:
285 "0F EE a5 3df2".
286 settings -dectbl INT
288 Force internal HTTP/2 settings to certain values. Currently only
289 support setting the decoding table size.
290 shell Same as for the top-level shell.
292 stream HTTP/2 introduces the concept of streams, and these come with
294 their own specification, and as it's quite big, have been moved
295 to their own chapter.
296 timeout NUMBER
298 Set the TCP timeout for this entity.
299 txpri (client only)
301 Send an HTTP/2 preface ("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n") and
302 set client to HTTP/2.
303 txreq|txresp [...]
305 Send a minimal request or response, but overload it if neces‐
306 sary.
307 txreq is client-specific and txresp is server-specific.
309 The only thing different between a request and a response, apart
311 from who can send them is that the first line (request line vs
312 status line), so all the options are prety much the same.
313 -method STRING (txreq only)
315 What method to use (default: "GET").
316 -req STRING (txreq only)
318 Alias for -method.
319 -url STRING (txreq only)
321 What location to use (default "/").
322 -proto STRING
324 What protocol use in the status line. (default:
325 "HTTP/1.1").
326 -status NUMBER (txresp only)
328 What status code to return (default 200).
329 -reason STRING (txresp only)
331 What message to put in the status line (default: "OK").
332 These three switches can appear in any order but must come be‐
334 fore the following ones.
335 -nohost
337 Don't include a Host header in the request.
338 -nolen Don't include a Content-Length header.
340 -hdr STRING
342 Add STRING as a header, it must follow this format:
343 "name: value". It can be called multiple times.
344 -hdrlen STRING NUMBER
346 Add STRING as a header with NUMBER bytes of content.
347 You can then use the arguments related to the body:
349 -body STRING
351 Input STRING as body.
352 -bodyfrom FILE
354 Same as -body but content is read from FILE.
355 -bodylen NUMBER
357 Generate and input a body that is NUMBER bytes-long.
358 -gziplevel NUMBER
360 Set the gzip level (call it before any of the other gzip
361 switches).
362 -gzipresidual NUMBER
364 Add extra gzip bits. You should never need it.
365 -gzipbody STRING
367 Gzip STRING and send it as body.
368 -gziplen NUMBER
370 Combine -bodylen and -gzipbody: generate a string of
371 length NUMBER, gzip it and send as body.
372 write_body STRING
374 Write the body of a request or a response to a file. By using
375 the shell command, higher-level checks on the body can be per‐
376 formed (eg. XML, JSON, ...) provided that such checks can be
377 delegated to an external program.
378 delay
380 NOTE: This command is available everywhere commands are given.
381 Sleep for the number of seconds specified in the argument. The number
383 can include a fractional part, e.g. 1.5.
384 err_shell
386 NOTICE: err_shell is deprecated, use shell -err -expect instead.
387 This is very similar to the the shell command, except it takes a first
389 string as argument before the command:
390 err_shell "foo" "echo foo"
392 err_shell expect the shell command to fail AND stdout to match the
394 string, failing the test case otherwise.
395 feature
397 Test that the required feature(s) for a test are available, and skip
398 the test otherwise; or change the interpretation of the test, as docu‐
399 mented below. feature takes any number of arguments from this list:
400 SO_RCVTIMEO_WORKS
402 The SO_RCVTIMEO socket option is working
403 64bit The environment is 64 bits
405 ipv4 127.0.0.1 work
407 ipv6 [::1] work
409 dns DNS lookups are working
411 topbuild
413 The test has been started with '-i'
414 root The test has been invoked by the root user
416 user_varnish
418 The varnish user is present
419 user_vcache
421 The vcache user is present
422 group_varnish
424 The varnish group is present
425 cmd <command-line>
427 A command line that should execute with a zero exit status
428 ignore_unknown_macro
430 Do not fail the test if a string of the form ${...} is not rec‐
431 ognized as a macro.
432 persistent_storage
434 Varnish was built with the deprecated persistent storage.
435 Be careful with ignore_unknown_macro, because it may cause a test with
437 a misspelled macro to fail silently. You should only need it if you
438 must run a test with strings of the form "${...}".
439 haproxy
441 Define and interact with haproxy instances.
442 To define a haproxy server, you'll use this syntax:
444 haproxy hNAME -conf-OK CONFIG
446 haproxy hNAME -conf-BAD ERROR CONFIG
447 haproxy hNAME [-D] [-W] [-arg STRING] [-conf[+vcl] STRING]
448 The first haproxy hNAME invocation will start the haproxy master
450 process in the background, waiting for the -start switch to actually
451 start the child.
452 Arguments:
454 hNAME Identify the HAProxy server with a string, it must starts with
456 'h'.
457 -conf-OK CONFIG
459 Run haproxy in '-c' mode to check config is OK
461 stdout/stderr should contain 'Configuration file is
462 valid' The exit code should be 0.
463 -conf-BAD ERROR CONFIG
465 Run haproxy in '-c' mode to check config is BAD.
467 "ERROR" should be part of the diagnostics on std‐
468 out/stderr. The exit code should be 1.
469 -D Run HAproxy in daemon mode. If not given '-d' mode used.
471 -W Enable HAproxy in Worker mode.
473 -S Enable HAproxy Master CLI in Worker mode
475 -arg STRING
477 Pass an argument to haproxy, for example "-h simple_list".
478 -cli STRING
480 Specify the spec to be run by the command line interface (CLI).
481 -mcli STRING
483 Specify the spec to be run by the command line interface (CLI)
484 of the Master process.
485 -conf STRING
487 Specify the configuration to be loaded by this HAProxy instance.
488 -conf+backend STRING
490 Specify the configuration to be loaded by this HAProxy instance,
492 all server instances will be automatically appended
493 -start Start this HAProxy instance.
495 -wait Stop this HAProxy instance.
497 -expectexit NUMBER
499 Expect haproxy to exit(3) with this value
500 haproxy CLI Specification
502 expect OP STRING
503 Regex match the CLI reception buffer with STRING if OP is ~ or,
504 on the contraty, if OP is !~ check that there is no regex match.
505 send STRING
507 Push STRING on the CLI connection. STRING will be terminated by
508 an end of line character (n).
509 logexpect
511 Reads the VSL and looks for records matching a given specification. It
512 will process records trying to match the first pattern, and when done,
513 will continue processing, trying to match the following pattern. If a
514 pattern isn't matched, the test will fail.
515 logexpect threads are declared this way:
517 logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
519 [vsl arguments] {
520 expect <skip> <vxid> <tag> <regex>
521 expect <skip> <vxid> <tag> <regex>
522 fail add <vxid> <tag> <regex>
523 fail clear
524 ...
525 } [-start|-wait]
526 And once declared, you can start them, or wait on them:
528 logexpect lNAME <-start|-wait>
530 With:
532 lNAME Name the logexpect thread, it must start with 'l'.
534 -v id Specify the varnish instance to use (most of the time, id=v1).
536 -g <session|request|vxid|raw
538 Decide how records are grouped, see -g in man varnishlog for
539 more information.
540 -d <0|1>
542 Start processing log records at the head of the log instead of
543 the tail.
544 -q query
546 Filter records using a query expression, see man vsl-query for
547 more information. Multiple -q options are not supported.
548 -m Also emit log records for misses (only for debugging)
550 -err Invert the meaning of success. Usually called once to expect the
552 logexpect to fail
553 -start Start the logexpect thread in the background.
555 -wait Wait for the logexpect thread to finish
557 VSL arguments (similar to the varnishlog options):
559 -C Use caseless regex
561 -i <taglist>
563 Include tags
564 -I <[taglist:]regex>
566 Include by regex
567 -T <seconds>
569 Transaction end timeout
570 expect specification:
572 skip: [uint|*|?]
574 Max number of record to skip
575 vxid: [uint|*|=]
577 vxid to match
578 tag: [tagname|*|=]
580 Tag to match against
581 regex: regular expression to match against (optional)
583 For skip, vxid and tag, '*' matches anything, '=' expects the value of
585 the previous matched record. The '?' marker is equivalent to zero, ex‐
586 pecting a match on the next record. The difference is that '?' can be
587 used when the order of individual consecutive logs is not determinis‐
588 tic. In other words, lines from a block of alternatives marked by '?'
589 can be matched in any order, but all need to match eventually.
590 fail specification:
592 add: Add to the fail list
594 Arguments are equivalent to expect, except for skip missing
595 clear: Clear the fail list
597 Any number of fail specifications can be active during execution of a
599 logexpect. All active fail specifications are matched against every log
600 line and, if any match, the logexpect fails immediately.
601 For a logexpect to end successfully, there must be no specs on the fail
603 list, so logexpects should always end with
604 expect <skip> <vxid> <tag> <termination-condition> fail clear
605 XXX can we come up with a better solution which is still safe?
607 loop
609 loop NUMBER STRING
610 Process STRING as a specification, NUMBER times.
611 This works inside all specification strings
613 process
615 Run a process with stdin+stdout on a pseudo-terminal and stderr on a
616 pipe.
617 Output from the pseudo-terminal is copied verbatim to ${pNAME_out}, and
619 the -log/-dump/-hexdump flags will also put it in the vtc-log.
620 The pseudo-terminal is not in ECHO mode, but if the programs run set it
622 to ECHO mode ("stty sane") any input sent to the process will also ap‐
623 pear in this stream because of the ECHO.
624 Output from the stderr-pipe is copied verbatim to ${pNAME_err}, and is
626 always included in the vtc_log.
627 process pNAME SPEC [-log] [-dump] [-hexdump] [-expect-exit N]
629 [-start] [-run] [-write STRING] [-writeln STRING] [-kill
630 STRING] [-stop] [-wait] [-close]
631 pNAME Name of the process. It must start with 'p'.
633 SPEC The command(s) to run in this process.
635 -hexdump
637 Log output with vtc_hexdump(). Must be before -start/-run.
638 -dump Log output with vtc_dump(). Must be before -start/-run.
640 -log Log output with VLU/vtc_log(). Must be before -start/-run.
642 -start Start the process.
644 -expect-exit N
646 Expect exit status N
647 -wait Wait for the process to finish.
649 -run Shorthand for -start -wait.
651 In most cases, if you just want to start a process and wait for
653 it to finish, you can use the shell command instead. The fol‐
654 lowing commands are equivalent:
655 shell "do --something"
657 process p1 "do --something" -run
659 However, you may use the the process variant to conveniently
661 collect the standard input and output without dealing with shell
662 redirections yourself. The shell command can also expect an ex‐
663 pression from either output, consider using it if you only need
664 to match one.
665 -kill STRING
667 Send a signal to the process. The argument can be either the
668 string "TERM", "INT", or "KILL" for SIGTERM, SIGINT or SIGKILL
669 signals, respectively, or a hyphen (-) followed by the signal
670 number.
671 If you need to use other signal names, you can use the kill(1)
673 command directly:
674 shell "kill -USR1 ${pNAME_pid}"
676 Note that SIGHUP usage is discouraged in test cases.
678 -stop Shorthand for -kill TERM.
680 -write STRING
682 Write a string to the process' stdin.
683 -writeln STRING
685 Same as -write followed by a newline (\n).
686 -writehex HEXSTRING
688 Same as -write but interpreted as hexadecimal bytes.
689 -need-bytes [+]NUMBER
691 Wait until at least NUMBER bytes have been received in total.
692 If '+' is prefixed, NUMBER new bytes must be received.
693 -expect-text LIN COL PAT
695 Wait for PAT to appear at LIN,COL on the virtual screen. Lines
696 and columns are numbered 1...N LIN==0 means "on any line" COL==0
697 means "anywhere on the line"
698 -close Alias for "-kill HUP"
700 -screen_dump
702 Dump the virtual screen into vtc_log
703 setenv
705 Set or change an environment variable:
706 setenv FOO "bar baz"
708 The above will set the environment variable $FOO to the value provided.
710 There is also an -ifunset argument which will only set the value if the
711 the environment variable does not already exist:
712 setenv -ifunset FOO quux
714 shell
716 NOTE: This command is available everywhere commands are given.
717 Pass the string given as argument to a shell. If you have multiple com‐
719 mands to run, you can use curly brackets to describe a multi-lines
720 script, eg:
721 shell {
723 echo begin
724 cat /etc/fstab
725 echo end
726 }
727 By default a zero exit code is expected, otherwise the vtc will fail.
729 Notice that the commandstring is prefixed with "exec 2>&1;" to combine
731 stderr and stdout back to the test process.
732 Optional arguments:
734 -err Expect non-zero exit code.
736 -exit N
738 Expect exit code N instead of zero.
739 -expect STRING
741 Expect string to be found in stdout+err.
742 -match REGEXP
744 Expect regexp to match the stdout+err output.
745 stream
747 (note: this section is at the top-level for easier navigation, but it's
748 part of the client/server specification)
749 Streams map roughly to a request in HTTP/2, a request is sent on stream
751 N, the response too, then the stream is discarded. The main exception
752 is the first stream, 0, that serves as coordinator.
753 Stream syntax follow the client/server one:
755 stream ID [SPEC] [ACTION]
757 ID is the HTTP/2 stream number, while SPEC describes what will be done
759 in that stream.
760 Note that, when parsing a stream action, if the entity isn't operating
762 in HTTP/2 mode, these spec is ran before:
763 txpri/rxpri # client/server
765 stream 0 {
766 txsettings
767 rxsettings
768 txsettings -ack
769 rxsettings
770 expect settings.ack == true
771 } -run
772 And HTTP/2 mode is then activated before parsing the specification.
774 Actions
776 -start Run the specification in a thread, giving back control immedi‐
777 ately.
778 -wait Wait for the started thread to finish running the spec.
780 -run equivalent to calling -start then -wait.
782 Specification
784 The specification of a stream follows the exact same rules as one for a
785 client or a server.
786 txreq, txresp, txcont, txpush
788 These four commands are about sending headers. txreq and txresp will
789 send HEADER frames; txcont will send CONTINUATION frames; txpush PUSH
790 frames. The only difference between txreq and txresp are the default
791 headers set by each of them.
792 -noadd Do not add default headers. Useful to avoid duplicates when
794 sending default headers using -hdr, -idxHdr and -litIdxHdr.
795 -status INT (txresp)
797 Set the :status pseudo-header.
798 -url STRING (txreq, txpush)
800 Set the :path pseudo-header.
801 -method STRING (txreq, txpush)
803 Set the :method pseudo-header.
804 -req STRING (txreq, txpush)
806 Alias for -method.
807 -scheme STRING (txreq, txpush)
809 Set the :scheme pseudo-header.
810 -hdr STRING1 STRING2
812 Insert a header, STRING1 being the name, and STRING2 the value.
813 -idxHdr INT
815 Insert an indexed header, using INT as index.
816 -litIdxHdr inc|not|never INT huf|plain STRING
818 Insert an literal, indexed header. The first argument specify if
819 the header should be added to the table, shouldn't, or mustn't
820 be compressed if/when retransmitted.
821 INT is the idex of the header name to use.
823 The third argument informs about the Huffman encoding: yes (huf)
825 or no (plain).
826 The last term is the literal value of the header.
828 -litHdr inc|not|never huf|plain STRING1 huf|plain STRING2
830 Insert a literal header, with the same first argument as
831 -litIdxHdr.
832 The second and third terms tell what the name of the header is
834 and if it should be Huffman-encoded, while the last two do the
835 same regarding the value.
836 -body STRING (txreq, txresp)
838 Specify a body, effectively putting STRING into a DATA frame af‐
839 ter the HEADER frame is sent.
840 -bodyfrom FILE (txreq, txresp)
842 Same as -body but content is read from FILE.
843 -bodylen INT (txreq, txresp)
845 Do the same thing as -body but generate a string of INT length
846 for you.
847 -gzipbody STRING (txreq, txresp)
849 Gzip STRING and send it as body.
850 -gziplen NUMBER (txreq, txresp)
852 Combine -bodylen and -gzipbody: generate a string of length NUM‐
853 BER, gzip it and send as body.
854 -nostrend (txreq, txresp)
856 Don't set the END_STREAM flag automatically, making the peer ex‐
857 pect a body after the headers.
858 -nohdrend
860 Don't set the END_HEADERS flag automatically, making the peer
861 expect more HEADER frames.
862 -dep INT (txreq, txresp)
864 Tell the peer that this content depends on the stream with the
865 INT id.
866 -ex (txreq, txresp)
868 Make the dependency exclusive (-dep is still needed).
869 -weight (txreq, txresp)
871 Set the weight for the dependency.
872 -promised INT (txpush)
874 The id of the promised stream.
875 -pad STRING / -padlen INT (txreq, txresp, txpush)
877 Add string as padding to the frame, either the one you provided
878 with -pad, or one that is generated for you, of length INT is
879 -padlen case.
880 txdata
882 By default, data frames are empty. The receiving end will know the
883 whole body has been delivered thanks to the END_STREAM flag set in the
884 last DATA frame, and txdata automatically set it.
885 -data STRING
887 Data to be embedded into the frame.
888 -datalen INT
890 Generate and INT-bytes long string to be sent in the frame.
891 -pad STRING / -padlen INT
893 Add string as padding to the frame, either the one you provided
894 with -pad, or one that is generated for you, of length INT is
895 -padlen case.
896 -nostrend
898 Don't set the END_STREAM flag, allowing to send more data on
899 this stream.
900 rxreq, rxresp
902 These are two convenience functions to receive headers and body of an
903 incoming request or response. The only difference is that rxreq can
904 only be by a server, and rxresp by a client.
905 rxhdrs
907 rxhdrs will expect one HEADER frame, then, depending on the arguments,
908 zero or more CONTINUATION frame.
909 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
911 seen.
912 -some INT
914 Retrieve INT - 1 CONTINUATION frames after the HEADER frame.
915 rxpush
917 This works like rxhdrs, expecting a PUSH frame and then zero or more
918 CONTINUATION frames.
919 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
921 seen.
922 -some INT
924 Retrieve INT - 1 CONTINUATION frames after the PUSH frame.
925 rxdata
927 Receiving data is done using the rxdata keywords and will retrieve one
928 DATA frame, if you wish to receive more, you can use these two conve‐
929 nience arguments:
930 -all keep waiting for DATA frame until one sets the END_STREAM flag
932 -some INT
934 retrieve INT DATA frames.
935 Receive a frame, any frame.
937 sendhex
939 Push bytes directly on the wire. sendhex takes exactly one argument: a
940 string describing the bytes, in hex notation, with possible whitespaces
941 between them. Here's an example:
942 sendhex "00 00 08 00 0900 8d"
944 rxgoaway
946 Receive a GOAWAY frame.
947 txgoaway
949 Possible options include:
950 -err STRING|INT
952 set the error code to explain the termination. The second argu‐
953 ment can be a integer or the string version of the error code as
954 found in rfc7540#7.
955 -laststream INT
957 the id of the "highest-numbered stream identifier for which the
958 sender of the GOAWAY frame might have taken some action on or
959 might yet take action on".
960 -debug specify the debug data, if any to append to the frame.
962 gunzip
964 Same as the gunzip command for HTTP/1.
965 rxping
967 Receive a PING frame.
968 txping
970 Send PING frame.
971 -data STRING
973 specify the payload of the frame, with STRING being an 8-char
974 string.
975 -ack set the ACK flag.
977 rxprio
979 Receive a PRIORITY frame.
980 txprio
982 Send a PRIORITY frame
983 -stream INT
985 indicate the id of the stream the sender stream depends on.
986 -ex the dependency should be made exclusive (only this streams de‐
988 pends on the parent stream).
989 -weight INT
991 an 8-bits integer is used to balance priority between streams
992 depending on the same streams.
993 rxrst
995 Receive a RST_STREAM frame.
996 txrst
998 Send a RST_STREAM frame. By default, txrst will send a 0 error code
999 (NO_ERROR).
1000 -err STRING|INT
1002 Sets the error code to be sent. The argument can be an integer
1003 or a string describing the error, such as NO_ERROR, or CANCEL
1004 (see rfc7540#11.4 for more strings).
1005 rxsettings
1007 Receive a SETTINGS frame.
1008 txsettings
1010 SETTINGS frames must be acknowledge, arguments are as follow (most of
1011 them are from rfc7540#6.5.2):
1012 -hdrtbl INT
1014 headers table size
1015 -push BOOL
1017 whether push frames are accepted or not
1018 -maxstreams INT
1020 maximum concurrent streams allowed
1021 -winsize INT
1023 sender's initial window size
1024 -framesize INT
1026 largest frame size authorized
1027 -hdrsize INT
1029 maximum size of the header list authorized
1030 -ack set the ack bit
1032 rxwinup
1034 Receive a WINDOW_UPDATE frame.
1035 txwinup
1037 Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the
1038 connection (from stream 0) or of the stream (any other stream).
1039 -size INT
1041 give INT credits to the peer.
1042 write_body STRING
1044 Same as the write_body command for HTTP/1.
1045 expect
1047 expect in stream works as it does in client or server, except that the
1048 elements compared will be different.
1049 Most of these elements will be frame specific, meaning that the last
1051 frame received on that stream must of the correct type.
1052 Here the list of keywords you can look at.
1054 syslog
1056 Define and interact with syslog instances (for use with haproxy)
1057 To define a syslog server, you'll use this syntax:
1059 syslog SNAME
1061 Arguments:
1063 SNAME Identify the syslog server with a string which must start with
1065 'S'.
1066 -level STRING
1068 Set the default syslog priority level used by any subsequent
1069 "recv" command. Any syslog dgram with a different level will be
1070 skipped by "recv" command. This default level value may be su‐
1071 perseded by "recv" command if supplied as first argument: "recv
1072 <level>".
1073 -start Start the syslog server thread in the background.
1075 -repeat
1077 Instead of processing the specification only once, do it
1079 NUMBER times.
1080 -bind Bind the syslog socket to a local address.
1082 -wait Wait for that thread to terminate.
1084 -stop Stop the syslog server thread.
1086 varnish
1088 Define and interact with varnish instances.
1089 To define a Varnish server, you'll use this syntax:
1091 varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
1093 [-errvcl STRING STRING] [-jail STRING] [-proto PROXY]
1094 The first varnish vNAME invocation will start the varnishd master
1096 process in the background, waiting for the -start switch to actually
1097 start the child.
1098 Types used in the description below:
1100 PATTERN
1102 is a 'glob' style pattern (ie: fnmatch(3)) as used in shell
1103 filename expansion.
1104 Arguments:
1106 vNAME Identify the Varnish server with a string, it must starts with
1108 'v'.
1109 -arg STRING
1111 Pass an argument to varnishd, for example "-h simple_list".
1112 -vcl STRING
1114 Specify the VCL to load on this Varnish instance. You'll proba‐
1115 bly want to use multi-lines strings for this ({...}).
1116 -vcl+backend STRING
1118 Do the exact same thing as -vcl, but adds the definition block
1119 of known backends (ie. already defined).
1120 -errvcl STRING1 STRING2
1122 Load STRING2 as VCL, expecting it to fail, and Varnish to send
1123 an error string matching STRING2
1124 -jail STRING
1126 Look at man varnishd (-j) for more information.
1127 -proto PROXY
1129 Have Varnish use the proxy protocol. Note that PROXY here is the
1130 actual string.
1131 You can decide to start the Varnish instance and/or wait for several
1133 events:
1134 varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]
1136 -start Start the child process.
1138 Once successfully started, the following macros are available
1140 for the default listen address: ${vNAME_addr}, ${vNAME_port} and
1141 ${vNAME_sock}. Additional macros are available, including the
1142 listen address name for each address vNAME listens to, like for
1143 example: ${vNAME_a0_addr}.
1144 -stop Stop the child process.
1146 -syntax
1148 Set the VCL syntax level for this command (default: 4.1)
1149 -wait Wait for that instance to terminate.
1151 -wait-running
1153 Wait for the Varnish child process to be started.
1154 -wait-stopped
1156 Wait for the Varnish child process to stop.
1157 -cleanup
1159 Once Varnish is stopped, clean everything after it. This is only
1160 used in very few tests and you should never need it.
1161 -expectexit NUMBER
1163 Expect varnishd to exit(3) with this value
1164 Once Varnish is started, you can talk to it (as you would through var‐
1166 nishadm) with these additional switches:
1167 varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
1169 [-clijson STRING]
1170 -cli STRING|-cliok STRING|-clierr STATUS STRING|-cliexpect REGEXP
1172 STRING
1173 All four of these will send STRING to the CLI, the only differ‐
1174 ence is what they expect the result to be. -cli doesn't expect
1175 anything, -cliok expects 200, -clierr expects STATUS, and -cli‐
1176 expect expects the REGEXP to match the returned response.
1177 -clijson STRING
1179 Send STRING to the CLI, expect success (CLIS_OK/200) and check
1180 that the response is parsable JSON.
1181 It is also possible to interact with its shared memory (as you would
1183 through tools like varnishstat) with additional switches:
1184 -expect !PATTERN|PATTERN OP NUMBER|PATTERN OP PATTERN
1186 Look into the VSM and make sure the first VSC counter identified
1187 by PATTERN has a correct value. OP can be ==, >, >=, <, <=. For
1188 example:
1189 varnish v1 -expect SM?.s1.g_space > 1000000
1191 varnish v1 -expect cache_hit >= cache_hit_grace
1192 In the ! form the test fails if a counter matches PATTERN.
1194 The MAIN. namespace can be omitted from PATTERN.
1196 The test takes up to 5 seconds before timing out.
1198 -vsc PATTERN
1200 Dump VSC counters matching PATTERN.
1201 -vsl_catchup
1203 Wait until the logging thread has idled to make sure that all
1204 the generated log is flushed
1205 varnishtest
1207 Alternate name for 'vtest', see above.
1208 vtest
1210 This should be the first command in your vtc as it will identify the
1211 test case with a short yet descriptive sentence. It takes exactly one
1212 argument, a string, eg:
1213 vtest "Check that vtest is actually a valid command"
1215 It will also print that string in the log.
1217
1219 This document has been written by Guillaume Quintard.
1220
1222 • varnishtest(1)
1223 • vmod_vtc(3)
1225
1227 This document is licensed under the same licence as Varnish itself. See
1228 LICENCE for details.
1229 • Copyright (c) 2006-2016 Varnish Software AS
1231 VTC(7)