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

HISTORY

1170       This document has been written by Guillaume Quintard.
1171

SEE ALSO

1173varnishtest(1)
1174
1175vmod_vtc(3)
1176
1178       This document is licensed under the same licence as Varnish itself. See
1179       LICENCE for details.
1180
1181       • Copyright (c) 2006-2016 Varnish Software AS
1182
1183
1184
1185
1186                                                                        VTC(7)
Impressum