1VTC(7)                                                                  VTC(7)
2
3
4

NAME

6       VTC - Varnish Test Case Syntax
7

OVERVIEW

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

PARSING

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
19       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
24   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
30   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
35   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

SYNTAX

42   barrier
43       NOTE: This command is available everywhere commands are given.
44
45       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
48       First, it's necessary to declare the barrier:
49
50          barrier bNAME TYPE NUMBER [-cyclic]
51
52       With the arguments being:
53
54       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
57       TYPE   it  can  be  "cond" (mutex) or "sock" (socket) and sets internal
58              behavior. If you don't need VCL synchronization, use cond.
59
60       NUMBER number of sync point needed to go through the barrier.
61
62       -cyclic
63              if present, the barrier will reset itself and be ready  for  an‐
64              other round once gotten through.
65
66       Then, to add a sync point:
67
68          barrier bNAME sync
69
70       This  will  block the parent thread until the number of sync points for
71       bNAME reaches the NUMBER given in the barrier declaration.
72
73       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
77          debug.barrier_sync("${bNAME_sock}");
78
79       This function returns 0 if everything went well and is  the  equivalent
80       of barrier bNAME sync at the VTC top-level.
81
82   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
88          client cNAME [...]
89          server sNAME [...]
90
91       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
94       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
98   Arguments
99       -start Start the thread in background, processing the last given speci‐
100              fication.
101
102       -wait  Block until the thread finishes.
103
104       -run (client only)
105              Equivalent to "-start -wait".
106
107       -repeat NUMBER
108              Instead of processing the specification only once, do it  NUMBER
109              times.
110
111       -keepalive
112              For repeat, do not open new connections but rather run all iter‐
113              ations in the same connection
114
115       -break (server only)
116              Stop the server.
117
118       -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
124       -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
129       -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
135              However, -dispatch is only allowed for the server name "s0".
136
137       -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
141       -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
145   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
150       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
157   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
163          client c1 {
164              txreq -url /foo \
165                    -hdr "bar: baz"
166
167              rxresp
168          } -run
169
170       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
174       chunked STRING
175              Send STRING as chunked encoding.
176
177       chunkedlen NUMBER
178              Do  as chunked except that the string will be generated for you,
179              with a length of NUMBER characters.
180
181       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
185       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
192              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
197                 expect req.http.x-num > 2
198
199              Here's the list of recognized strings, most should be obvious as
200              they either match VCL logic, or the txreq/txresp options:
201
202              • remote.ip
203
204              • remote.port
205
206              • remote.path
207
208              • req.method
209
210              • req.url
211
212              • req.proto
213
214              • resp.proto
215
216              • resp.status
217
218              • resp.reason
219
220              • resp.chunklen
221
222              • req.bodylen
223
224              • req.body
225
226              • resp.bodylen
227
228              • resp.body
229
230              • req.http.NAME
231
232              • resp.http.NAME
233
234       expect_close
235              Reads from the connection, expecting nothing to read but an EOF.
236
237       fatal|non_fatal
238              Control whether a failure of this entity should stop the test.
239
240       gunzip Gunzip the body in place.
241
242       recv NUMBER
243              Read NUMBER bytes from the connection.
244
245       rxchunk
246              Receive an HTTP chunk.
247
248       rxpri (server only)
249              Receive a preface. If valid set the server to HTTP/2, abort oth‐
250              erwise.
251
252       rxreq (server only)
253              Receive and parse a request's headers and body.
254
255       rxreqbody (server only)
256              Receive a request's body.
257
258       rxreqhdrs (server only)
259              Receive and parse a request's headers (but not the body).
260
261       rxresp [-no_obj] (client only)
262              Receive and parse a response's headers and body. If  -no_obj  is
263              present, only get the headers.
264
265       rxrespbody (client only)
266              Receive (part of) a response's body.
267
268       -max : max length of this receive, 0 for all
269
270       rxresphdrs (client only)
271              Receive and parse a response's headers.
272
273       send STRING
274              Push STRING on the connection.
275
276       send_n NUMBER STRING
277              Write STRING on the socket NUMBER times.
278
279       send_urgent STRING
280              Send string as TCP OOB urgent data. You will never need this.
281
282       sendhex STRING
283              Send  bytes as described by STRING. STRING should consist of hex
284              pairs possibly separated by whitespace or newlines. For example:
285              "0F EE a5    3df2".
286
287       settings -dectbl INT
288              Force internal HTTP/2 settings to certain values. Currently only
289              support setting the decoding table size.
290
291       shell  Same as for the top-level shell.
292
293       stream HTTP/2 introduces the concept of streams, and  these  come  with
294              their  own specification, and as it's quite big, have been moved
295              to their own chapter.
296
297       timeout NUMBER
298              Set the TCP timeout for this entity.
299
300       txpri (client only)
301              Send an HTTP/2 preface ("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n")  and
302              set client to HTTP/2.
303
304       txreq|txresp [...]
305              Send  a  minimal  request or response, but overload it if neces‐
306              sary.
307
308              txreq is client-specific and txresp is server-specific.
309
310              The only thing different between a request and a response, apart
311              from  who  can send them is that the first line (request line vs
312              status line), so all the options are prety much the same.
313
314              -method STRING (txreq only)
315                     What method to use (default: "GET").
316
317              -req STRING (txreq only)
318                     Alias for -method.
319
320              -url STRING (txreq only)
321                     What location to use (default "/").
322
323              -proto STRING
324                     What  protocol  use  in  the  status   line.    (default:
325                     "HTTP/1.1").
326
327              -status NUMBER (txresp only)
328                     What status code to return (default 200).
329
330              -reason STRING (txresp only)
331                     What message to put in the status line (default: "OK").
332
333              These  three  switches can appear in any order but must come be‐
334              fore the following ones.
335
336              -nohost
337                     Don't include a Host header in the request.
338
339              -nolen Don't include a Content-Length header.
340
341              -hdr STRING
342                     Add STRING as a  header,  it  must  follow  this  format:
343                     "name: value". It can be called multiple times.
344
345              -hdrlen STRING NUMBER
346                     Add STRING as a header with NUMBER bytes of content.
347
348              You can then use the arguments related to the body:
349
350              -body STRING
351                     Input STRING as body.
352
353              -bodyfrom FILE
354                     Same as -body but content is read from FILE.
355
356              -bodylen NUMBER
357                     Generate and input a body that is NUMBER bytes-long.
358
359              -gziplevel NUMBER
360                     Set  the gzip level (call it before any of the other gzip
361                     switches).
362
363              -gzipresidual NUMBER
364                     Add extra gzip bits. You should never need it.
365
366              -gzipbody STRING
367                     Gzip STRING and send it as body.
368
369              -gziplen NUMBER
370                     Combine -bodylen and  -gzipbody:  generate  a  string  of
371                     length NUMBER, gzip it and send as body.
372
373       write_body STRING
374              Write  the  body  of a request or a response to a file. By using
375              the shell command, higher-level checks on the body can  be  per‐
376              formed  (eg.  XML,  JSON,  ...) provided that such checks can be
377              delegated to an external program.
378
379   delay
380       NOTE: This command is available everywhere commands are given.
381
382       Sleep for the number of seconds specified in the argument.  The  number
383       can include a fractional part, e.g. 1.5.
384
385   err_shell
386       NOTICE: err_shell is deprecated, use shell -err -expect instead.
387
388       This  is very similar to the the shell command, except it takes a first
389       string as argument before the command:
390
391          err_shell "foo" "echo foo"
392
393       err_shell expect the shell command to fail  AND  stdout  to  match  the
394       string, failing the test case otherwise.
395
396   feature
397       Test  that  the  required feature(s) for a test are available, and skip
398       the test otherwise; or change the interpretation of the test, as  docu‐
399       mented below. feature takes any number of arguments from this list:
400
401       SO_RCVTIMEO_WORKS
402              The SO_RCVTIMEO socket option is working
403
404       64bit  The environment is 64 bits
405
406       ipv4   127.0.0.1 work
407
408       ipv6   [::1] work
409
410       dns    DNS lookups are working
411
412       topbuild
413              The test has been started with '-i'
414
415       root   The test has been invoked by the root user
416
417       user_varnish
418              The varnish user is present
419
420       user_vcache
421              The vcache user is present
422
423       group_varnish
424              The varnish group is present
425
426       cmd <command-line>
427              A command line that should execute with a zero exit status
428
429       ignore_unknown_macro
430              Do  not fail the test if a string of the form ${...} is not rec‐
431              ognized as a macro.
432
433       persistent_storage
434              Varnish was built with the deprecated persistent storage.
435
436       Be careful with ignore_unknown_macro, because it may cause a test  with
437       a  misspelled  macro  to  fail silently. You should only need it if you
438       must run a test with strings of the form "${...}".
439
440   haproxy
441       Define and interact with haproxy instances.
442
443       To define a haproxy server, you'll use this syntax:
444
445          haproxy hNAME -conf-OK CONFIG
446          haproxy hNAME -conf-BAD ERROR CONFIG
447          haproxy hNAME [-D] [-W] [-arg STRING] [-conf[+vcl] STRING]
448
449       The first haproxy  hNAME  invocation  will  start  the  haproxy  master
450       process  in  the  background, waiting for the -start switch to actually
451       start the child.
452
453       Arguments:
454
455       hNAME  Identify the HAProxy server with a string, it must  starts  with
456              'h'.
457
458       -conf-OK CONFIG
459
460              Run haproxy in '-c' mode to check config is OK
461                     stdout/stderr   should  contain  'Configuration  file  is
462                     valid' The exit code should be 0.
463
464       -conf-BAD ERROR CONFIG
465
466              Run haproxy in '-c' mode to check config is BAD.
467                     "ERROR"  should  be  part  of  the  diagnostics  on  std‐
468                     out/stderr.  The exit code should be 1.
469
470       -D     Run HAproxy in daemon mode.  If not given '-d' mode used.
471
472       -W     Enable HAproxy in Worker mode.
473
474       -S     Enable HAproxy Master CLI in Worker mode
475
476       -arg STRING
477              Pass an argument to haproxy, for example "-h simple_list".
478
479       -cli STRING
480              Specify the spec to be run by the command line interface (CLI).
481
482       -mcli STRING
483              Specify  the  spec to be run by the command line interface (CLI)
484              of the Master process.
485
486       -conf STRING
487              Specify the configuration to be loaded by this HAProxy instance.
488
489       -conf+backend STRING
490
491              Specify the configuration to be loaded by this HAProxy instance,
492                     all server instances will be automatically appended
493
494       -start Start this HAProxy instance.
495
496       -wait  Stop this HAProxy instance.
497
498       -expectexit NUMBER
499              Expect haproxy to exit(3) with this value
500
501   haproxy CLI Specification
502       expect OP STRING
503              Regex match the CLI reception buffer with STRING if OP is ~  or,
504              on the contraty, if OP is !~ check that there is no regex match.
505
506       send STRING
507              Push  STRING on the CLI connection. STRING will be terminated by
508              an end of line character (n).
509
510   logexpect
511       Reads the VSL and looks for records matching a given specification.  It
512       will  process records trying to match the first pattern, and when done,
513       will continue processing, trying to match the following pattern.  If  a
514       pattern isn't matched, the test will fail.
515
516       logexpect threads are declared this way:
517
518          logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
519                  [vsl arguments] {
520                          expect <skip> <vxid> <tag> <regex>
521                          expect <skip> <vxid> <tag> <regex>
522                          fail add <vxid> <tag> <regex>
523                          fail clear
524                          ...
525                  } [-start|-wait]
526
527       And once declared, you can start them, or wait on them:
528
529          logexpect lNAME <-start|-wait>
530
531       With:
532
533       lNAME  Name the logexpect thread, it must start with 'l'.
534
535       -v id  Specify the varnish instance to use (most of the time, id=v1).
536
537       -g <session|request|vxid|raw
538              Decide  how  records  are  grouped, see -g in man varnishlog for
539              more information.
540
541       -d <0|1>
542              Start processing log records at the head of the log  instead  of
543              the tail.
544
545       -q query
546              Filter  records  using a query expression, see man vsl-query for
547              more information. Multiple -q options are not supported.
548
549       -m     Also emit log records for misses (only for debugging)
550
551       -err   Invert the meaning of success. Usually called once to expect the
552              logexpect to fail
553
554       -start Start the logexpect thread in the background.
555
556       -wait  Wait for the logexpect thread to finish
557
558       VSL arguments (similar to the varnishlog options):
559
560       -C     Use caseless regex
561
562       -i <taglist>
563              Include tags
564
565       -I <[taglist:]regex>
566              Include by regex
567
568       -T <seconds>
569              Transaction end timeout
570
571       expect specification:
572
573       skip: [uint|*|?]
574              Max number of record to skip
575
576       vxid: [uint|*|=]
577              vxid to match
578
579       tag: [tagname|*|=]
580              Tag to match against
581
582       regex: regular expression to match against (optional)
583
584       For  skip, vxid and tag, '*' matches anything, '=' expects the value of
585       the previous matched record. The '?' marker is equivalent to zero,  ex‐
586       pecting  a  match on the next record. The difference is that '?' can be
587       used when the order of individual consecutive logs is  not  determinis‐
588       tic.  In  other words, lines from a block of alternatives marked by '?'
589       can be matched in any order, but all need to match eventually.
590
591       fail specification:
592
593       add: Add to the fail list
594          Arguments are equivalent to expect, except for skip missing
595
596       clear: Clear the fail list
597
598       Any number of fail specifications can be active during execution  of  a
599       logexpect. All active fail specifications are matched against every log
600       line and, if any match, the logexpect fails immediately.
601
602       For a logexpect to end successfully, there must be no specs on the fail
603       list, so logexpects should always end with
604          expect <skip> <vxid> <tag> <termination-condition> fail clear
605
606       XXX can we come up with a better solution which is still safe?
607
608   loop
609       loop NUMBER STRING
610              Process STRING as a specification, NUMBER times.
611
612       This works inside all specification strings
613
614   process
615       Run  a  process  with stdin+stdout on a pseudo-terminal and stderr on a
616       pipe.
617
618       Output from the pseudo-terminal is copied verbatim to ${pNAME_out}, and
619       the -log/-dump/-hexdump flags will also put it in the vtc-log.
620
621       The pseudo-terminal is not in ECHO mode, but if the programs run set it
622       to ECHO mode ("stty sane") any input sent to the process will also  ap‐
623       pear in this stream because of the ECHO.
624
625       Output  from the stderr-pipe is copied verbatim to ${pNAME_err}, and is
626       always included in the vtc_log.
627
628          process pNAME SPEC [-log] [-dump] [-hexdump] [-expect-exit N]
629                 [-start] [-run]  [-write  STRING]  [-writeln  STRING]  [-kill
630                 STRING] [-stop] [-wait] [-close]
631
632       pNAME  Name of the process. It must start with 'p'.
633
634       SPEC   The command(s) to run in this process.
635
636       -hexdump
637              Log output with vtc_hexdump(). Must be before -start/-run.
638
639       -dump  Log output with vtc_dump(). Must be before -start/-run.
640
641       -log   Log output with VLU/vtc_log(). Must be before -start/-run.
642
643       -start Start the process.
644
645       -expect-exit N
646              Expect exit status N
647
648       -wait  Wait for the process to finish.
649
650       -run   Shorthand for -start -wait.
651
652              In  most cases, if you just want to start a process and wait for
653              it to finish, you can use the shell command instead.   The  fol‐
654              lowing commands are equivalent:
655
656                 shell "do --something"
657
658                 process p1 "do --something" -run
659
660              However,  you  may  use  the the process variant to conveniently
661              collect the standard input and output without dealing with shell
662              redirections  yourself. The shell command can also expect an ex‐
663              pression from either output, consider using it if you only  need
664              to match one.
665
666       -kill STRING
667              Send  a  signal  to  the process. The argument can be either the
668              string "TERM", "INT", or "KILL" for SIGTERM, SIGINT  or  SIGKILL
669              signals,  respectively,  or  a hyphen (-) followed by the signal
670              number.
671
672              If you need to use other signal names, you can use  the  kill(1)
673              command directly:
674
675                 shell "kill -USR1 ${pNAME_pid}"
676
677              Note that SIGHUP usage is discouraged in test cases.
678
679       -stop  Shorthand for -kill TERM.
680
681       -write STRING
682              Write a string to the process' stdin.
683
684       -writeln STRING
685              Same as -write followed by a newline (\n).
686
687       -writehex HEXSTRING
688              Same as -write but interpreted as hexadecimal bytes.
689
690       -need-bytes [+]NUMBER
691              Wait  until  at  least NUMBER bytes have been received in total.
692              If '+' is prefixed, NUMBER new bytes must be received.
693
694       -expect-text LIN COL PAT
695              Wait for PAT to appear at LIN,COL on the virtual screen.   Lines
696              and columns are numbered 1...N LIN==0 means "on any line" COL==0
697              means "anywhere on the line"
698
699       -close Alias for "-kill HUP"
700
701       -screen_dump
702              Dump the virtual screen into vtc_log
703
704   setenv
705       Set or change an environment variable:
706
707          setenv FOO "bar baz"
708
709       The above will set the environment variable $FOO to the value provided.
710       There is also an -ifunset argument which will only set the value if the
711       the environment variable does not already exist:
712
713          setenv -ifunset FOO quux
714
715   shell
716       NOTE: This command is available everywhere commands are given.
717
718       Pass the string given as argument to a shell. If you have multiple com‐
719       mands  to  run,  you  can  use curly brackets to describe a multi-lines
720       script, eg:
721
722          shell {
723                  echo begin
724                  cat /etc/fstab
725                  echo end
726          }
727
728       By default a zero exit code is expected, otherwise the vtc will fail.
729
730       Notice that the commandstring is prefixed with "exec 2>&1;" to  combine
731       stderr and stdout back to the test process.
732
733       Optional arguments:
734
735       -err   Expect non-zero exit code.
736
737       -exit N
738              Expect exit code N instead of zero.
739
740       -expect STRING
741              Expect string to be found in stdout+err.
742
743       -match REGEXP
744              Expect regexp to match the stdout+err output.
745
746   stream
747       (note: this section is at the top-level for easier navigation, but it's
748       part of the client/server specification)
749
750       Streams map roughly to a request in HTTP/2, a request is sent on stream
751       N,  the  response too, then the stream is discarded. The main exception
752       is the first stream, 0, that serves as coordinator.
753
754       Stream syntax follow the client/server one:
755
756          stream ID [SPEC] [ACTION]
757
758       ID is the HTTP/2 stream number, while SPEC describes what will be  done
759       in that stream.
760
761       Note  that, when parsing a stream action, if the entity isn't operating
762       in HTTP/2 mode, these spec is ran before:
763
764          txpri/rxpri # client/server
765          stream 0 {
766              txsettings
767              rxsettings
768              txsettings -ack
769              rxsettings
770              expect settings.ack == true
771          } -run
772
773       And HTTP/2 mode is then activated before parsing the specification.
774
775   Actions
776       -start Run the specification in a thread, giving back  control  immedi‐
777              ately.
778
779       -wait  Wait for the started thread to finish running the spec.
780
781       -run   equivalent to calling -start then -wait.
782
783   Specification
784       The specification of a stream follows the exact same rules as one for a
785       client or a server.
786
787   txreq, txresp, txcont, txpush
788       These four commands are about sending headers. txreq  and  txresp  will
789       send  HEADER  frames; txcont will send CONTINUATION frames; txpush PUSH
790       frames.  The only difference between txreq and txresp are  the  default
791       headers set by each of them.
792
793       -noadd Do  not  add  default  headers.  Useful to avoid duplicates when
794              sending default headers using -hdr, -idxHdr and -litIdxHdr.
795
796       -status INT (txresp)
797              Set the :status pseudo-header.
798
799       -url STRING (txreq, txpush)
800              Set the :path pseudo-header.
801
802       -method STRING (txreq, txpush)
803              Set the :method pseudo-header.
804
805       -req STRING (txreq, txpush)
806              Alias for -method.
807
808       -scheme STRING (txreq, txpush)
809              Set the :scheme pseudo-header.
810
811       -hdr STRING1 STRING2
812              Insert a header, STRING1 being the name, and STRING2 the value.
813
814       -idxHdr INT
815              Insert an indexed header, using INT as index.
816
817       -litIdxHdr inc|not|never INT huf|plain STRING
818              Insert an literal, indexed header. The first argument specify if
819              the  header  should be added to the table, shouldn't, or mustn't
820              be compressed if/when retransmitted.
821
822              INT is the idex of the header name to use.
823
824              The third argument informs about the Huffman encoding: yes (huf)
825              or no (plain).
826
827              The last term is the literal value of the header.
828
829       -litHdr inc|not|never huf|plain STRING1 huf|plain STRING2
830              Insert  a  literal  header,  with  the  same  first  argument as
831              -litIdxHdr.
832
833              The second and third terms tell what the name of the  header  is
834              and  if  it should be Huffman-encoded, while the last two do the
835              same regarding the value.
836
837       -body STRING (txreq, txresp)
838              Specify a body, effectively putting STRING into a DATA frame af‐
839              ter the HEADER frame is sent.
840
841       -bodyfrom FILE (txreq, txresp)
842              Same as -body but content is read from FILE.
843
844       -bodylen INT (txreq, txresp)
845              Do  the  same thing as -body but generate a string of INT length
846              for you.
847
848       -gzipbody STRING (txreq, txresp)
849              Gzip STRING and send it as body.
850
851       -gziplen NUMBER (txreq, txresp)
852              Combine -bodylen and -gzipbody: generate a string of length NUM‐
853              BER, gzip it and send as body.
854
855       -nostrend (txreq, txresp)
856              Don't set the END_STREAM flag automatically, making the peer ex‐
857              pect a body after the headers.
858
859       -nohdrend
860              Don't set the END_HEADERS flag automatically,  making  the  peer
861              expect more HEADER frames.
862
863       -dep INT (txreq, txresp)
864              Tell  the  peer that this content depends on the stream with the
865              INT id.
866
867       -ex (txreq, txresp)
868              Make the dependency exclusive (-dep is still needed).
869
870       -weight (txreq, txresp)
871              Set the weight for the dependency.
872
873       -promised INT (txpush)
874              The id of the promised stream.
875
876       -pad STRING / -padlen INT (txreq, txresp, txpush)
877              Add string as padding to the frame, either the one you  provided
878              with  -pad,  or  one that is generated for you, of length INT is
879              -padlen case.
880
881   txdata
882       By default, data frames are empty. The  receiving  end  will  know  the
883       whole  body has been delivered thanks to the END_STREAM flag set in the
884       last DATA frame, and txdata automatically set it.
885
886       -data STRING
887              Data to be embedded into the frame.
888
889       -datalen INT
890              Generate and INT-bytes long string to be sent in the frame.
891
892       -pad STRING / -padlen INT
893              Add string as padding to the frame, either the one you  provided
894              with  -pad,  or  one that is generated for you, of length INT is
895              -padlen case.
896
897       -nostrend
898              Don't set the END_STREAM flag, allowing to  send  more  data  on
899              this stream.
900
901   rxreq, rxresp
902       These  are  two convenience functions to receive headers and body of an
903       incoming request or response. The only difference  is  that  rxreq  can
904       only be by a server, and rxresp by a client.
905
906   rxhdrs
907       rxhdrs  will expect one HEADER frame, then, depending on the arguments,
908       zero or more CONTINUATION frame.
909
910       -all   Keep waiting for CONTINUATION frames until END_HEADERS  flag  is
911              seen.
912
913       -some INT
914              Retrieve INT - 1 CONTINUATION frames after the HEADER frame.
915
916   rxpush
917       This  works  like  rxhdrs, expecting a PUSH frame and then zero or more
918       CONTINUATION frames.
919
920       -all   Keep waiting for CONTINUATION frames until END_HEADERS  flag  is
921              seen.
922
923       -some INT
924              Retrieve INT - 1 CONTINUATION frames after the PUSH frame.
925
926   rxdata
927       Receiving  data is done using the rxdata keywords and will retrieve one
928       DATA frame, if you wish to receive more, you can use these  two  conve‐
929       nience arguments:
930
931       -all   keep waiting for DATA frame until one sets the END_STREAM flag
932
933       -some INT
934              retrieve INT DATA frames.
935
936       Receive a frame, any frame.
937
938   sendhex
939       Push  bytes directly on the wire. sendhex takes exactly one argument: a
940       string describing the bytes, in hex notation, with possible whitespaces
941       between them. Here's an example:
942
943          sendhex "00 00 08 00 0900       8d"
944
945   rxgoaway
946       Receive a GOAWAY frame.
947
948   txgoaway
949       Possible options include:
950
951       -err STRING|INT
952              set  the error code to explain the termination. The second argu‐
953              ment can be a integer or the string version of the error code as
954              found in rfc7540#7.
955
956       -laststream INT
957              the  id of the "highest-numbered stream identifier for which the
958              sender of the GOAWAY frame might have taken some  action  on  or
959              might yet take action on".
960
961       -debug specify the debug data, if any to append to the frame.
962
963   gunzip
964       Same as the gunzip command for HTTP/1.
965
966   rxping
967       Receive a PING frame.
968
969   txping
970       Send PING frame.
971
972       -data STRING
973              specify  the  payload  of the frame, with STRING being an 8-char
974              string.
975
976       -ack   set the ACK flag.
977
978   rxprio
979       Receive a PRIORITY frame.
980
981   txprio
982       Send a PRIORITY frame
983
984       -stream INT
985              indicate the id of the stream the sender stream depends on.
986
987       -ex    the dependency should be made exclusive (only this  streams  de‐
988              pends on the parent stream).
989
990       -weight INT
991              an  8-bits  integer  is used to balance priority between streams
992              depending on the same streams.
993
994   rxrst
995       Receive a RST_STREAM frame.
996
997   txrst
998       Send a RST_STREAM frame. By default, txrst will send  a  0  error  code
999       (NO_ERROR).
1000
1001       -err STRING|INT
1002              Sets  the  error code to be sent. The argument can be an integer
1003              or a string describing the error, such as  NO_ERROR,  or  CANCEL
1004              (see rfc7540#11.4 for more strings).
1005
1006   rxsettings
1007       Receive a SETTINGS frame.
1008
1009   txsettings
1010       SETTINGS  frames  must be acknowledge, arguments are as follow (most of
1011       them are from  rfc7540#6.5.2):
1012
1013       -hdrtbl INT
1014              headers table size
1015
1016       -push BOOL
1017              whether push frames are accepted or not
1018
1019       -maxstreams INT
1020              maximum concurrent streams allowed
1021
1022       -winsize INT
1023              sender's initial window size
1024
1025       -framesize INT
1026              largest frame size authorized
1027
1028       -hdrsize INT
1029              maximum size of the header list authorized
1030
1031       -ack   set the ack bit
1032
1033   rxwinup
1034       Receive a WINDOW_UPDATE frame.
1035
1036   txwinup
1037       Transmit a WINDOW_UPDATE frame, increasing the amount of credit of  the
1038       connection (from stream 0) or of the stream (any other stream).
1039
1040       -size INT
1041              give INT credits to the peer.
1042
1043       write_body STRING
1044              Same as the write_body command for HTTP/1.
1045
1046   expect
1047       expect  in stream works as it does in client or server, except that the
1048       elements compared will be different.
1049
1050       Most of these elements will be frame specific, meaning  that  the  last
1051       frame received on that stream must of the correct type.
1052
1053       Here the list of keywords you can look at.
1054
1055   syslog
1056       Define and interact with syslog instances (for use with haproxy)
1057
1058       To define a syslog server, you'll use this syntax:
1059
1060          syslog SNAME
1061
1062       Arguments:
1063
1064       SNAME  Identify  the  syslog server with a string which must start with
1065              'S'.
1066
1067       -level STRING
1068              Set the default syslog priority level  used  by  any  subsequent
1069              "recv" command.  Any syslog dgram with a different level will be
1070              skipped by "recv" command. This default level value may  be  su‐
1071              perseded  by "recv" command if supplied as first argument: "recv
1072              <level>".
1073
1074       -start Start the syslog server thread in the background.
1075
1076       -repeat
1077
1078              Instead of processing the specification only once, do it
1079                     NUMBER times.
1080
1081       -bind  Bind the syslog socket to a local address.
1082
1083       -wait  Wait for that thread to terminate.
1084
1085       -stop  Stop the syslog server thread.
1086
1087   varnish
1088       Define and interact with varnish instances.
1089
1090       To define a Varnish server, you'll use this syntax:
1091
1092          varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
1093                  [-errvcl STRING STRING] [-jail STRING] [-proto PROXY]
1094
1095       The first varnish vNAME  invocation  will  start  the  varnishd  master
1096       process  in  the  background, waiting for the -start switch to actually
1097       start the child.
1098
1099       Types used in the description below:
1100
1101       PATTERN
1102              is a 'glob' style pattern (ie:  fnmatch(3))  as  used  in  shell
1103              filename expansion.
1104
1105       Arguments:
1106
1107       vNAME  Identify  the  Varnish server with a string, it must starts with
1108              'v'.
1109
1110       -arg STRING
1111              Pass an argument to varnishd, for example "-h simple_list".
1112
1113       -vcl STRING
1114              Specify the VCL to load on this Varnish instance. You'll  proba‐
1115              bly want to use multi-lines strings for this ({...}).
1116
1117       -vcl+backend STRING
1118              Do  the  exact same thing as -vcl, but adds the definition block
1119              of known backends (ie. already defined).
1120
1121       -errvcl STRING1 STRING2
1122              Load STRING2 as VCL, expecting it to fail, and Varnish  to  send
1123              an error string matching STRING2
1124
1125       -jail STRING
1126              Look at man varnishd (-j) for more information.
1127
1128       -proto PROXY
1129              Have Varnish use the proxy protocol. Note that PROXY here is the
1130              actual string.
1131
1132       You can decide to start the Varnish instance and/or  wait  for  several
1133       events:
1134
1135          varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]
1136
1137       -start Start the child process.
1138
1139              Once  successfully  started,  the following macros are available
1140              for the default listen address: ${vNAME_addr}, ${vNAME_port} and
1141              ${vNAME_sock}.  Additional  macros  are available, including the
1142              listen address name for each address vNAME listens to, like  for
1143              example: ${vNAME_a0_addr}.
1144
1145       -stop  Stop the child process.
1146
1147       -syntax
1148              Set the VCL syntax level for this command (default: 4.1)
1149
1150       -wait  Wait for that instance to terminate.
1151
1152       -wait-running
1153              Wait for the Varnish child process to be started.
1154
1155       -wait-stopped
1156              Wait for the Varnish child process to stop.
1157
1158       -cleanup
1159              Once Varnish is stopped, clean everything after it. This is only
1160              used in very few tests and you should never need it.
1161
1162       -expectexit NUMBER
1163              Expect varnishd to exit(3) with this value
1164
1165       Once Varnish is started, you can talk to it (as you would through  var‐
1166       nishadm) with these additional switches:
1167
1168          varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
1169                        [-clijson STRING]
1170
1171       -cli   STRING|-cliok  STRING|-clierr  STATUS  STRING|-cliexpect  REGEXP
1172       STRING
1173              All four of these will send STRING to the CLI, the only  differ‐
1174              ence  is  what they expect the result to be. -cli doesn't expect
1175              anything, -cliok expects 200, -clierr expects STATUS, and  -cli‐
1176              expect expects the REGEXP to match the returned response.
1177
1178       -clijson STRING
1179              Send  STRING  to the CLI, expect success (CLIS_OK/200) and check
1180              that the response is parsable JSON.
1181
1182       It is also possible to interact with its shared memory  (as  you  would
1183       through tools like varnishstat) with additional switches:
1184
1185       -expect !PATTERN|PATTERN OP NUMBER|PATTERN OP PATTERN
1186              Look into the VSM and make sure the first VSC counter identified
1187              by PATTERN has a correct value. OP can be ==, >, >=, <, <=.  For
1188              example:
1189
1190                 varnish v1 -expect SM?.s1.g_space > 1000000
1191                 varnish v1 -expect cache_hit >= cache_hit_grace
1192
1193              In the ! form the test fails if a counter matches PATTERN.
1194
1195              The MAIN. namespace can be omitted from PATTERN.
1196
1197              The test takes up to 5 seconds before timing out.
1198
1199       -vsc PATTERN
1200              Dump VSC counters matching PATTERN.
1201
1202       -vsl_catchup
1203              Wait  until  the  logging thread has idled to make sure that all
1204              the generated log is flushed
1205
1206   varnishtest
1207       Alternate name for 'vtest', see above.
1208
1209   vtest
1210       This should be the first command in your vtc as it  will  identify  the
1211       test  case  with a short yet descriptive sentence. It takes exactly one
1212       argument, a string, eg:
1213
1214          vtest "Check that vtest is actually a valid command"
1215
1216       It will also print that string in the log.
1217

HISTORY

1219       This document has been written by Guillaume Quintard.
1220

SEE ALSO

1222varnishtest(1)
1223
1224vmod_vtc(3)
1225
1227       This document is licensed under the same licence as Varnish itself. See
1228       LICENCE for details.
1229
1230       • Copyright (c) 2006-2016 Varnish Software AS
1231
1232
1233
1234
1235                                                                        VTC(7)
Impressum