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 When a string is processed, macro expansion is performed. Macros are in
43 the form ${<name>[,<args>...]}, they have a name followed by an op‐
44 tional comma- or space-separated list of arguments. Leading and trail‐
45 ing spaces are ignored.
46 The macros ${foo,bar,baz} and ${ foo bar baz } are equivalent. If an
48 argument contains a space or a comma, arguments can be quoted. For ex‐
49 ample the macro ${foo,"bar,baz"} gives one argument bar,baz to the
50 macro called foo.
51 Unless documented otherwise, all macros are simple macros that don't
53 take arguments.
54 Built-in macros
56 ${bad_backend}
57 A socket address that will reliably never accept connections.
58 ${bad_ip}
60 An unlikely IPv4 address.
61 ${date}
63 The current date and time formatted for HTTP.
64 ${listen_addr}
66 The default listen address various components use, by default a
67 random port on localhost.
68 ${localhost}
70 The first IP address that resolves to "localhost".
71 ${pwd} The working directory from which varnishtest was executed.
73 ${string,<action>[,<args>...]}
75 The string macro is the entry point for text generation, it
76 takes a specialized action with each its own set of arguments.
77 ${string,repeat,<uint>,<str>}
79 Repeat uint times the string str.
80 ${testdir}
82 The directory containing the VTC script of the ongoing test case
83 execution.
84 ${tmpdir}
86 The dedicated working directory for the ongoing test case execu‐
87 tion, which happens to also be the current working directory.
88 Useful when an absolute path to the working directory is needed.
89 ${topbuild}
91 Only present when the -i option is used, to work on Varnish it‐
92 self instead of a regular installation.
93
95 barrier
96 NOTE: This command is available everywhere commands are given.
97 Barriers allows you to synchronize different threads to make sure
99 events occur in the right order. It's even possible to use them in VCL.
100 First, it's necessary to declare the barrier:
102 barrier bNAME TYPE NUMBER [-cyclic]
104 With the arguments being:
106 bNAME this is the name of the barrier, used to identify it when you'll
108 create sync points. It must start with 'b'.
109 TYPE it can be "cond" (mutex) or "sock" (socket) and sets internal
111 behavior. If you don't need VCL synchronization, use cond.
112 NUMBER number of sync point needed to go through the barrier.
114 -cyclic
116 if present, the barrier will reset itself and be ready for an‐
117 other round once gotten through.
118 Then, to add a sync point:
120 barrier bNAME sync
122 This will block the parent thread until the number of sync points for
124 bNAME reaches the NUMBER given in the barrier declaration.
125 If you wish to synchronize the VCL, you need to declare a "sock" bar‐
127 rier. This will emit a macro definition named "bNAME_sock" that you
128 can use in VCL (after importing the vtc vmod):
129 vtc.barrier_sync("${bNAME_sock}");
131 This function returns 0 if everything went well and is the equivalent
133 of barrier bNAME sync at the VTC top-level.
134 client/server
136 Client and server threads are fake HTTP entities used to test your Var‐
137 nish and VCL. They take any number of arguments, and the one that are
138 not recognized, assuming they don't start with '-', are treated as
139 specifications, laying out the actions to undertake:
140 client cNAME [...]
142 server sNAME [...]
143 Clients and server are identified by a string that's the first argu‐
145 ment, clients' names start with 'c' and servers' names start with 's'.
146 As the client and server commands share a good deal of arguments and
148 specification actions, they are grouped in this single section, spe‐
149 cific items will be explicitly marked as such.
150 SECTION: client-server.macros Macros and automatic behaviour
152 To make things easier in the general case, clients will connect by de‐
154 fault to a Varnish server called v1. To connect to a different Varnish
155 server, use '-connect ${vNAME_sock}'.
156 The -vcl+backend switch of the varnish command will add all the de‐
158 clared servers as backends. Be careful though, servers will by default
159 listen to the 127.0.0.1 IP and will pick a random port, and publish 3
160 macros: sNAME_addr, sNAME_port and sNAME_sock, but only once they are
161 started. For 'varnish -vcl+backend' to create the vcl with the correct
162 values, the server must be started first.
163 SECTION: client-server.args Arguments
165 -start Start the thread in background, processing the last given speci‐
167 fication.
168 -wait Block until the thread finishes.
170 -run (client only)
172 Equivalent to "-start -wait".
173 -repeat NUMBER
175 Instead of processing the specification only once, do it NUMBER
176 times.
177 -keepalive
179 For repeat, do not open new connections but rather run all iter‐
180 ations in the same connection
181 -break (server only)
183 Stop the server.
184 -listen STRING (server only)
186 Dictate the listening socket for the server. STRING is of the
187 form "IP PORT", or "/PATH/TO/SOCKET" for a Unix domain socket.
188 In the latter case, the path must begin with '/', and the server
189 must be able to create it.
190 -connect STRING (client only)
192 Indicate the server to connect to. STRING is also of the form
193 "IP PORT", or "/PATH/TO/SOCKET". As with "server -listen", a
194 Unix domain socket is recognized when STRING begins with a '/'.
195 -dispatch (server only, s0 only)
197 Normally, to keep things simple, server threads only handle one
198 connection at a time, but the -dispatch switch allows to accept
199 any number of connection and handle them following the given
200 spec.
201 However, -dispatch is only allowed for the server name "s0".
203 -proxy1 STRING (client only)
205 Use the PROXY protocol version 1 for this connection. STRING is
206 of the form "CLIENTIP:PORT SERVERIP:PORT".
207 -proxy2 STRING (client only)
209 Use the PROXY protocol version 2 for this connection. STRING is
210 of the form "CLIENTIP:PORT SERVERIP:PORT".
211 SECTION: client-server.spec Specification
213 It's a string, either double-quoted "like this", but most of the time
215 enclosed in curly brackets, allowing multilining. Write a command per
216 line in it, empty line are ignored, and long line can be wrapped by us‐
217 ing a backslash. For example:
218 client c1 {
220 txreq -url /foo \
221 -hdr "bar: baz"
222 rxresp
224 } -run
225 accept (server only)
227 Close the current connection, if any, and accept a new one. Note
228 that this new connection is HTTP/1.x.
229 chunked STRING
231 Send STRING as chunked encoding.
232 chunkedlen NUMBER
234 Do as chunked except that the string will be generated for you,
235 with a length of NUMBER characters.
236 close (server only)
238 Close the connection. Note that if operating in HTTP/2 mode no
239 extra (GOAWAY) frame is sent, it's simply a TCP close.
240 expect STRING1 OP STRING2
242 Test if "STRING1 OP STRING2" is true, and if not, fails the
243 test. OP can be ==, <, <=, >, >= when STRING1 and STRING2 rep‐
244 resent numbers in which case it's an order operator. If STRING1
245 and STRING2 are meant as strings OP is a matching operator, ei‐
246 ther == (exact match) or ~ (regex match).
247 varnishtest will first try to resolve STRING1 and STRING2 by
249 looking if they have special meanings, in which case, the re‐
250 solved value is use for the test. Note that this value can be a
251 string representing a number, allowing for tests such as:
252 expect req.http.x-num > 2
254 Here's the list of recognized strings, most should be obvious as
256 they either match VCL logic, or the txreq/txresp options:
257 • remote.ip
259 • remote.port
261 • remote.path
263 • req.method
265 • req.url
267 • req.proto
269 • resp.proto
271 • resp.status
273 • resp.reason
275 • resp.chunklen
277 • req.bodylen
279 • req.body
281 • resp.bodylen
283 • resp.body
285 • req.http.NAME
287 • resp.http.NAME
289 expect_close
291 Reads from the connection, expecting nothing to read but an EOF.
292 fatal|non_fatal
294 Control whether a failure of this entity should stop the test.
295 gunzip Gunzip the body in place.
297 recv NUMBER
299 Read NUMBER bytes from the connection.
300 rxchunk
302 Receive an HTTP chunk.
303 rxpri (server only)
305 Receive a preface. If valid set the server to HTTP/2, abort oth‐
306 erwise.
307 rxreq (server only)
309 Receive and parse a request's headers and body.
310 rxreqbody (server only)
312 Receive a request's body.
313 rxreqhdrs (server only)
315 Receive and parse a request's headers (but not the body).
316 rxresp [-no_obj] (client only)
318 Receive and parse a response's headers and body. If -no_obj is
319 present, only get the headers.
320 rxrespbody (client only)
322 Receive (part of) a response's body.
323 -max : max length of this receive, 0 for all
325 rxresphdrs (client only)
327 Receive and parse a response's headers.
328 send STRING
330 Push STRING on the connection.
331 send_n NUMBER STRING
333 Write STRING on the socket NUMBER times.
334 send_urgent STRING
336 Send string as TCP OOB urgent data. You will never need this.
337 sendhex STRING
339 Send bytes as described by STRING. STRING should consist of hex
340 pairs possibly separated by whitespace or newlines. For example:
341 "0F EE a5 3df2".
342 settings -dectbl INT
344 Force internal HTTP/2 settings to certain values. Currently only
345 support setting the decoding table size.
346 shell Same as for the top-level shell.
348 stream HTTP/2 introduces the concept of streams, and these come with
350 their own specification, and as it's quite big, have been moved
351 to their own chapter.
352 SECTION: stream stream
354 (note: this section is at the top-level for easier navigation, but it's
356 part of the client/server specification)
357 Streams map roughly to a request in HTTP/2, a request is sent on stream
359 N, the response too, then the stream is discarded. The main exception
360 is the first stream, 0, that serves as coordinator.
361 Stream syntax follow the client/server one:
363 stream ID [SPEC] [ACTION]
365 ID is the HTTP/2 stream number, while SPEC describes what will be done
367 in that stream.
368 Note that, when parsing a stream action, if the entity isn't operating
370 in HTTP/2 mode, these spec is ran before:
371 txpri/rxpri # client/server
373 stream 0 {
374 txsettings
375 rxsettings
376 txsettings -ack
377 rxsettings
378 expect settings.ack == true
379 } -run
380 And HTTP/2 mode is then activated before parsing the specification.
382 SECTION: stream.actions Actions
384 -start Run the specification in a thread, giving back control immedi‐
386 ately.
387 -wait Wait for the started thread to finish running the spec.
389 -run equivalent to calling -start then -wait.
391 timeout NUMBER
393 Set the TCP timeout for this entity.
394 txpri (client only)
396 Send an HTTP/2 preface ("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n") and
397 set client to HTTP/2.
398 txreq|txresp [...]
400 Send a minimal request or response, but overload it if neces‐
401 sary.
402 txreq is client-specific and txresp is server-specific.
404 The only thing different between a request and a response, apart
406 from who can send them is that the first line (request line vs
407 status line), so all the options are prety much the same.
408 -method STRING (txreq only)
410 What method to use (default: "GET").
411 -req STRING (txreq only)
413 Alias for -method.
414 -url STRING (txreq only)
416 What location to use (default "/").
417 -proto STRING
419 What protocol use in the status line. (default:
420 "HTTP/1.1").
421 -status NUMBER (txresp only)
423 What status code to return (default 200).
424 -reason STRING (txresp only)
426 What message to put in the status line (default: "OK").
427 These three switches can appear in any order but must come be‐
429 fore the following ones.
430 -nohost
432 Don't include a Host header in the request.
433 -nolen Don't include a Content-Length header.
435 -hdr STRING
437 Add STRING as a header, it must follow this format:
438 "name: value". It can be called multiple times.
439 -hdrlen STRING NUMBER
441 Add STRING as a header with NUMBER bytes of content.
442 You can then use the arguments related to the body:
444 -body STRING
446 Input STRING as body.
447 -bodyfrom FILE
449 Same as -body but content is read from FILE.
450 -bodylen NUMBER
452 Generate and input a body that is NUMBER bytes-long.
453 -gziplevel NUMBER
455 Set the gzip level (call it before any of the other gzip
456 switches).
457 -gzipresidual NUMBER
459 Add extra gzip bits. You should never need it.
460 -gzipbody STRING
462 Gzip STRING and send it as body.
463 -gziplen NUMBER
465 Combine -bodylen and -gzipbody: generate a string of
466 length NUMBER, gzip it and send as body.
467 write_body STRING
469 Write the body of a request or a response to a file. By using
470 the shell command, higher-level checks on the body can be per‐
471 formed (eg. XML, JSON, ...) provided that such checks can be
472 delegated to an external program.
473 delay
475 NOTE: This command is available everywhere commands are given.
476 Sleep for the number of seconds specified in the argument. The number
478 can include a fractional part, e.g. 1.5.
479 feature
481 Test that the required feature(s) for a test are available, and skip
482 the test otherwise; or change the interpretation of the test, as docu‐
483 mented below. feature takes any number of arguments from this list:
484 64bit The environment is 64 bits
486 ipv4 127.0.0.1 works
488 ipv6 [::1] works
490 dns DNS lookups are working
492 topbuild
494 The test has been started with '-i'
495 root The test has been invoked by the root user
497 user_varnish
499 The varnish user is present
500 user_vcache
502 The vcache user is present
503 group_varnish
505 The varnish group is present
506 cmd <command-line>
508 A command line that should execute with a zero exit status
509 ignore_unknown_macro
511 Do not fail the test if a string of the form ${...} is not rec‐
512 ognized as a macro.
513 persistent_storage
515 Varnish was built with the deprecated persistent storage.
516 coverage
518 Varnish was built with code coverage enabled.
519 asan Varnish was built with the address sanitizer.
521 msan Varnish was built with the memory sanitizer.
523 tsan Varnish was built with the thread sanitizer.
525 ubsan Varnish was built with the undefined behavior sanitizer.
527 sanitizer
529 Varnish was built with a sanitizer.
530 workspace_emulator
532 Varnish was built with its workspace emulator.
533 A feature name can be prefixed with an exclamation mark (!) to skip a
535 test if the feature is present.
536 Be careful with ignore_unknown_macro, because it may cause a test with
538 a misspelled macro to fail silently. You should only need it if you
539 must run a test with strings of the form "${...}".
540 haproxy
542 Define and interact with haproxy instances.
543 To define a haproxy server, you'll use this syntax:
545 haproxy hNAME -conf-OK CONFIG
547 haproxy hNAME -conf-BAD ERROR CONFIG
548 haproxy hNAME [-D] [-W] [-arg STRING] [-conf[+vcl] STRING]
549 The first haproxy hNAME invocation will start the haproxy master
551 process in the background, waiting for the -start switch to actually
552 start the child.
553 Arguments:
555 hNAME Identify the HAProxy server with a string, it must starts with
557 'h'.
558 -conf-OK CONFIG
560 Run haproxy in '-c' mode to check config is OK
562 stdout/stderr should contain 'Configuration file is
563 valid' The exit code should be 0.
564 -conf-BAD ERROR CONFIG
566 Run haproxy in '-c' mode to check config is BAD.
568 "ERROR" should be part of the diagnostics on std‐
569 out/stderr. The exit code should be 1.
570 -D Run HAproxy in daemon mode. If not given '-d' mode used.
572 -W Enable HAproxy in Worker mode.
574 -S Enable HAproxy Master CLI in Worker mode
576 -arg STRING
578 Pass an argument to haproxy, for example "-h simple_list".
579 -cli STRING
581 Specify the spec to be run by the command line interface (CLI).
582 -mcli STRING
584 Specify the spec to be run by the command line interface (CLI)
585 of the Master process.
586 -conf STRING
588 Specify the configuration to be loaded by this HAProxy instance.
589 -conf+backend STRING
591 Specify the configuration to be loaded by this HAProxy instance,
593 all server instances will be automatically appended
594 -start Start this HAProxy instance.
596 -wait Stop this HAProxy instance.
598 -expectexit NUMBER
600 Expect haproxy to exit(3) with this value
601 logexpect
603 Reads the VSL and looks for records matching a given specification. It
604 will process records trying to match the first pattern, and when done,
605 will continue processing, trying to match the following pattern. If a
606 pattern isn't matched, the test will fail.
607 logexpect threads are declared this way:
609 logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
611 [vsl arguments] {
612 expect <skip> <vxid> <tag> <regex>
613 expect <skip> <vxid> <tag> <regex>
614 fail add <vxid> <tag> <regex>
615 fail clear
616 abort
617 ...
618 } [-start|-wait]
619 And once declared, you can start them, or wait on them:
621 logexpect lNAME <-start|-wait>
623 With:
625 lNAME Name the logexpect thread, it must start with 'l'.
627 -v id Specify the varnish instance to use (most of the time, id=v1).
629 -g <session|request|vxid|raw
631 Decide how records are grouped, see -g in man varnishlog for
632 more information.
633 -d <0|1>
635 Start processing log records at the head of the log instead of
636 the tail.
637 -q query
639 Filter records using a query expression, see man vsl-query for
640 more information. Multiple -q options are not supported.
641 -m Also emit log records for misses (only for debugging)
643 -err Invert the meaning of success. Usually called once to expect the
645 logexpect to fail
646 -start Start the logexpect thread in the background.
648 -wait Wait for the logexpect thread to finish
650 VSL arguments (similar to the varnishlog options):
652 -C Use caseless regex
654 -i <taglist>
656 Include tags
657 -I <[taglist:]regex>
659 Include by regex
660 -T <seconds>
662 Transaction end timeout
663 expect specification:
665 skip: [uint|*|?]
667 Max number of record to skip
668 vxid: [uint|*|=]
670 vxid to match
671 tag: [tagname|*|=]
673 Tag to match against
674 regex: regular expression to match against (optional)
676 For skip, vxid and tag, '*' matches anything, '=' expects the value of
678 the previous matched record. The '?' marker is equivalent to zero, ex‐
679 pecting a match on the next record. The difference is that '?' can be
680 used when the order of individual consecutive logs is not determinis‐
681 tic. In other words, lines from a block of alternatives marked by '?'
682 can be matched in any order, but all need to match eventually.
683 fail specification:
685 add: Add to the fail list
687 Arguments are equivalent to expect, except for skip missing
688 clear: Clear the fail list
690 Any number of fail specifications can be active during execution of a
692 logexpect. All active fail specifications are matched against every log
693 line and, if any match, the logexpect fails immediately.
694 For a logexpect to end successfully, there must be no specs on the fail
696 list, so logexpects should always end with
697 expect <skip> <vxid> <tag> <termination-condition> fail clear
698 abort specification:
700 abort(3) varnishtest, intended to help debugging of the VSL client li‐
702 brary itself.
703 process
705 Run a process with stdin+stdout on a pseudo-terminal and stderr on a
706 pipe.
707 Output from the pseudo-terminal is copied verbatim to ${pNAME_out}, and
709 the -log/-dump/-hexdump flags will also put it in the vtc-log.
710 The pseudo-terminal is not in ECHO mode, but if the programs run set it
712 to ECHO mode ("stty sane") any input sent to the process will also ap‐
713 pear in this stream because of the ECHO.
714 Output from the stderr-pipe is copied verbatim to ${pNAME_err}, and is
716 always included in the vtc_log.
717 process pNAME SPEC [-log] [-dump] [-hexdump] [-expect-exit N]
719 [-start] [-run] [-write STRING] [-writeln STRING] [-kill
720 STRING] [-stop] [-wait] [-close]
721 pNAME Name of the process. It must start with 'p'.
723 SPEC The command(s) to run in this process.
725 -hexdump
727 Log output with vtc_hexdump(). Must be before -start/-run.
728 -dump Log output with vtc_dump(). Must be before -start/-run.
730 -log Log output with VLU/vtc_log(). Must be before -start/-run.
732 -start Start the process.
734 -expect-exit N
736 Expect exit status N
737 -wait Wait for the process to finish.
739 -run Shorthand for -start -wait.
741 In most cases, if you just want to start a process and wait for
743 it to finish, you can use the shell command instead. The fol‐
744 lowing commands are equivalent:
745 shell "do --something"
747 process p1 "do --something" -run
749 However, you may use the the process variant to conveniently
751 collect the standard input and output without dealing with shell
752 redirections yourself. The shell command can also expect an ex‐
753 pression from either output, consider using it if you only need
754 to match one.
755 -kill STRING
757 Send a signal to the process. The argument can be either the
758 string "TERM", "INT", or "KILL" for SIGTERM, SIGINT or SIGKILL
759 signals, respectively, or a hyphen (-) followed by the signal
760 number.
761 If you need to use other signal names, you can use the kill(1)
763 command directly:
764 shell "kill -USR1 ${pNAME_pid}"
766 Note that SIGHUP usage is discouraged in test cases.
768 -stop Shorthand for -kill TERM.
770 -winsz LIN COL
772 Change the terminal window size to LIN lines and COL columns.
773 -write STRING
775 Write a string to the process' stdin.
776 -writeln STRING
778 Same as -write followed by a newline (\n).
779 -writehex HEXSTRING
781 Same as -write but interpreted as hexadecimal bytes.
782 -need-bytes [+]NUMBER
784 Wait until at least NUMBER bytes have been received in total.
785 If '+' is prefixed, NUMBER new bytes must be received.
786 -expect-text LIN COL PAT
788 Wait for PAT to appear at LIN,COL on the virtual screen. Lines
789 and columns are numbered 1...N LIN==0 means "on any line" COL==0
790 means "anywhere on the line"
791 -close Alias for "-kill HUP"
793 -screen_dump
795 Dump the virtual screen into vtc_log
796 setenv
798 Set or change an environment variable:
799 setenv FOO "bar baz"
801 The above will set the environment variable $FOO to the value provided.
803 There is also an -ifunset argument which will only set the value if the
804 the environment variable does not already exist:
805 setenv -ifunset FOO quux
807 shell
809 NOTE: This command is available everywhere commands are given.
810 Pass the string given as argument to a shell. If you have multiple com‐
812 mands to run, you can use curly brackets to describe a multi-lines
813 script, eg:
814 shell {
816 echo begin
817 cat /etc/fstab
818 echo end
819 }
820 By default a zero exit code is expected, otherwise the vtc will fail.
822 Notice that the commandstring is prefixed with "exec 2>&1;" to combine
824 stderr and stdout back to the test process.
825 Optional arguments:
827 -err Expect non-zero exit code.
829 -exit N
831 Expect exit code N instead of zero.
832 -expect STRING
834 Expect string to be found in stdout+err.
835 -match REGEXP
837 Expect regexp to match the stdout+err output.
838 Specification
840 The specification of a stream follows the exact same rules as one for a
841 client or a server.
842 txreq, txresp, txcont, txpush
844 These four commands are about sending headers. txreq and txresp will
845 send HEADER frames; txcont will send CONTINUATION frames; txpush PUSH
846 frames. The only difference between txreq and txresp are the default
847 headers set by each of them.
848 -noadd Do not add default headers. Useful to avoid duplicates when
850 sending default headers using -hdr, -idxHdr and -litIdxHdr.
851 -status INT (txresp)
853 Set the :status pseudo-header.
854 -url STRING (txreq, txpush)
856 Set the :path pseudo-header.
857 -method STRING (txreq, txpush)
859 Set the :method pseudo-header.
860 -req STRING (txreq, txpush)
862 Alias for -method.
863 -scheme STRING (txreq, txpush)
865 Set the :scheme pseudo-header.
866 -hdr STRING1 STRING2
868 Insert a header, STRING1 being the name, and STRING2 the value.
869 -idxHdr INT
871 Insert an indexed header, using INT as index.
872 -litIdxHdr inc|not|never INT huf|plain STRING
874 Insert an literal, indexed header. The first argument specify if
875 the header should be added to the table, shouldn't, or mustn't
876 be compressed if/when retransmitted.
877 INT is the idex of the header name to use.
879 The third argument informs about the Huffman encoding: yes (huf)
881 or no (plain).
882 The last term is the literal value of the header.
884 -litHdr inc|not|never huf|plain STRING1 huf|plain STRING2
886 Insert a literal header, with the same first argument as
887 -litIdxHdr.
888 The second and third terms tell what the name of the header is
890 and if it should be Huffman-encoded, while the last two do the
891 same regarding the value.
892 -body STRING (txreq, txresp)
894 Specify a body, effectively putting STRING into a DATA frame af‐
895 ter the HEADER frame is sent.
896 -bodyfrom FILE (txreq, txresp)
898 Same as -body but content is read from FILE.
899 -bodylen INT (txreq, txresp)
901 Do the same thing as -body but generate a string of INT length
902 for you.
903 -gzipbody STRING (txreq, txresp)
905 Gzip STRING and send it as body.
906 -gziplen NUMBER (txreq, txresp)
908 Combine -bodylen and -gzipbody: generate a string of length NUM‐
909 BER, gzip it and send as body.
910 -nostrend (txreq, txresp)
912 Don't set the END_STREAM flag automatically, making the peer ex‐
913 pect a body after the headers.
914 -nohdrend
916 Don't set the END_HEADERS flag automatically, making the peer
917 expect more HEADER frames.
918 -dep INT (txreq, txresp)
920 Tell the peer that this content depends on the stream with the
921 INT id.
922 -ex (txreq, txresp)
924 Make the dependency exclusive (-dep is still needed).
925 -weight (txreq, txresp)
927 Set the weight for the dependency.
928 -promised INT (txpush)
930 The id of the promised stream.
931 -pad STRING / -padlen INT (txreq, txresp, txpush)
933 Add string as padding to the frame, either the one you provided
934 with -pad, or one that is generated for you, of length INT is
935 -padlen case.
936 txdata
938 By default, data frames are empty. The receiving end will know the
939 whole body has been delivered thanks to the END_STREAM flag set in the
940 last DATA frame, and txdata automatically set it.
941 -data STRING
943 Data to be embedded into the frame.
944 -datalen INT
946 Generate and INT-bytes long string to be sent in the frame.
947 -pad STRING / -padlen INT
949 Add string as padding to the frame, either the one you provided
950 with -pad, or one that is generated for you, of length INT is
951 -padlen case.
952 -nostrend
954 Don't set the END_STREAM flag, allowing to send more data on
955 this stream.
956 rxreq, rxresp
958 These are two convenience functions to receive headers and body of an
959 incoming request or response. The only difference is that rxreq can
960 only be by a server, and rxresp by a client.
961 rxhdrs
963 rxhdrs will expect one HEADER frame, then, depending on the arguments,
964 zero or more CONTINUATION frame.
965 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
967 seen.
968 -some INT
970 Retrieve INT - 1 CONTINUATION frames after the HEADER frame.
971 rxpush
973 This works like rxhdrs, expecting a PUSH frame and then zero or more
974 CONTINUATION frames.
975 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
977 seen.
978 -some INT
980 Retrieve INT - 1 CONTINUATION frames after the PUSH frame.
981 rxdata
983 Receiving data is done using the rxdata keywords and will retrieve one
984 DATA frame, if you wish to receive more, you can use these two conve‐
985 nience arguments:
986 -all keep waiting for DATA frame until one sets the END_STREAM flag
988 -some INT
990 retrieve INT DATA frames.
991 Receive a frame, any frame.
993 sendhex
995 Push bytes directly on the wire. sendhex takes exactly one argument: a
996 string describing the bytes, in hex notation, with possible whitespaces
997 between them. Here's an example:
998 sendhex "00 00 08 00 0900 8d"
1000 rxgoaway
1002 Receive a GOAWAY frame.
1003 gunzip
1005 Same as the gunzip command for HTTP/1.
1006 rxping
1008 Receive a PING frame.
1009 txping
1011 Send PING frame.
1012 -data STRING
1014 specify the payload of the frame, with STRING being an 8-char
1015 string.
1016 -ack set the ACK flag.
1018 rxprio
1020 Receive a PRIORITY frame.
1021 txprio
1023 Send a PRIORITY frame
1024 -stream INT
1026 indicate the id of the stream the sender stream depends on.
1027 -ex the dependency should be made exclusive (only this streams de‐
1029 pends on the parent stream).
1030 -weight INT
1032 an 8-bits integer is used to balance priority between streams
1033 depending on the same streams.
1034 rxrst
1036 Receive a RST_STREAM frame.
1037 txrst
1039 Send a RST_STREAM frame. By default, txrst will send a 0 error code
1040 (NO_ERROR).
1041 -err STRING|INT
1043 Sets the error code to be sent. The argument can be an integer
1044 or a string describing the error, such as NO_ERROR, or CANCEL
1045 (see rfc7540#11.4 for more strings).
1046 rxsettings
1048 Receive a SETTINGS frame.
1049 txsettings
1051 SETTINGS frames must be acknowledge, arguments are as follow (most of
1052 them are from rfc7540#6.5.2):
1053 -hdrtbl INT
1055 headers table size
1056 -push BOOL
1058 whether push frames are accepted or not
1059 -maxstreams INT
1061 maximum concurrent streams allowed
1062 -winsize INT
1064 sender's initial window size
1065 -framesize INT
1067 largest frame size authorized
1068 -hdrsize INT
1070 maximum size of the header list authorized
1071 -ack set the ack bit
1073 rxwinup
1075 Receive a WINDOW_UPDATE frame.
1076 txwinup
1078 Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the
1079 connection (from stream 0) or of the stream (any other stream).
1080 -size INT
1082 give INT credits to the peer.
1083 write_body STRING
1085 Same as the write_body command for HTTP/1.
1086 expect
1088 expect in stream works as it does in client or server, except that the
1089 elements compared will be different.
1090 Most of these elements will be frame specific, meaning that the last
1092 frame received on that stream must of the correct type.
1093 Here the list of keywords you can look at.
1095 GOAWAY specific
1097 goaway.err
1098 The error code (as integer) of the GOAWAY frame.
1099 goaway.laststream
1101 Last-Stream-ID
1102 goaway.debug
1104 Debug data, if any.
1105 PING specific
1107 ping.data
1108 The 8-bytes string of the PING frame payload.
1109 ping.ack (PING)
1111 "true" if the ACK flag was set, "false" otherwise.
1112 PRIORITY specific
1114 prio.stream
1115 The stream ID announced.
1116 prio.exclusive
1118 "true" if the priority is exclusive, else "false".
1119 prio.weight
1121 The dependency weight.
1122 PUSH_PROMISE specific
1124 push.id
1125 The id of the promised stream.
1126 RESET_STREAM specific
1128 rst.err
1129 The error code (as integer) of the RESET_STREAM frame.
1130 SETTINGS specific
1132 settings.ack
1133 "true" if the ACK flag was set, else ""false.
1134 settings.push
1136 "true" if the push settings was set to yes, "false" if set to
1137 no, and <undef> if not present.
1138 settings.hdrtbl
1140 Value of HEADER_TABLE_SIZE if set, <undef> otherwise.
1141 settings.maxstreams
1143 Value of MAX_CONCURRENT_STREAMS if set, <undef> otherwise.
1144 settings.winsize
1146 Value of INITIAL_WINDOW_SIZE if set, <undef> otherwise.
1147 setting.framesize
1149 Value of MAX_FRAME_SIZE if set, <undef> otherwise.
1150 settings.hdrsize
1152 Value of MAX_HEADER_LIST_SIZE if set, <undef> otherwise.
1153 WINDOW_UPDATE specific
1155 winup.size
1156 The size of the upgrade given by the WINDOW_UPDATE frame.
1157 Generic frame
1159 frame.data
1160 Payload of the last frame
1161 frame.type
1163 Type of the frame, as integer.
1164 frame.size
1166 Size of the frame.
1167 frame.stream
1169 Stream of the frame (correspond to the one you are executing
1170 this from, obviously).
1171 frame.padding (for DATA, HEADERS, PUSH_PROMISE frames)
1173 Number of padded bytes.
1174 Request and response
1176 Note: it's possible to inspect a request or response while it is still
1177 being construct (in-between two frames for example).
1178 req.bodylen / resp.bodylen
1180 Length in bytes of the request/response so far.
1181 req.body / resp.body
1183 Body of the request/response so far.
1184 req.http.STRING / resp.http.STRING
1186 Value of the header STRING in the request/response.
1187 req.status / resp.status
1189 :status pseudo-header's value.
1190 req.url / resp.url
1192 :path pseudo-header's value.
1193 req.method / resp.method
1195 :method pseudo-header's value.
1196 req.authority / resp.authority
1198 :method pseudo-header's value.
1199 req.scheme / resp.scheme
1201 :method pseudo-header's value.
1202 Stream
1204 stream.window
1205 The current window size of the stream, or, if on stream 0, of
1206 the connection.
1207 stream.weight
1209 Weight of the stream
1210 stream.dependency
1212 Id of the stream this one depends on.
1213 Index tables
1215 tbl.dec.size / tbl.enc.size
1216 Size (bytes) of the decoding/encoding table.
1217 tbl.dec.size / tbl.enc.maxsize
1219 Maximum size (bytes) of the decoding/encoding table.
1220 tbl.dec.length / tbl.enc.length
1222 Number of headers in decoding/encoding table.
1223 tbl.dec[INT].key / tbl.enc[INT].key
1225 Name of the header at index INT of the decoding/encoding table.
1226 tbl.dec[INT].value / tbl.enc[INT].value
1228 Value of the header at index INT of the decoding/encoding table.
1229 syslog
1231 Define and interact with syslog instances (for use with haproxy)
1232 To define a syslog server, you'll use this syntax:
1234 syslog SNAME
1236 Arguments:
1238 SNAME Identify the syslog server with a string which must start with
1240 'S'.
1241 -level STRING
1243 Set the default syslog priority level used by any subsequent
1244 "recv" command. Any syslog dgram with a different level will be
1245 skipped by "recv" command. This default level value may be su‐
1246 perseded by "recv" command if supplied as first argument: "recv
1247 <level>".
1248 -start Start the syslog server thread in the background.
1250 -repeat
1252 Instead of processing the specification only once, do it
1254 NUMBER times.
1255 -bind Bind the syslog socket to a local address.
1257 -wait Wait for that thread to terminate.
1259 -stop Stop the syslog server thread.
1261 tunnel
1263 The goal of a tunnel is to help control the data transfer between two
1264 parties, for example to trigger socket timeouts in the middle of proto‐
1265 col frames, without the need to change how both parties are imple‐
1266 mented.
1267 A tunnel accepts a connection and then connects on behalf of the source
1269 to the desired destination. Once both connections are established the
1270 tunnel will transfer bytes unchanged between the source and destina‐
1271 tion. Transfer can be interrupted, usually with the help of synchro‐
1272 nization methods like barriers. Once the transfer is paused, it is pos‐
1273 sible to let a specific amount of bytes move in either direction.
1274 SECTION: tunnel.args Arguments
1276 -start Start the tunnel in background, processing the last given speci‐
1278 fication.
1279 -start+pause
1281 Start the tunnel, but already paused.
1282 -wait Block until the thread finishes.
1284 -listen STRING
1286 Dictate the listening socket for the server. STRING is of the
1287 form "IP PORT", or "HOST PORT".
1288 Listens by defaults to a local random port.
1290 -connect STRING
1292 Indicate the server to connect to. STRING is also of the form
1293 "IP PORT", or "HOST PORT".
1294 Connects by default to a varnish instance called v1.
1296 SECTION: tunnel.spec Specification
1298 The specification contains a list of tunnel commands that can be com‐
1300 bined with barriers and delays. For example:
1301 tunnel t1 {
1303 barrier b1 sync
1304 pause
1305 delay 1
1306 send 42
1307 barrier b2 sync
1308 resume
1309 } -start
1310 If one end of the tunnel is closed before the end of the specification
1312 the test case will fail. A specification that ends in a paused state
1313 will implicitely resume the tunnel.
1314 varnish
1316 Define and interact with varnish instances.
1317 To define a Varnish server, you'll use this syntax:
1319 varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
1321 [-errvcl STRING STRING] [-jail STRING] [-proto PROXY]
1322 The first varnish vNAME invocation will start the varnishd master
1324 process in the background, waiting for the -start switch to actually
1325 start the child.
1326 Types used in the description below:
1328 PATTERN
1330 is a 'glob' style pattern (ie: fnmatch(3)) as used in shell
1331 filename expansion.
1332 Arguments:
1334 vNAME Identify the Varnish server with a string, it must starts with
1336 'v'.
1337 -arg STRING
1339 Pass an argument to varnishd, for example "-h simple_list".
1340 -vcl STRING
1342 Specify the VCL to load on this Varnish instance. You'll proba‐
1343 bly want to use multi-lines strings for this ({...}).
1344 -vcl+backend STRING
1346 Do the exact same thing as -vcl, but adds the definition block
1347 of known backends (ie. already defined).
1348 -errvcl STRING1 STRING2
1350 Load STRING2 as VCL, expecting it to fail, and Varnish to send
1351 an error string matching STRING1
1352 -jail STRING
1354 Look at man varnishd (-j) for more information.
1355 -proto PROXY
1357 Have Varnish use the proxy protocol. Note that PROXY here is the
1358 actual string.
1359 You can decide to start the Varnish instance and/or wait for several
1361 events:
1362 varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]
1364 -start Start the child process.
1366 Once successfully started, the following macros are available
1368 for the default listen address: ${vNAME_addr}, ${vNAME_port} and
1369 ${vNAME_sock}. Additional macros are available, including the
1370 listen address name for each address vNAME listens to, like for
1371 example: ${vNAME_a0_addr}.
1372 -stop Stop the child process.
1374 -syntax
1376 Set the VCL syntax level for this command (default: 4.1)
1377 -wait Wait for that instance to terminate.
1379 -wait-running
1381 Wait for the Varnish child process to be started.
1382 -wait-stopped
1384 Wait for the Varnish child process to stop.
1385 -cleanup
1387 Once Varnish is stopped, clean everything after it. This is only
1388 used in very few tests and you should never need it.
1389 -expectexit NUMBER
1391 Expect varnishd to exit(3) with this value
1392 Once Varnish is started, you can talk to it (as you would through var‐
1394 nishadm) with these additional switches:
1395 varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
1397 [-clijson STRING]
1398 -cli STRING|-cliok STRING|-clierr STATUS STRING|-cliexpect REGEXP
1400 STRING
1401 All four of these will send STRING to the CLI, the only differ‐
1402 ence is what they expect the result to be. -cli doesn't expect
1403 anything, -cliok expects 200, -clierr expects STATUS, and -cli‐
1404 expect expects the REGEXP to match the returned response.
1405 -clijson STRING
1407 Send STRING to the CLI, expect success (CLIS_OK/200) and check
1408 that the response is parsable JSON.
1409 It is also possible to interact with its shared memory (as you would
1411 through tools like varnishstat) with additional switches:
1412 -expect !PATTERN|PATTERN OP NUMBER|PATTERN OP PATTERN
1414 Look into the VSM and make sure the first VSC counter identified
1415 by PATTERN has a correct value. OP can be ==, >, >=, <, <=. For
1416 example:
1417 varnish v1 -expect SM?.s1.g_space > 1000000
1419 varnish v1 -expect cache_hit >= cache_hit_grace
1420 In the ! form the test fails if a counter matches PATTERN.
1422 The MAIN. namespace can be omitted from PATTERN.
1424 The test takes up to 5 seconds before timing out.
1426 -vsc PATTERN
1428 Dump VSC counters matching PATTERN.
1429 -vsl_catchup
1431 Wait until the logging thread has idled to make sure that all
1432 the generated log is flushed
1433 varnishtest
1435 Alternate name for 'vtest', see above.
1436 vtest
1438 This should be the first command in your vtc as it will identify the
1439 test case with a short yet descriptive sentence. It takes exactly one
1440 argument, a string, eg:
1441 vtest "Check that vtest is actually a valid command"
1443 It will also print that string in the log.
1445
1447 This document has been written by Guillaume Quintard.
1448
1450 • varnishtest(1)
1451 • vmod_vtc(3)
1453
1455 This document is licensed under the same licence as Varnish itself. See
1456 LICENCE for details.
1457 • Copyright (c) 2006-2016 Varnish Software AS
1459 VTC(7)