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

MACROS

42       When a string is processed, macro expansion is performed. Macros are in
43       the form ${<name>[,<args>...]}, they have a name  followed  by  an  op‐
44       tional  comma- or space-separated list of arguments. Leading and trail‐
45       ing spaces are ignored.
46
47       The macros ${foo,bar,baz} and ${ foo bar baz } are  equivalent.  If  an
48       argument  contains a space or a comma, arguments can be quoted. For ex‐
49       ample the macro ${foo,"bar,baz"} gives  one  argument  bar,baz  to  the
50       macro called foo.
51
52       Unless  documented  otherwise,  all macros are simple macros that don't
53       take arguments.
54
55   Built-in macros
56       ${bad_backend}
57              A socket address that will reliably never accept connections.
58
59       ${bad_ip}
60              An unlikely IPv4 address.
61
62       ${date}
63              The current date and time formatted for HTTP.
64
65       ${listen_addr}
66              The default listen address various components use, by default  a
67              random port on localhost.
68
69       ${localhost}
70              The first IP address that resolves to "localhost".
71
72       ${pwd} The working directory from which varnishtest was executed.
73
74       ${string,<action>[,<args>...]}
75              The  string  macro  is  the  entry point for text generation, it
76              takes a specialized action with each its own set of arguments.
77
78       ${string,repeat,<uint>,<str>}
79              Repeat uint times the string str.
80
81       ${testdir}
82              The directory containing the VTC script of the ongoing test case
83              execution.
84
85       ${tmpdir}
86              The dedicated working directory for the ongoing test case execu‐
87              tion, which happens to also be the  current  working  directory.
88              Useful when an absolute path to the working directory is needed.
89
90       ${topbuild}
91              Only  present when the -i option is used, to work on Varnish it‐
92              self instead of a regular installation.
93

SYNTAX

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

HISTORY

1449       This document has been written by Guillaume Quintard.
1450

SEE ALSO

1452varnishtest(1)
1453
1454vmod_vtc(3)
1455
1457       This document is licensed under the same licence as Varnish itself. See
1458       LICENCE for details.
1459
1460       • Copyright (c) 2006-2016 Varnish Software AS
1461
1462
1463
1464
1465                                                                        VTC(7)
Impressum