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
64 another 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
147 default to the first Varnish server declared and the -vcl+backend
148 switch of the varnish command will add all the declared servers as
149 backends.
150 Be careful though, servers will by default listen to the 127.0.0.1 IP
152 and will pick a random port, and publish 3 macros: sNAME_addr,
153 sNAME_port and sNAME_sock, but only once they are started. For 'var‐
154 nish -vcl+backend' to create the vcl with the correct values, the
155 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
161 using 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,
190 either == (exact match) or ~ (regex match).
191 varnishtet will first try to resolve STRING1 and STRING2 by
193 looking if they have special meanings, in which case, the
194 resolved value is use for the test. Note that this value can be
195 a 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 loop NUMBER STRING
243 Process STRING as a specification, NUMBER times.
244 recv NUMBER
246 Read NUMBER bytes from the connection.
247 rxchunk
249 Receive an HTTP chunk.
250 rxpri (server only)
252 Receive a preface. If valid set the server to HTTP/2, abort oth‐
253 erwise.
254 rxreq (server only)
256 Receive and parse a request's headers and body.
257 rxreqbody (server only)
259 Receive a request's body.
260 rxreqhdrs (server only)
262 Receive and parse a request's headers (but not the body).
263 rxresp [-no_obj] (client only)
265 Receive and parse a response's headers and body. If -no_obj is
266 present, only get the headers.
267 rxrespbody (client only)
269 Receive (part of) a response's body.
270 -max : max length of this receive, 0 for all
272 rxresphdrs (client only)
274 Receive and parse a response's headers.
275 send STRING
277 Push STRING on the connection.
278 send_n NUMBER STRING
280 Write STRING on the socket NUMBER times.
281 send_urgent STRING
283 Send string as TCP OOB urgent data. You will never need this.
284 sendhex STRING
286 Send bytes as described by STRING. STRING should consist of hex
287 pairs possibly separated by whitespace or newlines. For example:
288 "0F EE a5 3df2".
289 settings -dectbl INT
291 Force internal HTTP/2 settings to certain values. Currently only
292 support setting the decoding table size.
293 shell Same as for the top-level shell.
295 stream HTTP/2 introduces the concept of streams, and these come with
297 their own specification, and as it's quite big, have been moved
298 to their own chapter.
299 timeout NUMBER
301 Set the TCP timeout for this entity.
302 txpri (client only)
304 Send an HTTP/2 preface ("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n") and
305 set client to HTTP/2.
306 txreq|txresp [...]
308 Send a minimal request or response, but overload it if neces‐
309 sary.
310 txreq is client-specific and txresp is server-specific.
312 The only thing different between a request and a response, apart
314 from who can send them is that the first line (request line vs
315 status line), so all the options are prety much the same.
316 -method STRING (txreq only)
318 What method to use (default: "GET").
319 -req STRING (txreq only)
321 Alias for -method.
322 -url STRING (txreq only)
324 What location to use (default "/").
325 -proto STRING
327 What protocol use in the status line. (default:
328 "HTTP/1.1").
329 -status NUMBER (txresp only)
331 What status code to return (default 200).
332 -reason STRING (txresp only)
334 What message to put in the status line (default: "OK").
335 These three switches can appear in any order but must come
337 before the following ones.
338 -nohost
340 Don't include a Host header in the request.
341 -nolen Don't include a Content-Length header.
343 -hdr STRING
345 Add STRING as a header, it must follow this format:
346 "name: value". It can be called multiple times.
347 -hdrlen STRING NUMBER
349 Add STRING as a header with NUMBER bytes of content.
350 You can then use the arguments related to the body:
352 -body STRING
354 Input STRING as body.
355 -bodyfrom FILE
357 Same as -body but content is read from FILE.
358 -bodylen NUMBER
360 Generate and input a body that is NUMBER bytes-long.
361 -gziplevel NUMBER
363 Set the gzip level (call it before any of the other gzip
364 switches).
365 -gzipresidual NUMBER
367 Add extra gzip bits. You should never need it.
368 -gzipbody STRING
370 Zip STRING and send it as body.
371 -gziplen NUMBER
373 Combine -body and -gzipbody: create a body of length NUM‐
374 BER, zip it and send as body.
375 write_body STRING
377 Write the body of a request or a response to a file. By using
378 the shell command, higher-level checks on the body can be per‐
379 formed (eg. XML, JSON, ...) provided that such checks can be
380 delegated to an external program.
381 delay
383 NOTE: This command is available everywhere commands are given.
384 Sleep for the number of seconds specified in the argument. The number
386 can include a fractional part, e.g. 1.5.
387 err_shell
389 NOTICE: err_shell is deprecated, use shell -err -expect instead.
390 This is very similar to the the shell command, except it takes a first
392 string as argument before the command:
393 err_shell "foo" "echo foo"
395 err_shell expect the shell command to fail AND stdout to match the
397 string, failing the test case otherwise.
398 feature
400 Test that the required feature(s) for a test are available, and skip
401 the test otherwise; or change the interpretation of the test, as docu‐
402 mented below. feature takes any number of arguments from this list:
403 SO_RCVTIMEO_WORKS
405 The SO_RCVTIMEO socket option is working
406 64bit The environment is 64 bits
408 dns DNS lookups are working
410 topbuild
412 The test has been started with '-i'
413 root The test has been invoked by the root user
415 user_varnish
417 The varnish user is present
418 user_vcache
420 The vcache user is present
421 group_varnish
423 The varnish group is present
424 cmd <command-line>
426 A command line that should execute with a zero exit status
427 ignore_unknown_macro
429 Do not fail the test if a string of the form ${...} is not rec‐
430 ognized as a macro.
431 persistent_storage
433 Varnish was built with the deprecated persistent storage.
434 Be careful with ignore_unknown_macro, because it may cause a test with
436 a misspelled macro to fail silently. You should only need it if you
437 must run a test with strings of the form "${...}".
438 haproxy
440 Define and interact with haproxy instances.
441 To define a haproxy server, you'll use this syntax:
443 haproxy hNAME -conf-OK CONFIG
445 haproxy hNAME -conf-BAD ERROR CONFIG
446 haproxy hNAME [-D] [-W] [-arg STRING] [-conf[+vcl] STRING]
447 The first haproxy hNAME invocation will start the haproxy master
449 process in the background, waiting for the -start switch to actually
450 start the child.
451 Arguments:
453 hNAME Identify the HAProxy server with a string, it must starts with
455 'h'.
456 -conf-OK CONFIG
458 Run haproxy in '-c' mode to check config is OK
460 stdout/stderr should contain 'Configuration file is
461 valid' The exit code should be 0.
462 -conf-BAD ERROR CONFIG
464 Run haproxy in '-c' mode to check config is BAD.
466 "ERROR" should be part of the diagnostics on std‐
467 out/stderr. The exit code should be 1.
468 -D Run HAproxy in daemon mode. If not given '-d' mode used.
470 -W Enable HAproxy in Worker mode.
472 -arg STRING
474 Pass an argument to haproxy, for example "-h simple_list".
475 -cli STRING
477 Specify the spec to be run by the command line interface (CLI).
478 -conf STRING
480 Specify the configuration to be loaded by this HAProxy instance.
481 -conf+backend STRING
483 Specify the configuration to be loaded by this HAProxy instance,
485 all server instances will be automatically appended
486 -start Start this HAProxy instance.
488 -wait Stop this HAProxy instance.
490 -expectexit NUMBER
492 Expect haproxy to exit(3) with this value
493 haproxy CLI Specification
495 expect OP STRING
496 Regex match the CLI reception buffer with STRING if OP is ~ or,
497 on the contraty, if OP is !~ check that there is no regex match.
498 send STRING
500 Push STRING on the CLI connection. STRING will be terminated by
501 an end of line character (n).
502 logexpect
504 Reads the VSL and looks for records matching a given specification. It
505 will process records trying to match the first pattern, and when done,
506 will continue processing, trying to match the following pattern. If a
507 pattern isn't matched, the test will fail.
508 logexpect threads are declared this way:
510 logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
512 [vsl arguments] {
513 expect <skip> <vxid> <tag> <regex>
514 expect <skip> <vxid> <tag> <regex>
515 ...
516 } [-start|-wait]
517 And once declared, you can start them, or wait on them:
519 logexpect lNAME <-start|-wait>
521 With:
523 lNAME Name the logexpect thread, it must start with 'l'.
525 -v id Specify the varnish instance to use (most of the time, id=v1).
527 -g <session|request|vxid|raw
529 Decide how records are grouped, see -g in man varnishlog for
530 more information.
531 -d <0|1>
533 Start processing log records at the head of the log instead of
534 the tail.
535 -q query
537 Filter records using a query expression, see man vsl-query for
538 more information.
539 -m Also emit log records for misses (only for debugging)
541 -start Start the logexpect thread in the background.
543 -wait Wait for the logexpect thread to finish
545 VSL arguments (similar to the varnishlog options):
547 -b|-c Process only backend/client records.
549 -C Use caseless regex
551 -i <taglist>
553 Include tags
554 -I <[taglist:]regex>
556 Include by regex
557 -T <seconds>
559 Transaction end timeout
560 And the arguments of the specifications lines are:
562 skip: [uint|*]
564 Max number of record to skip
565 vxid: [uint|*|=]
567 vxid to match
568 tag: [tagname|*|=]
570 Tag to match against
571 regex: regular expression to match against (optional)
573 For skip, vxid and tag, '*' matches anything, '=' expects the value of
575 the previous matched record.
576 process
578 Run a process with stdin+stdout on a pseudo-terminal and stderr on a
579 pipe.
580 Output from the pseudo-terminal is copied verbatim to ${pNAME_out}, and
582 the -log/-dump/-hexdump flags will also put it in the vtc-log.
583 The pseudo-terminal is not in ECHO mode, but if the programs run set it
585 to ECHO mode ("stty sane") any input sent to the process will also
586 appear in this stream because of the ECHO.
587 Output from the stderr-pipe is copied verbatim to ${pNAME_err}, and is
589 always included in the vtc_log.
590 process pNAME SPEC [-log] [-dump] [-hexdump] [-expect-exit N]
592 [-start] [-run] [-write STRING] [-writeln STRING] [-kill
593 STRING] [-stop] [-wait] [-close]
594 pNAME Name of the process. It must start with 'p'.
596 SPEC The command(s) to run in this process.
598 -hexdump
600 Log output with vtc_hexdump(). Must be before -start/-run.
601 -dump Log output with vtc_dump(). Must be before -start/-run.
603 -log Log output with VLU/vtc_log(). Must be before -start/-run.
605 -start Start the process.
607 -expect-exit N
609 Expect exit status N
610 -wait Wait for the process to finish.
612 -run Shorthand for -start -wait.
614 In most cases, if you just want to start a process and wait for
616 it to finish, you can use the shell command instead. The fol‐
617 lowing commands are equivalent:
618 shell "do --something"
620 process p1 "do --something" -run
622 However, you may use the the process variant to conveniently
624 collect the standard input and output without dealing with shell
625 redirections yourself. The shell command can also expect an
626 expression from either output, consider using it if you only
627 need to match one.
628 -kill STRING
630 Send a signal to the process. The argument can be either the
631 string "TERM", "INT", or "KILL" for SIGTERM, SIGINT or SIGKILL
632 signals, respectively, or a hyphen (-) followed by the signal
633 number.
634 If you need to use other signal names, you can use the kill(1)
636 command directly:
637 shell "kill -USR1 ${pNAME_pid}"
639 Note that SIGHUP usage is discouraged in test cases.
641 -stop Shorthand for -kill TERM.
643 -write STRING
645 Write a string to the process' stdin.
646 -writeln STRING
648 Same as -write followed by a newline (\n).
649 -writehex HEXSTRING
651 Same as -write but interpreted as hexadecimal bytes.
652 -need-bytes [+]NUMBER
654 Wait until at least NUMBER bytes have been received in total.
655 If '+' is prefixed, NUMBER new bytes must be received.
656 -expect-text LIN COL PAT
658 Wait for PAT to appear at LIN,COL on the virtual screen. Lines
659 and columns are numbered 1...N LIN==0 means "on any line" COL==0
660 means "anywhere on the line"
661 -close Alias for "-kill HUP"
663 -screen_dump
665 Dump the virtual screen into vtc_log
666 setenv
668 Set or change an environment variable:
669 setenv FOO "bar baz"
671 The above will set the environment variable $FOO to the value provided.
673 There is also an -ifunset argument which will only set the value if the
674 the environment variable does not already exist:
675 setenv -ifunset FOO quux
677 shell
679 NOTE: This command is available everywhere commands are given.
680 Pass the string given as argument to a shell. If you have multiple com‐
682 mands to run, you can use curly brackets to describe a multi-lines
683 script, eg:
684 shell {
686 echo begin
687 cat /etc/fstab
688 echo end
689 }
690 By default a zero exit code is expected, otherwise the vtc will fail.
692 Notice that the commandstring is prefixed with "exec 2>&1;" to combine
694 stderr and stdout back to the test process.
695 Optional arguments:
697 -err Expect non-zero exit code.
699 -exit N
701 Expect exit code N instead of zero.
702 -expect STRING
704 Expect string to be found in stdout+err.
705 -match REGEXP
707 Expect regexp to match the stdout+err output.
708 stream
710 (note: this section is at the top-level for easier navigation, but it's
711 part of the client/server specification)
712 Streams map roughly to a request in HTTP/2, a request is sent on stream
714 N, the response too, then the stream is discarded. The main exception
715 is the first stream, 0, that serves as coordinator.
716 Stream syntax follow the client/server one:
718 stream ID [SPEC] [ACTION]
720 ID is the HTTP/2 stream number, while SPEC describes what will be done
722 in that stream.
723 Note that, when parsing a stream action, if the entity isn't operating
725 in HTTP/2 mode, these spec is ran before:
726 txpri/rxpri # client/server
728 stream 0 {
729 txsettings
730 rxsettings
731 txsettings -ack
732 rxsettings
733 expect settings.ack == true
734 } -run
735 And HTTP/2 mode is then activated before parsing the specification.
737 Actions
739 -start Run the specification in a thread, giving back control immedi‐
740 ately.
741 -wait Wait for the started thread to finish running the spec.
743 -run equivalent to calling -start then -wait.
745 Specification
747 The specification of a stream follows the exact same rules as one for a
748 client or a server.
749 txreq, txresp, txcont, txpush
751 These four commands are about sending headers. txreq and txresp will
752 send HEADER frames; txcont will send CONTINUATION frames; txpush PUSH
753 frames. The only difference between txreq and txresp are the default
754 headers set by each of them.
755 -noadd Do not add default headers. Useful to avoid duplicates when
757 sending default headers using -hdr, -idxHdr and -litIdxHdr.
758 -status INT (txresp)
760 Set the :status pseudo-header.
761 -url STRING (txreq, txpush)
763 Set the :path pseudo-header.
764 -method STRING (txreq, txpush)
766 Set the :method pseudo-header.
767 -req STRING (txreq, txpush)
769 Alias for -method.
770 -scheme STRING (txreq, txpush)
772 Set the :scheme pseudo-header.
773 -hdr STRING1 STRING2
775 Insert a header, STRING1 being the name, and STRING2 the value.
776 -idxHdr INT
778 Insert an indexed header, using INT as index.
779 -litIdxHdr inc|not|never INT huf|plain STRING
781 Insert an literal, indexed header. The first argument specify if
782 the header should be added to the table, shouldn't, or mustn't
783 be compressed if/when retransmitted.
784 INT is the idex of the header name to use.
786 The third argument informs about the Huffman encoding: yes (huf)
788 or no (plain).
789 The last term is the literal value of the header.
791 -litHdr inc|not|never huf|plain STRING1 huf|plain STRING2
793 Insert a literal header, with the same first argument as
794 -litIdxHdr.
795 The second and third terms tell what the name of the header is
797 and if it should be Huffman-encoded, while the last two do the
798 same regarding the value.
799 -body STRING (txreq, txresp)
801 Specify a body, effectively putting STRING into a DATA frame
802 after the HEADER frame is sent.
803 -bodyfrom FILE (txreq, txresp)
805 Same as -body but content is read from FILE.
806 -bodylen INT (txreq, txresp)
808 Do the same thing as -body but generate an string of INT length
809 for you.
810 -gzipbody STRING (txreq, txresp)
812 Gzip STRING and send it as body.
813 -gziplen NUMBER (txreq, txresp)
815 Combine -body and -gzipbody: create a body of length NUMBER,
816 gzip it and send as body.
817 -nostrend (txreq, txresp)
819 Don't set the END_STREAM flag automatically, making the peer
820 expect a body after the headers.
821 -nohdrend
823 Don't set the END_HEADERS flag automatically, making the peer
824 expect more HEADER frames.
825 -dep INT (txreq, txresp)
827 Tell the peer that this content depends on the stream with the
828 INT id.
829 -ex (txreq, txresp)
831 Make the dependency exclusive (-dep is still needed).
832 -weight (txreq, txresp)
834 Set the weight for the dependency.
835 -promised INT (txpush)
837 The id of the promised stream.
838 -pad STRING / -padlen INT (txreq, txresp, txpush)
840 Add string as padding to the frame, either the one you provided
841 with -pad, or one that is generated for you, of length INT is
842 -padlen case.
843 txdata
845 By default, data frames are empty. The receiving end will know the
846 whole body has been delivered thanks to the END_STREAM flag set in the
847 last DATA frame, and txdata automatically set it.
848 -data STRING
850 Data to be embedded into the frame.
851 -datalen INT
853 Generate and INT-bytes long string to be sent in the frame.
854 -pad STRING / -padlen INT
856 Add string as padding to the frame, either the one you provided
857 with -pad, or one that is generated for you, of length INT is
858 -padlen case.
859 -nostrend
861 Don't set the END_STREAM flag, allowing to send more data on
862 this stream.
863 rxreq, rxresp
865 These are two convenience functions to receive headers and body of an
866 incoming request or response. The only difference is that rxreq can
867 only be by a server, and rxresp by a client.
868 rxhdrs
870 rxhdrs will expect one HEADER frame, then, depending on the arguments,
871 zero or more CONTINUATION frame.
872 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
874 seen.
875 -some INT
877 Retrieve INT - 1 CONTINUATION frames after the HEADER frame.
878 rxpush
880 This works like rxhdrs, expecting a PUSH frame and then zero or more
881 CONTINUATION frames.
882 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
884 seen.
885 -some INT
887 Retrieve INT - 1 CONTINUATION frames after the PUSH frame.
888 rxdata
890 Receiving data is done using the rxdata keywords and will retrieve one
891 DATA frame, if you wish to receive more, you can use these two conve‐
892 nience arguments:
893 -all keep waiting for DATA frame until one sets the END_STREAM flag
895 -some INT
897 retrieve INT DATA frames.
898 Receive a frame, any frame.
900 sendhex
902 Push bytes directly on the wire. sendhex takes exactly one argument: a
903 string describing the bytes, in hex notation, with possible whitespaces
904 between them. Here's an example:
905 sendhex "00 00 08 00 0900 8d"
907 rxgoaway
909 Receive a GOAWAY frame.
910 txgoaway
912 Possible options include:
913 -err STRING|INT
915 set the error code to explain the termination. The second argu‐
916 ment can be a integer or the string version of the error code as
917 found in rfc7540#7.
918 -laststream INT
920 the id of the "highest-numbered stream identifier for which the
921 sender of the GOAWAY frame might have taken some action on or
922 might yet take action on".
923 -debug specify the debug data, if any to append to the frame.
925 gunzip
927 Same as the gunzip command for HTTP/1.
928 rxping
930 Receive a PING frame.
931 txping
933 Send PING frame.
934 -data STRING
936 specify the payload of the frame, with STRING being an 8-char
937 string.
938 -ack set the ACK flag.
940 rxprio
942 Receive a PRIORITY frame.
943 txprio
945 Send a PRIORITY frame
946 -stream INT
948 indicate the id of the stream the sender stream depends on.
949 -ex the dependency should be made exclusive (only this streams
951 depends on the parent stream).
952 -weight INT
954 an 8-bits integer is used to balance priority between streams
955 depending on the same streams.
956 rxrst
958 Receive a RST_STREAM frame.
959 txrst
961 Send a RST_STREAM frame. By default, txrst will send a 0 error code
962 (NO_ERROR).
963 -err STRING|INT
965 Sets the error code to be sent. The argument can be an integer
966 or a string describing the error, such as NO_ERROR, or CANCEL
967 (see rfc7540#11.4 for more strings).
968 rxsettings
970 Receive a SETTINGS frame.
971 txsettings
973 SETTINGS frames must be acknowledge, arguments are as follow (most of
974 them are from rfc7540#6.5.2):
975 -hdrtbl INT
977 headers table size
978 -push BOOL
980 whether push frames are accepted or not
981 -maxstreams INT
983 maximum concurrent streams allowed
984 -winsize INT
986 sender's initial window size
987 -framesize INT
989 largest frame size authorized
990 -hdrsize INT
992 maximum size of the header list authorized
993 -ack set the ack bit
995 rxwinup
997 Receive a WINDOW_UPDATE frame.
998 txwinup
1000 Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the
1001 connection (from stream 0) or of the stream (any other stream).
1002 -size INT
1004 give INT credits to the peer.
1005 write_body STRING
1007 Same as the write_body command for HTTP/1.
1008 expect
1010 expect in stream works as it does in client or server, except that the
1011 elements compared will be different.
1012 Most of these elements will be frame specific, meaning that the last
1014 frame received on that stream must of the correct type.
1015 Here the list of keywords you can look at.
1017 syslog
1019 Define and interact with syslog instances (for use with haproxy)
1020 To define a syslog server, you'll use this syntax:
1022 syslog SNAME
1024 Arguments:
1026 SNAME Identify the syslog server with a string which must start with
1028 'S'.
1029 -level STRING
1031 Set the default syslog priority level used by any subsequent
1032 "recv" command. Any syslog dgram with a different level will be
1033 skipped by "recv" command. This default level value may be
1034 superseded by "recv" command if supplied as first argument:
1035 "recv <level>".
1036 -start Start the syslog server thread in the background.
1038 -repeat
1040 Instead of processing the specification only once, do it
1042 NUMBER times.
1043 -bind Bind the syslog socket to a local address.
1045 -wait Wait for that thread to terminate.
1047 -stop Stop the syslog server thread.
1049 varnish
1051 Define and interact with varnish instances.
1052 To define a Varnish server, you'll use this syntax:
1054 varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
1056 [-errvcl STRING STRING] [-jail STRING] [-proto PROXY]
1057 The first varnish vNAME invocation will start the varnishd master
1059 process in the background, waiting for the -start switch to actually
1060 start the child.
1061 Types used in the description below:
1063 PATTERN
1065 is a 'glob' style pattern (ie: fnmatch(3)) as used in shell
1066 filename expansion.
1067 Arguments:
1069 vNAME Identify the Varnish server with a string, it must starts with
1071 'v'.
1072 -arg STRING
1074 Pass an argument to varnishd, for example "-h simple_list".
1075 -vcl STRING
1077 Specify the VCL to load on this Varnish instance. You'll proba‐
1078 bly want to use multi-lines strings for this ({...}).
1079 -vcl+backend STRING
1081 Do the exact same thing as -vcl, but adds the definition block
1082 of known backends (ie. already defined).
1083 -errvcl STRING1 STRING2
1085 Load STRING2 as VCL, expecting it to fail, and Varnish to send
1086 an error string matching STRING2
1087 -jail STRING
1089 Look at man varnishd (-j) for more information.
1090 -proto PROXY
1092 Have Varnish use the proxy protocol. Note that PROXY here is the
1093 actual string.
1094 You can decide to start the Varnish instance and/or wait for several
1096 events:
1097 varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]
1099 -start Start the child process.
1101 -stop Stop the child process.
1103 -syntax
1105 Set the VCL syntax level for this command (default: 4.1)
1106 -wait Wait for that instance to terminate.
1108 -wait-running
1110 Wait for the Varnish child process to be started.
1111 -wait-stopped
1113 Wait for the Varnish child process to stop.
1114 -cleanup
1116 Once Varnish is stopped, clean everything after it. This is only
1117 used in very few tests and you should never need it.
1118 Once Varnish is started, you can talk to it (as you would through var‐
1120 nishadm) with these additional switches:
1121 varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
1123 [-clijson STRING] [-expect STRING OP NUMBER]
1124 -cli STRING|-cliok STRING|-clierr STATUS STRING|-cliexpect REGEXP
1126 STRING
1127 All four of these will send STRING to the CLI, the only differ‐
1128 ence is what they expect the result to be. -cli doesn't expect
1129 anything, -cliok expects 200, -clierr expects STATUS, and -cli‐
1130 expect expects the REGEXP to match the returned response.
1131 -clijson STRING
1133 Send STRING to the CLI, expect success (CLIS_OK/200) and check
1134 that the response is parsable JSON.
1135 -expect PATTERN OP NUMBER
1137 Look into the VSM and make sure the first VSC counter identified
1138 by PATTERN has a correct value. OP can be ==, >, >=, <, <=. For
1139 example:
1140 varnish v1 -expect SM?.s1.g_space > 1000000
1142 -expectexit NUMBER
1144 Expect varnishd to exit(3) with this value
1145 -vsc PATTERN
1147 Dump VSC counters matching PATTERN.
1148 -vsl_catchup
1150 Wait until the logging thread has idled to make sure that all
1151 the generated log is flushed
1152 varnishtest
1154 Alternate name for 'vtest', see above.
1155 vtest
1157 This should be the first command in your vtc as it will identify the
1158 test case with a short yet descriptive sentence. It takes exactly one
1159 argument, a string, eg:
1160 vtest "Check that vtest is actually a valid command"
1162 It will also print that string in the log.
1164
1166 This document has been written by Guillaume Quintard.
1167
1169 · varnishtest(1)
1170 · vmod_vtc(3)
1172
1174 This document is licensed under the same licence as Varnish itself. See
1175 LICENCE for details.
1176 · Copyright (c) 2006-2016 Varnish Software AS
1178 VTC(7)