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

HISTORY

1142       This document has been written by Guillaume Quintard.
1143

SEE ALSO

1145       · varnishtest(1)
1146
1147       · vmod_vtc(3)
1148
1150       This document is licensed under the same licence as Varnish itself. See
1151       LICENCE for details.
1152
1153       · Copyright (c) 2006-2016 Varnish Software AS
1154
1155
1156
1157
1158                                                                        VTC(7)
Impressum