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 loop NUMBER STRING
241 Process STRING as a specification, NUMBER times.
242 recv NUMBER
244 Read NUMBER bytes from the connection.
245 rxchunk
247 Receive an HTTP chunk.
248 rxpri (server only)
250 Receive a preface. If valid set the server to HTTP/2, abort oth‐
251 erwise.
252 rxreq (server only)
254 Receive and parse a request's headers and body.
255 rxreqbody (server only)
257 Receive a request's body.
258 rxreqhdrs
260 Receive and parse a request's headers (but not the body).
261 rxresp [-no_obj] (client only)
263 Receive and parse a response's headers and body. If -no_obj is
264 present, only get the headers.
265 rxrespbody (client only)
267 Receive a response's body.
268 rxresphdrs (client only)
270 Receive and parse a response's headers.
271 send STRING
273 Push STRING on the connection.
274 send_n NUMBER STRING
276 Write STRING on the socket NUMBER times.
277 send_urgent STRING
279 Send string as TCP OOB urgent data. You will never need this.
280 sendhex STRING
282 Send bytes as described by STRING. STRING should consist of hex
283 pairs possibly separated by whitespace or newlines. For example:
284 "0F EE a5 3df2".
285 settings -dectbl INT
287 Force internal HTTP/2 settings to certain values. Currently only
288 support setting the decoding table size.
289 shell Same as for the top-level shell.
291 stream HTTP/2 introduces the concept of streams, and these come with
293 their own specification, and as it's quite big, have been moved
294 to their own chapter.
295 timeout NUMBER
297 Set the TCP timeout for this entity.
298 txpri (client only)
300 Send an HTTP/2 preface ("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n") and
301 set client to HTTP/2.
302 txreq|txresp [...]
304 Send a minimal request or response, but overload it if neces‐
305 sary.
306 txreq is client-specific and txresp is server-specific.
308 The only thing different between a request and a response, apart
310 from who can send them is that the first line (request line vs
311 status line), so all the options are prety much the same.
312 -req STRING (txreq only)
314 What method to use (default: "GET").
315 -url STRING (txreq only)
317 What location to use (default "/").
318 -proto STRING
320 What protocol use in the status line. (default:
321 "HTTP/1.1").
322 -status NUMBER (txresp only)
324 What status code to return (default 200).
325 -reason STRING (txresp only)
327 What message to put in the status line (default: "OK").
328 These three switches can appear in any order but must come
330 before the following ones.
331 -nohost
333 Don't include a Host header in the request.
334 -nolen Don't include a Content-Length header.
336 -hdr STRING
338 Add STRING as a header, it must follow this format:
339 "name: value". It can be called multiple times.
340 -hdrlen STRING NUMBER
342 Add STRING as a header with NUMBER bytes of content.
343 You can then use the arguments related to the body:
345 -body STRING
347 Input STRING as body.
348 -bodylen NUMBER
350 Generate and input a body that is NUMBER bytes-long.
351 -gziplevel NUMBER
353 Set the gzip level (call it before any of the other gzip
354 switches).
355 -gzipresidual NUMBER
357 Add extra gzip bits. You should never need it.
358 -gzipbody STRING
360 Zip STRING and send it as body.
361 -gziplen NUMBER
363 Combine -body and -gzipbody: create a body of length NUM‐
364 BER, zip it and send as body.
365 write_body STRING
367 Write the body of a request or a response to a file. By using
368 the shell command, higher-level checks on the body can be per‐
369 formed (eg. XML, JSON, ...) provided that such checks can be
370 delegated to an external program.
371 delay
373 NOTE: This command is available everywhere commands are given.
374 Sleep for the number of seconds specified in the argument. The number
376 can include a fractional part, e.g. 1.5.
377 err_shell
379 NOTICE: err_shell is deprecated, use shell -err -expect instead.
380 This is very similar to the the shell command, except it takes a first
382 string as argument before the command:
383 err_shell "foo" "echo foo"
385 err_shell expect the shell command to fail AND stdout to match the
387 string, failing the test case otherwise.
388 feature
390 Test that the required feature(s) for a test are available, and skip
391 the test otherwise; or change the interpretation of the test, as docu‐
392 mented below. feature takes any number of arguments from this list:
393 SO_RCVTIMEO_WORKS
395 The SO_RCVTIMEO socket option is working
396 64bit The environment is 64 bits
398 !OSX The environment is not OSX
400 dns DNS lookups are working
402 topbuild
404 The test has been started with '-i'
405 root The test has been invoked by the root user
407 user_varnish
409 The varnish user is present
410 user_vcache
412 The vcache user is present
413 group_varnish
415 The varnish group is present
416 cmd <command-line>
418 A command line that should execute with a zero exit status
419 ignore_unknown_macro
421 Do not fail the test if a string of the form ${...} is not rec‐
422 ognized as a macro.
423 persistent_storage
425 Varnish was built with the deprecated persistent storage.
426 Be careful with ignore_unknown_macro, because it may cause a test with
428 a misspelled macro to fail silently. You should only need it if you
429 must run a test with strings of the form "${...}".
430 haproxy
432 Define and interact with haproxy instances.
433 To define a haproxy server, you'll use this syntax:
435 haproxy hNAME -conf-OK CONFIG
437 haproxy hNAME -conf-BAD ERROR CONFIG
438 haproxy hNAME [-D] [-W] [-arg STRING] [-conf[+vcl] STRING]
439 The first haproxy hNAME invocation will start the haproxy master
441 process in the background, waiting for the -start switch to actually
442 start the child.
443 Arguments:
445 hNAME Identify the HAProxy server with a string, it must starts with
447 'h'.
448 -conf-OK CONFIG
450 Run haproxy in '-c' mode to check config is OK
452 stdout/stderr should contain 'Configuration file is
453 valid' The exit code should be 0.
454 -conf-BAD ERROR CONFIG
456 Run haproxy in '-c' mode to check config is BAD.
458 "ERROR" should be part of the diagnostics on std‐
459 out/stderr. The exit code should be 1.
460 -D Run HAproxy in daemon mode. If not given '-d' mode used.
462 -W Enable HAproxy in Worker mode.
464 -arg STRING
466 Pass an argument to haproxy, for example "-h simple_list".
467 -cli STRING
469 Specify the spec to be run by the command line interface (CLI).
470 -conf STRING
472 Specify the configuration to be loaded by this HAProxy instance.
473 -conf+backend STRING
475 Specify the configuration to be loaded by this HAProxy instance,
477 all server instances will be automatically appended
478 -start Start this HAProxy instance.
480 -wait Stop this HAProxy instance.
482 -expectexit NUMBER
484 Expect haproxy to exit(3) with this value
485 haproxy CLI Specification
487 expect OP STRING
488 Regex match the CLI reception buffer with STRING if OP is ~ or,
489 on the contraty, if OP is !~ check that there is no regex match.
490 send STRING
492 Push STRING on the CLI connection. STRING will be terminated by
493 an end of line character (n).
494 logexpect
496 Reads the VSL and looks for records matching a given specification. It
497 will process records trying to match the first pattern, and when done,
498 will continue processing, trying to match the following pattern. If a
499 pattern isn't matched, the test will fail.
500 logexpect threads are declared this way:
502 logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
504 [vsl arguments] {
505 expect <skip> <vxid> <tag> <regex>
506 expect <skip> <vxid> <tag> <regex>
507 ...
508 } [-start|-wait]
509 And once declared, you can start them, or wait on them:
511 logexpect lNAME <-start|-wait>
513 With:
515 lNAME Name the logexpect thread, it must start with 'l'.
517 -v id Specify the varnish instance to use (most of the time, id=v1).
519 -g <session|request|vxid|raw
521 Decide how records are grouped, see -g in man varnishlog for
522 more information.
523 -d <0|1>
525 Start processing log records at the head of the log instead of
526 the tail.
527 -q query
529 Filter records using a query expression, see man vsl-query for
530 more information.
531 -start Start the logexpect thread in the background.
533 -wait Wait for the logexpect thread to finish
535 VSL arguments (similar to the varnishlog options):
537 -b|-c Process only backend/client records.
539 -C Use caseless regex
541 -i <taglist>
543 Include tags
544 -I <[taglist:]regex>
546 Include by regex
547 -T <seconds>
549 Transaction end timeout
550 And the arguments of the specifications lines are:
552 skip: [uint|*]
554 Max number of record to skip
555 vxid: [uint|*|=]
557 vxid to match
558 tag: [tagname|*|=]
560 Tag to match against
561 regex: regular expression to match against (optional)
563 For skip, vxid and tag, '*' matches anything, '=' expects the value of
565 the previous matched record.
566 process
568 Run a process with stdin+stdout on a pseudo-terminal and stderr on a
569 pipe.
570 Output from the pseudo-terminal is copied verbatim to ${pNAME_out}, and
572 the -log/-dump/-hexdump flags will also put it in the vtc-log.
573 The pseudo-terminal is not in ECHO mode, but if the programs run set it
575 to ECHO mode ("stty sane") any input sent to the process will also
576 appear in this stream because of the ECHO.
577 Output from the stderr-pipe is copied verbatim to ${pNAME_err}, and is
579 always included in the vtc_log.
580 process pNAME SPEC [-log] [-dump] [-hexdump] [-expect-exit N]
582 [-start] [-run] [-write STRING] [-writeln STRING] [-kill
583 STRING] [-stop] [-wait] [-close]
584 pNAME Name of the process. It must start with 'p'.
586 SPEC The command(s) to run in this process.
588 -hexdump
590 Log output with vtc_hexdump(). Must be before -start/-run.
591 -dump Log output with vtc_dump(). Must be before -start/-run.
593 -log Log output with VLU/vtc_log(). Must be before -start/-run.
595 -start Start the process.
597 -expect-exit N
599 Expect exit status N
600 -wait Wait for the process to finish.
602 -run Shorthand for -start -wait.
604 In most cases, if you just want to start a process and wait for
606 it to finish, you can use the shell command instead. The fol‐
607 lowing commands are equivalent:
608 shell "do --something"
610 process p1 "do --something" -run
612 However, you may use the the process variant to conveniently
614 collect the standard input and output without dealing with shell
615 redirections yourself. The shell command can also expect an
616 expression from either output, consider using it if you only
617 need to match one.
618 -kill STRING
620 Send a signal to the process. The argument can be either the
621 string "TERM", "INT", or "KILL" for SIGTERM, SIGINT or SIGKILL
622 signals, respectively, or a hyphen (-) followed by the signal
623 number.
624 If you need to use other signal names, you can use the kill(1)
626 command directly:
627 shell "kill -USR1 ${pNAME_pid}"
629 Note that SIGHUP usage is discouraged in test cases.
631 -stop Shorthand for -kill TERM.
633 -write STRING
635 Write a string to the process' stdin.
636 -writeln STRING
638 Same as -write followed by a newline (\n).
639 -writehex HEXSTRING
641 Same as -write but interpreted as hexadecimal bytes.
642 -need-bytes [+]NUMBER
644 Wait until at least NUMBER bytes have been received in total.
645 If '+' is prefixed, NUMBER new bytes must be received.
646 -expect-text LIN COL PAT
648 Wait for PAT to appear at LIN,COL on the virtual screen. Lines
649 and columns are numbered 1...N LIN==0 means "on any line" COL==0
650 means "anywhere on the line"
651 -close Alias for "-kill HUP"
653 -screen_dump
655 Dump the virtual screen into vtc_log
656 setenv
658 Set or change an environment variable:
659 setenv FOO "bar baz"
661 The above will set the environment variable $FOO to the value provided.
663 There is also an -ifunset argument which will only set the value if the
664 the environment variable does not already exist:
665 setenv -ifunset FOO quux
667 shell
669 NOTE: This command is available everywhere commands are given.
670 Pass the string given as argument to a shell. If you have multiple com‐
672 mands to run, you can use curly brackets to describe a multi-lines
673 script, eg:
674 shell {
676 echo begin
677 cat /etc/fstab
678 echo end
679 }
680 By default a zero exit code is expected, otherwise the vtc will fail.
682 Notice that the commandstring is prefixed with "exec 2>&1;" to combine
684 stderr and stdout back to the test process.
685 Optional arguments:
687 -err Expect non-zero exit code.
689 -exit N
691 Expect exit code N instead of zero.
692 -expect STRING
694 Expect string to be found in stdout+err.
695 -match REGEXP
697 Expect regexp to match the stdout+err output.
698 stream
700 (note: this section is at the top-level for easier navigation, but it's
701 part of the client/server specification)
702 Streams map roughly to a request in HTTP/2, a request is sent on stream
704 N, the response too, then the stream is discarded. The main exception
705 is the first stream, 0, that serves as coordinator.
706 Stream syntax follow the client/server one:
708 stream ID [SPEC] [ACTION]
710 ID is the HTTP/2 stream number, while SPEC describes what will be done
712 in that stream.
713 Note that, when parsing a stream action, if the entity isn't operating
715 in HTTP/2 mode, these spec is ran before:
716 txpri/rxpri # client/server
718 stream 0 {
719 txsettings
720 rxsettings
721 txsettings -ack
722 rxsettings
723 expect settings.ack == true
724 } -run
725 And HTTP/2 mode is then activated before parsing the specification.
727 Actions
729 -start Run the specification in a thread, giving back control immedi‐
730 ately.
731 -wait Wait for the started thread to finish running the spec.
733 -run equivalent to calling -start then -wait.
735 Specification
737 The specification of a stream follows the exact same rules as one for a
738 client or a server.
739 txreq, txresp, txcont, txpush
741 These four commands are about sending headers. txreq and txresp will
742 send HEADER frames; txcont will send CONTINUATION frames; txpush PUSH
743 frames. The only difference between txreq and txresp are the default
744 headers set by each of them.
745 -noadd Do not add default headers. Useful to avoid duplicates when
747 sending default headers using -hdr, -idxHdr and -litIdxHdr.
748 -status INT (txresp)
750 Set the :status pseudo-header.
751 -url STRING (txreq, txpush)
753 Set the :path pseudo-header.
754 -req STRING (txreq, txpush)
756 Set the :method pseudo-header.
757 -scheme STRING (txreq, txpush)
759 Set the :scheme pseudo-header.
760 -hdr STRING1 STRING2
762 Insert a header, STRING1 being the name, and STRING2 the value.
763 -idxHdr INT
765 Insert an indexed header, using INT as index.
766 -litIdxHdr inc|not|never INT huf|plain STRING
768 Insert an literal, indexed header. The first argument specify if
769 the header should be added to the table, shouldn't, or mustn't
770 be compressed if/when retransmitted.
771 INT is the idex of the header name to use.
773 The third argument informs about the Huffman encoding: yes (huf)
775 or no (plain).
776 The last term is the literal value of the header.
778 -litHdr inc|not|never huf|plain STRING1 huf|plain STRING2
780 Insert a literal header, with the same first argument as
781 -litIdxHdr.
782 The second and third terms tell what the name of the header is
784 and if it should be Huffman-encoded, while the last two do the
785 same regarding the value.
786 -body STRING (txreq, txresp)
788 Specify a body, effectively putting STRING into a DATA frame
789 after the HEADER frame is sent.
790 -bodylen INT (txreq, txresp)
792 Do the same thing as -body but generate an string of INT length
793 for you.
794 -nostrend (txreq, txresp)
796 Don't set the END_STREAM flag automatically, making the peer
797 expect a body after the headers.
798 -nohdrend
800 Don't set the END_HEADERS flag automatically, making the peer
801 expect more HEADER frames.
802 -dep INT (txreq, txresp)
804 Tell the peer that this content depends on the stream with the
805 INT id.
806 -ex (txreq, txresp)
808 Make the dependency exclusive (-dep is still needed).
809 -weight (txreq, txresp)
811 Set the weight for the dependency.
812 -promised INT (txpush)
814 The id of the promised stream.
815 -pad STRING / -padlen INT (txreq, txresp, txpush)
817 Add string as padding to the frame, either the one you provided
818 with -pad, or one that is generated for you, of length INT is
819 -padlen case.
820 txdata
822 By default, data frames are empty. The receiving end will know the
823 whole body has been delivered thanks to the END_STREAM flag set in the
824 last DATA frame, and txdata automatically set it.
825 -data STRING
827 Data to be embedded into the frame.
828 -datalen INT
830 Generate and INT-bytes long string to be sent in the frame.
831 -pad STRING / -padlen INT
833 Add string as padding to the frame, either the one you provided
834 with -pad, or one that is generated for you, of length INT is
835 -padlen case.
836 -nostrend
838 Don't set the END_STREAM flag, allowing to send more data on
839 this stream.
840 rxreq, rxresp
842 These are two convenience functions to receive headers and body of an
843 incoming request or response. The only difference is that rxreq can
844 only be by a server, and rxresp by a client.
845 rxhdrs
847 rxhdrs will expect one HEADER frame, then, depending on the arguments,
848 zero or more CONTINUATION frame.
849 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
851 seen.
852 -some INT
854 Retrieve INT - 1 CONTINUATION frames after the HEADER frame.
855 rxpush
857 This works like rxhdrs, expecting a PUSH frame and then zero or more
858 CONTINUATION frames.
859 -all Keep waiting for CONTINUATION frames until END_HEADERS flag is
861 seen.
862 -some INT
864 Retrieve INT - 1 CONTINUATION frames after the PUSH frame.
865 rxdata
867 Receiving data is done using the rxdata keywords and will retrieve one
868 DATA frame, if you wish to receive more, you can use these two conve‐
869 nience arguments:
870 -all keep waiting for DATA frame until one sets the END_STREAM flag
872 -some INT
874 retrieve INT DATA frames.
875 Receive a frame, any frame.
877 sendhex
879 Push bytes directly on the wire. sendhex takes exactly one argument: a
880 string describing the bytes, in hex notation, with possible whitespaces
881 between them. Here's an example:
882 sendhex "00 00 08 00 0900 8d"
884 rxgoaway
886 Receive a GOAWAY frame.
887 txgoaway
889 Possible options include:
890 -err STRING|INT
892 set the error code to explain the termination. The second argu‐
893 ment can be a integer or the string version of the error code as
894 found in rfc7540#7.
895 -laststream INT
897 the id of the "highest-numbered stream identifier for which the
898 sender of the GOAWAY frame might have taken some action on or
899 might yet take action on".
900 -debug specify the debug data, if any to append to the frame.
902 rxping
904 Receive a PING frame.
905 txping
907 Send PING frame.
908 -data STRING
910 specify the payload of the frame, with STRING being an 8-char
911 string.
912 -ack set the ACK flag.
914 rxprio
916 Receive a PRIORITY frame.
917 txprio
919 Send a PRIORITY frame
920 -stream INT
922 indicate the id of the stream the sender stream depends on.
923 -ex the dependency should be made exclusive (only this streams
925 depends on the parent stream).
926 -weight INT
928 an 8-bits integer is used to balance priority between streams
929 depending on the same streams.
930 rxrst
932 Receive a RST_STREAM frame.
933 txrst
935 Send a RST_STREAM frame. By default, txrst will send a 0 error code
936 (NO_ERROR).
937 -err STRING|INT
939 Sets the error code to be sent. The argument can be an integer
940 or a string describing the error, such as NO_ERROR, or CANCEL
941 (see rfc7540#11.4 for more strings).
942 rxsettings
944 Receive a SETTINGS frame.
945 txsettings
947 SETTINGS frames must be acknowledge, arguments are as follow (most of
948 them are from rfc7540#6.5.2):
949 -hdrtbl INT
951 headers table size
952 -push BOOL
954 whether push frames are accepted or not
955 -maxstreams INT
957 maximum concurrent streams allowed
958 -winsize INT
960 sender's initial window size
961 -framesize INT
963 largest frame size authorized
964 -hdrsize INT
966 maximum size of the header list authorized
967 -ack set the ack bit
969 rxwinup
971 Receive a WINDOW_UPDATE frame.
972 txwinup
974 Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the
975 connection (from stream 0) or of the stream (any other stream).
976 -size INT
978 give INT credits to the peer.
979 write_body STRING
981 Same as the write_body command for HTTP/1.
982 expect
984 expect in stream works as it does in client or server, except that the
985 elements compared will be different.
986 Most of these elements will be frame specific, meaning that the last
988 frame received on that stream must of the correct type.
989 Here the list of keywords you can look at.
991 syslog
993 Define and interact with syslog instances (for use with haproxy)
994 To define a syslog server, you'll use this syntax:
996 syslog SNAME
998 Arguments:
1000 SNAME Identify the syslog server with a string which must start with
1002 'S'.
1003 -level STRING
1005 Set the default syslog priority level used by any subsequent
1006 "recv" command. Any syslog dgram with a different level will be
1007 skipped by "recv" command. This default level value may be
1008 superseded by "recv" command if supplied as first argument:
1009 "recv <level>".
1010 -start Start the syslog server thread in the background.
1012 -repeat
1014 Instead of processing the specification only once, do it
1016 NUMBER times.
1017 -bind Bind the syslog socket to a local address.
1019 -wait Wait for that thread to terminate.
1021 -stop Stop the syslog server thread.
1023 varnish
1025 Define and interact with varnish instances.
1026 To define a Varnish server, you'll use this syntax:
1028 varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
1030 [-errvcl STRING STRING] [-jail STRING] [-proto PROXY]
1031 The first varnish vNAME invocation will start the varnishd master
1033 process in the background, waiting for the -start switch to actually
1034 start the child.
1035 Types used in the description below:
1037 PATTERN
1039 is a 'glob' style pattern (ie: fnmatch(3)) as used in shell
1040 filename expansion.
1041 Arguments:
1043 vNAME Identify the Varnish server with a string, it must starts with
1045 'v'.
1046 -arg STRING
1048 Pass an argument to varnishd, for example "-h simple_list".
1049 -vcl STRING
1051 Specify the VCL to load on this Varnish instance. You'll proba‐
1052 bly want to use multi-lines strings for this ({...}).
1053 -vcl+backend STRING
1055 Do the exact same thing as -vcl, but adds the definition block
1056 of known backends (ie. already defined).
1057 -errvcl STRING1 STRING2
1059 Load STRING2 as VCL, expecting it to fail, and Varnish to send
1060 an error string matching STRING2
1061 -jail STRING
1063 Look at man varnishd (-j) for more information.
1064 -proto PROXY
1066 Have Varnish use the proxy protocol. Note that PROXY here is the
1067 actual string.
1068 You can decide to start the Varnish instance and/or wait for several
1070 events:
1071 varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]
1073 -start Start the child process.
1075 -stop Stop the child process.
1077 -syntax
1079 Set the VCL syntax level for this command (default: 4.1)
1080 -wait Wait for that instance to terminate.
1082 -wait-running
1084 Wait for the Varnish child process to be started.
1085 -wait-stopped
1087 Wait for the Varnish child process to stop.
1088 -cleanup
1090 Once Varnish is stopped, clean everything after it. This is only
1091 used in very few tests and you should never need it.
1092 Once Varnish is started, you can talk to it (as you would through var‐
1094 nishadm) with these additional switches:
1095 varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
1097 [-clijson STRING] [-expect STRING OP NUMBER]
1098 -cli STRING|-cliok STRING|-clierr STATUS STRING|-cliexpect REGEXP
1100 STRING
1101 All four of these will send STRING to the CLI, the only differ‐
1102 ence is what they expect the result to be. -cli doesn't expect
1103 anything, -cliok expects 200, -clierr expects STATUS, and -cli‐
1104 expect expects the REGEXP to match the returned response.
1105 -clijson STRING
1107 Send STRING to the CLI, expect success (CLIS_OK/200) and check
1108 that the response is parsable JSON.
1109 -expect PATTERN OP NUMBER
1111 Look into the VSM and make sure the first VSC counter identified
1112 by PATTERN has a correct value. OP can be ==, >, >=, <, <=. For
1113 example:
1114 varnish v1 -expect SM?.s1.g_space > 1000000
1116 -expectexit NUMBER
1118 Expect varnishd to exit(3) with this value
1119 -vsc PATTERN
1121 Dump VSC counters matching PATTERN.
1122 -vsl_catchup
1124 Wait until the logging thread has idled to make sure that all
1125 the generated log is flushed
1126 varnishtest
1128 Alternate name for 'vtest', see above.
1129 vtest
1131 This should be the first command in your vtc as it will identify the
1132 test case with a short yet descriptive sentence. It takes exactly one
1133 argument, a string, eg:
1134 vtest "Check that vtest is actually a valid command"
1136 It will also print that string in the log.
1138
1140 This document has been written by Guillaume Quintard.
1141
1143 · varnishtest(1)
1144 · vmod_vtc(3)
1146
1148 This document is licensed under the same licence as Varnish itself. See
1149 LICENCE for details.
1150 · Copyright (c) 2006-2016 Varnish Software AS
1152 VTC(7)