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 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 be‐
337 fore 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 Gzip STRING and send it as body.
371 -gziplen NUMBER
373 Combine -bodylen and -gzipbody: generate a string of
374 length NUMBER, gzip 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 -S Enable HAproxy Master CLI in Worker mode
474 -arg STRING
476 Pass an argument to haproxy, for example "-h simple_list".
477 -cli STRING
479 Specify the spec to be run by the command line interface (CLI).
480 -mcli STRING
482 Specify the spec to be run by the command line interface (CLI)
483 of the Master process.
484 -conf STRING
486 Specify the configuration to be loaded by this HAProxy instance.
487 -conf+backend STRING
489 Specify the configuration to be loaded by this HAProxy instance,
491 all server instances will be automatically appended
492 -start Start this HAProxy instance.
494 -wait Stop this HAProxy instance.
496 -expectexit NUMBER
498 Expect haproxy to exit(3) with this value
499 haproxy CLI Specification
501 expect OP STRING
502 Regex match the CLI reception buffer with STRING if OP is ~ or,
503 on the contraty, if OP is !~ check that there is no regex match.
504 send STRING
506 Push STRING on the CLI connection. STRING will be terminated by
507 an end of line character (n).
508 logexpect
510 Reads the VSL and looks for records matching a given specification. It
511 will process records trying to match the first pattern, and when done,
512 will continue processing, trying to match the following pattern. If a
513 pattern isn't matched, the test will fail.
514 logexpect threads are declared this way:
516 logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
518 [vsl arguments] {
519 expect <skip> <vxid> <tag> <regex>
520 expect <skip> <vxid> <tag> <regex>
521 ...
522 } [-start|-wait]
523 And once declared, you can start them, or wait on them:
525 logexpect lNAME <-start|-wait>
527 With:
529 lNAME Name the logexpect thread, it must start with 'l'.
531 -v id Specify the varnish instance to use (most of the time, id=v1).
533 -g <session|request|vxid|raw
535 Decide how records are grouped, see -g in man varnishlog for
536 more information.
537 -d <0|1>
539 Start processing log records at the head of the log instead of
540 the tail.
541 -q query
543 Filter records using a query expression, see man vsl-query for
544 more information. Multiple -q options are not supported.
545 -m Also emit log records for misses (only for debugging)
547 -start Start the logexpect thread in the background.
549 -wait Wait for the logexpect thread to finish
551 VSL arguments (similar to the varnishlog options):
553 -C Use caseless regex
555 -i <taglist>
557 Include tags
558 -I <[taglist:]regex>
560 Include by regex
561 -T <seconds>
563 Transaction end timeout
564 And the arguments of the specifications lines are:
566 skip: [uint|*]
568 Max number of record to skip
569 vxid: [uint|*|=]
571 vxid to match
572 tag: [tagname|*|=]
574 Tag to match against
575 regex: regular expression to match against (optional)
577 For skip, vxid and tag, '*' matches anything, '=' expects the value of
579 the previous matched record.
580 process
582 Run a process with stdin+stdout on a pseudo-terminal and stderr on a
583 pipe.
584 Output from the pseudo-terminal is copied verbatim to ${pNAME_out}, and
586 the -log/-dump/-hexdump flags will also put it in the vtc-log.
587 The pseudo-terminal is not in ECHO mode, but if the programs run set it
589 to ECHO mode ("stty sane") any input sent to the process will also ap‐
590 pear in this stream because of the ECHO.
591 Output from the stderr-pipe is copied verbatim to ${pNAME_err}, and is
593 always included in the vtc_log.
594 process pNAME SPEC [-log] [-dump] [-hexdump] [-expect-exit N]
596 [-start] [-run] [-write STRING] [-writeln STRING] [-kill
597 STRING] [-stop] [-wait] [-close]
598 pNAME Name of the process. It must start with 'p'.
600 SPEC The command(s) to run in this process.
602 -hexdump
604 Log output with vtc_hexdump(). Must be before -start/-run.
605 -dump Log output with vtc_dump(). Must be before -start/-run.
607 -log Log output with VLU/vtc_log(). Must be before -start/-run.
609 -start Start the process.
611 -expect-exit N
613 Expect exit status N
614 -wait Wait for the process to finish.
616 -run Shorthand for -start -wait.
618 In most cases, if you just want to start a process and wait for
620 it to finish, you can use the shell command instead. The fol‐
621 lowing commands are equivalent:
622 shell "do --something"
624 process p1 "do --something" -run
626 However, you may use the the process variant to conveniently
628 collect the standard input and output without dealing with shell
629 redirections yourself. The shell command can also expect an ex‐
630 pression from either output, consider using it if you only need
631 to match one.
632 -kill STRING
634 Send a signal to the process. The argument can be either the
635 string "TERM", "INT", or "KILL" for SIGTERM, SIGINT or SIGKILL
636 signals, respectively, or a hyphen (-) followed by the signal
637 number.
638 If you need to use other signal names, you can use the kill(1)
640 command directly:
641 shell "kill -USR1 ${pNAME_pid}"
643 Note that SIGHUP usage is discouraged in test cases.
645 -stop Shorthand for -kill TERM.
647 -write STRING
649 Write a string to the process' stdin.
650 -writeln STRING
652 Same as -write followed by a newline (\n).
653 -writehex HEXSTRING
655 Same as -write but interpreted as hexadecimal bytes.
656 -need-bytes [+]NUMBER
658 Wait until at least NUMBER bytes have been received in total.
659 If '+' is prefixed, NUMBER new bytes must be received.
660 -expect-text LIN COL PAT
662 Wait for PAT to appear at LIN,COL on the virtual screen. Lines
663 and columns are numbered 1...N LIN==0 means "on any line" COL==0
664 means "anywhere on the line"
665 -close Alias for "-kill HUP"
667 -screen_dump
669 Dump the virtual screen into vtc_log
670 setenv
672 Set or change an environment variable:
673 setenv FOO "bar baz"
675 The above will set the environment variable $FOO to the value provided.
677 There is also an -ifunset argument which will only set the value if the
678 the environment variable does not already exist:
679 setenv -ifunset FOO quux
681 shell
683 NOTE: This command is available everywhere commands are given.
684 Pass the string given as argument to a shell. If you have multiple com‐
686 mands to run, you can use curly brackets to describe a multi-lines
687 script, eg:
688 shell {
690 echo begin
691 cat /etc/fstab
692 echo end
693 }
694 By default a zero exit code is expected, otherwise the vtc will fail.
696 Notice that the commandstring is prefixed with "exec 2>&1;" to combine
698 stderr and stdout back to the test process.
699 Optional arguments:
701 -err Expect non-zero exit code.
703 -exit N
705 Expect exit code N instead of zero.
706 -expect STRING
708 Expect string to be found in stdout+err.
709 -match REGEXP
711 Expect regexp to match the stdout+err output.
712 stream
714 (note: this section is at the top-level for easier navigation, but it's
715 part of the client/server specification)
716 Streams map roughly to a request in HTTP/2, a request is sent on stream
718 N, the response too, then the stream is discarded. The main exception
719 is the first stream, 0, that serves as coordinator.
720 Stream syntax follow the client/server one:
722 stream ID [SPEC] [ACTION]
724 ID is the HTTP/2 stream number, while SPEC describes what will be done
726 in that stream.
727 Note that, when parsing a stream action, if the entity isn't operating
729 in HTTP/2 mode, these spec is ran before:
730 txpri/rxpri # client/server
732 stream 0 {
733 txsettings
734 rxsettings
735 txsettings -ack
736 rxsettings
737 expect settings.ack == true
738 } -run
739 And HTTP/2 mode is then activated before parsing the specification.
741 Actions
743 -start Run the specification in a thread, giving back control immedi‐
744 ately.
745 -wait Wait for the started thread to finish running the spec.
747 -run equivalent to calling -start then -wait.
749 Specification
751 The specification of a stream follows the exact same rules as one for a
752 client or a server.
753 txreq, txresp, txcont, txpush
755 These four commands are about sending headers. txreq and txresp will
756 send HEADER frames; txcont will send CONTINUATION frames; txpush PUSH
757 frames. The only difference between txreq and txresp are the default
758 headers set by each of them.
759 -noadd Do not add default headers. Useful to avoid duplicates when
761 sending default headers using -hdr, -idxHdr and -litIdxHdr.
762 -status INT (txresp)
764 Set the :status pseudo-header.
765 -url STRING (txreq, txpush)
767 Set the :path pseudo-header.
768 -method STRING (txreq, txpush)
770 Set the :method pseudo-header.
771 -req STRING (txreq, txpush)
773 Alias for -method.
774 -scheme STRING (txreq, txpush)
776 Set the :scheme pseudo-header.
777 -hdr STRING1 STRING2
779 Insert a header, STRING1 being the name, and STRING2 the value.
780 -idxHdr INT
782 Insert an indexed header, using INT as index.
783 -litIdxHdr inc|not|never INT huf|plain STRING
785 Insert an literal, indexed header. The first argument specify if
786 the header should be added to the table, shouldn't, or mustn't
787 be compressed if/when retransmitted.
788 INT is the idex of the header name to use.
790 The third argument informs about the Huffman encoding: yes (huf)
792 or no (plain).
793 The last term is the literal value of the header.
795 -litHdr inc|not|never huf|plain STRING1 huf|plain STRING2
797 Insert a literal header, with the same first argument as
798 -litIdxHdr.
799 The second and third terms tell what the name of the header is
801 and if it should be Huffman-encoded, while the last two do the
802 same regarding the value.
803 -body STRING (txreq, txresp)
805 Specify a body, effectively putting STRING into a DATA frame af‐
806 ter the HEADER frame is sent.
807 -bodyfrom FILE (txreq, txresp)
809 Same as -body but content is read from FILE.
810 -bodylen INT (txreq, txresp)
812 Do the same thing as -body but generate a string of INT length
813 for you.
814 -gzipbody STRING (txreq, txresp)
816 Gzip STRING and send it as body.
817 -gziplen NUMBER (txreq, txresp)
819 Combine -bodylen and -gzipbody: generate a string of length NUM‐
820 BER, gzip it and send as body.
821 -nostrend (txreq, txresp)
823 Don't set the END_STREAM flag automatically, making the peer ex‐
824 pect a body after the headers.
825 -nohdrend
827 Don't set the END_HEADERS flag automatically, making the peer
828 expect more HEADER frames.
829 -dep INT (txreq, txresp)
831 Tell the peer that this content depends on the stream with the
832 INT id.
833 -ex (txreq, txresp)
835 Make the dependency exclusive (-dep is still needed).
836 -weight (txreq, txresp)
838 Set the weight for the dependency.
839 -promised INT (txpush)
841 The id of the promised stream.
842 -pad STRING / -padlen INT (txreq, txresp, txpush)
844 Add string as padding to the frame, either the one you provided
845 with -pad, or one that is generated for you, of length INT is
846 -padlen case.
847 txdata
849 By default, data frames are empty. The receiving end will know the
850 whole body has been delivered thanks to the END_STREAM flag set in the
851 last DATA frame, and txdata automatically set it.
852 -data STRING
854 Data to be embedded into the frame.
855 -datalen INT
857 Generate and INT-bytes long string to be sent in the frame.
858 -pad STRING / -padlen INT
860 Add string as padding to the frame, either the one you provided
861 with -pad, or one that is generated for you, of length INT is
862 -padlen case.
863 -nostrend
865 Don't set the END_STREAM flag, allowing to send more data on
866 this stream.
867 rxreq, rxresp
869 These are two convenience functions to receive headers and body of an
870 incoming request or response. The only difference is that rxreq can
871 only be by a server, and rxresp by a client.
872 rxhdrs
874 rxhdrs will expect one HEADER frame, then, depending on the arguments,
875 zero or more CONTINUATION frame.
876 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
878 seen.
879 -some INT
881 Retrieve INT - 1 CONTINUATION frames after the HEADER frame.
882 rxpush
884 This works like rxhdrs, expecting a PUSH frame and then zero or more
885 CONTINUATION frames.
886 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
888 seen.
889 -some INT
891 Retrieve INT - 1 CONTINUATION frames after the PUSH frame.
892 rxdata
894 Receiving data is done using the rxdata keywords and will retrieve one
895 DATA frame, if you wish to receive more, you can use these two conve‐
896 nience arguments:
897 -all keep waiting for DATA frame until one sets the END_STREAM flag
899 -some INT
901 retrieve INT DATA frames.
902 Receive a frame, any frame.
904 sendhex
906 Push bytes directly on the wire. sendhex takes exactly one argument: a
907 string describing the bytes, in hex notation, with possible whitespaces
908 between them. Here's an example:
909 sendhex "00 00 08 00 0900 8d"
911 rxgoaway
913 Receive a GOAWAY frame.
914 txgoaway
916 Possible options include:
917 -err STRING|INT
919 set the error code to explain the termination. The second argu‐
920 ment can be a integer or the string version of the error code as
921 found in rfc7540#7.
922 -laststream INT
924 the id of the "highest-numbered stream identifier for which the
925 sender of the GOAWAY frame might have taken some action on or
926 might yet take action on".
927 -debug specify the debug data, if any to append to the frame.
929 gunzip
931 Same as the gunzip command for HTTP/1.
932 rxping
934 Receive a PING frame.
935 txping
937 Send PING frame.
938 -data STRING
940 specify the payload of the frame, with STRING being an 8-char
941 string.
942 -ack set the ACK flag.
944 rxprio
946 Receive a PRIORITY frame.
947 txprio
949 Send a PRIORITY frame
950 -stream INT
952 indicate the id of the stream the sender stream depends on.
953 -ex the dependency should be made exclusive (only this streams de‐
955 pends on the parent stream).
956 -weight INT
958 an 8-bits integer is used to balance priority between streams
959 depending on the same streams.
960 rxrst
962 Receive a RST_STREAM frame.
963 txrst
965 Send a RST_STREAM frame. By default, txrst will send a 0 error code
966 (NO_ERROR).
967 -err STRING|INT
969 Sets the error code to be sent. The argument can be an integer
970 or a string describing the error, such as NO_ERROR, or CANCEL
971 (see rfc7540#11.4 for more strings).
972 rxsettings
974 Receive a SETTINGS frame.
975 txsettings
977 SETTINGS frames must be acknowledge, arguments are as follow (most of
978 them are from rfc7540#6.5.2):
979 -hdrtbl INT
981 headers table size
982 -push BOOL
984 whether push frames are accepted or not
985 -maxstreams INT
987 maximum concurrent streams allowed
988 -winsize INT
990 sender's initial window size
991 -framesize INT
993 largest frame size authorized
994 -hdrsize INT
996 maximum size of the header list authorized
997 -ack set the ack bit
999 rxwinup
1001 Receive a WINDOW_UPDATE frame.
1002 txwinup
1004 Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the
1005 connection (from stream 0) or of the stream (any other stream).
1006 -size INT
1008 give INT credits to the peer.
1009 write_body STRING
1011 Same as the write_body command for HTTP/1.
1012 expect
1014 expect in stream works as it does in client or server, except that the
1015 elements compared will be different.
1016 Most of these elements will be frame specific, meaning that the last
1018 frame received on that stream must of the correct type.
1019 Here the list of keywords you can look at.
1021 syslog
1023 Define and interact with syslog instances (for use with haproxy)
1024 To define a syslog server, you'll use this syntax:
1026 syslog SNAME
1028 Arguments:
1030 SNAME Identify the syslog server with a string which must start with
1032 'S'.
1033 -level STRING
1035 Set the default syslog priority level used by any subsequent
1036 "recv" command. Any syslog dgram with a different level will be
1037 skipped by "recv" command. This default level value may be su‐
1038 perseded by "recv" command if supplied as first argument: "recv
1039 <level>".
1040 -start Start the syslog server thread in the background.
1042 -repeat
1044 Instead of processing the specification only once, do it
1046 NUMBER times.
1047 -bind Bind the syslog socket to a local address.
1049 -wait Wait for that thread to terminate.
1051 -stop Stop the syslog server thread.
1053 varnish
1055 Define and interact with varnish instances.
1056 To define a Varnish server, you'll use this syntax:
1058 varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
1060 [-errvcl STRING STRING] [-jail STRING] [-proto PROXY]
1061 The first varnish vNAME invocation will start the varnishd master
1063 process in the background, waiting for the -start switch to actually
1064 start the child.
1065 Types used in the description below:
1067 PATTERN
1069 is a 'glob' style pattern (ie: fnmatch(3)) as used in shell
1070 filename expansion.
1071 Arguments:
1073 vNAME Identify the Varnish server with a string, it must starts with
1075 'v'.
1076 -arg STRING
1078 Pass an argument to varnishd, for example "-h simple_list".
1079 -vcl STRING
1081 Specify the VCL to load on this Varnish instance. You'll proba‐
1082 bly want to use multi-lines strings for this ({...}).
1083 -vcl+backend STRING
1085 Do the exact same thing as -vcl, but adds the definition block
1086 of known backends (ie. already defined).
1087 -errvcl STRING1 STRING2
1089 Load STRING2 as VCL, expecting it to fail, and Varnish to send
1090 an error string matching STRING2
1091 -jail STRING
1093 Look at man varnishd (-j) for more information.
1094 -proto PROXY
1096 Have Varnish use the proxy protocol. Note that PROXY here is the
1097 actual string.
1098 You can decide to start the Varnish instance and/or wait for several
1100 events:
1101 varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]
1103 -start Start the child process.
1105 -stop Stop the child process.
1107 -syntax
1109 Set the VCL syntax level for this command (default: 4.1)
1110 -wait Wait for that instance to terminate.
1112 -wait-running
1114 Wait for the Varnish child process to be started.
1115 -wait-stopped
1117 Wait for the Varnish child process to stop.
1118 -cleanup
1120 Once Varnish is stopped, clean everything after it. This is only
1121 used in very few tests and you should never need it.
1122 Once Varnish is started, you can talk to it (as you would through var‐
1124 nishadm) with these additional switches:
1125 varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
1127 [-clijson STRING] [-expect STRING OP NUMBER]
1128 -cli STRING|-cliok STRING|-clierr STATUS STRING|-cliexpect REGEXP
1130 STRING
1131 All four of these will send STRING to the CLI, the only differ‐
1132 ence is what they expect the result to be. -cli doesn't expect
1133 anything, -cliok expects 200, -clierr expects STATUS, and -cli‐
1134 expect expects the REGEXP to match the returned response.
1135 -clijson STRING
1137 Send STRING to the CLI, expect success (CLIS_OK/200) and check
1138 that the response is parsable JSON.
1139 -expect PATTERN OP NUMBER
1141 Look into the VSM and make sure the first VSC counter identified
1142 by PATTERN has a correct value. OP can be ==, >, >=, <, <=. For
1143 example:
1144 varnish v1 -expect SM?.s1.g_space > 1000000
1146 -expectexit NUMBER
1148 Expect varnishd to exit(3) with this value
1149 -vsc PATTERN
1151 Dump VSC counters matching PATTERN.
1152 -vsl_catchup
1154 Wait until the logging thread has idled to make sure that all
1155 the generated log is flushed
1156 varnishtest
1158 Alternate name for 'vtest', see above.
1159 vtest
1161 This should be the first command in your vtc as it will identify the
1162 test case with a short yet descriptive sentence. It takes exactly one
1163 argument, a string, eg:
1164 vtest "Check that vtest is actually a valid command"
1166 It will also print that string in the log.
1168
1170 This document has been written by Guillaume Quintard.
1171
1173 • varnishtest(1)
1174 • vmod_vtc(3)
1176
1178 This document is licensed under the same licence as Varnish itself. See
1179 LICENCE for details.
1180 • Copyright (c) 2006-2016 Varnish Software AS
1182 VTC(7)