1VTC(7) VTC(7)
2
3
4
6 VTC - Varnish Test Case Syntax
7
9 This document describes the syntax used by Varnish Test Cases files
10 (.vtc). A vtc file describe a scenario with different scripted
11 HTTP-talking entities, and generally one or more Varnish instances to
12 test.
13
15 A vtc file will be read word after word, with very little tokenization,
16 meaning a syntax error won't be detected until the test actually reach
17 the relevant action in the test.
18
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
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
1142 This document has been written by Guillaume Quintard.
1143
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)