7
This document describes the syntax used by Varnish Test Cases files (.vtc). A vtc file describe a scenario with different scripted HTTP-talking entities, and generally one or more Varnish instances to test.
A vtc file will be read word after word, with very little tokenization, meaning a syntax error won’t be detected until the test actually reach the relevant action in the test.
A parsing error will most of the time result in an assert being triggered. If this happens, please refer yourself to the related source file and line number. However, this guide should help you avoid the most common mistakes.
The parser splits words by detecting whitespace characters and a string is a word, or a series of words on the same line enclosed by double-quotes (“…”), or, for multi-line strings, enclosed in curly brackets ({…}).
The leading whitespaces of lines are ignored. Empty lines (or ones consisting only of whitespaces) are ignored too, as are the lines starting with “#” that are comments.
Test files take at most one command per line, with the first word of the line being the command and the following ones being its arguments. To continue over to a new line without breaking the argument string, you can escape the newline character (\n) with a backslash (\).
NOTE: This command is available everywhere commands are given.
Barriers allows you to synchronize different threads to make sure events occur in the right order. It’s even possible to use them in VCL.
First, it’s necessary to declare the barrier:
barrier bNAME TYPE NUMBER [-cyclic]
With the arguments being:
this is the name of the barrier, used to identify it when you’ll create sync points. It must start with ‘b’.
it can be “cond” (mutex) or “sock” (socket) and sets internal behavior. If you don’t need VCL synchronization, use cond.
number of sync point needed to go through the barrier.
if present, the barrier will reset itself and be ready for another round once gotten through.
Then, to add a sync point:
barrier bNAME sync
This will block the parent thread until the number of sync points for bNAME reaches the NUMBER given in the barrier declaration.
If you wish to synchronize the VCL, you need to declare a “sock” barrier. This will emit a macro definition named “bNAME_sock” that you can use in VCL (after importing the debug vmod):
debug.barrier_sync("${bNAME_sock}");
This function returns 0 if everything went well and is the equivalent of barrier bNAME sync at the VTC top-level.
Client and server threads are fake HTTP entities used to test your Varnish and VCL. They take any number of arguments, and the one that are not recognized, assuming they don’t start with ‘-‘, are treated as specifications, laying out the actions to undertake:
client cNAME [...] server sNAME [...]
Clients and server are identified by a string that’s the first argument, clients’ names start with ‘c’ and servers’ names start with ‘s’.
As the client and server commands share a good deal of arguments and specification actions, they are grouped in this single section, specific items will be explicitly marked as such.
Start the thread in background, processing the last given specification.
Block until the thread finishes.
Equivalent to “-start -wait”.
Instead of processing the specification only once, do it NUMBER times.
For repeat, do not open new connections but rather run all iterations in the same connection
Stop the server.
Dictate the listening socket for the server. STRING is of the form “IP PORT”, or “/PATH/TO/SOCKET” for a Unix domain socket. In the latter case, the path must begin with ‘/’, and the server must be able to create it.
Indicate the server to connect to. STRING is also of the form “IP PORT”, or “/PATH/TO/SOCKET”. As with “server -listen”, a Unix domain socket is recognized when STRING begins with a ‘/’.
Normally, to keep things simple, server threads only handle one connection at a time, but the -dispatch switch allows to accept any number of connection and handle them following the given spec.
However, -dispatch is only allowed for the server name “s0”.
Use the PROXY protocol version 1 for this connection. STRING is of the form “CLIENTIP:PORT SERVERIP:PORT”.
Use the PROXY protocol version 2 for this connection. STRING is of the form “CLIENTIP:PORT SERVERIP:PORT”.
To make things easier in the general case, clients will connect by default to a Varnish server called v1. To connect to a different Varnish server, use ‘-connect ${vNAME_sock}’.
The -vcl+backend switch of the varnish command will add all the declared servers as backends. Be careful though, servers will by default listen to the 127.0.0.1 IP and will pick a random port, and publish 3 macros: sNAME_addr, sNAME_port and sNAME_sock, but only once they are started. For ‘varnish -vcl+backend’ to create the vcl with the correct values, the server must be started first.
It’s a string, either double-quoted “like this”, but most of the time enclosed in curly brackets, allowing multilining. Write a command per line in it, empty line are ignored, and long line can be wrapped by using a backslash. For example:
client c1 {
txreq -url /foo \
-hdr "bar: baz"
rxresp
} -run
Close the current connection, if any, and accept a new one. Note that this new connection is HTTP/1.x.
Send STRING as chunked encoding.
Do as chunked except that the string will be generated for you, with a length of NUMBER characters.
Close the connection. Note that if operating in HTTP/2 mode no extra (GOAWAY) frame is sent, it’s simply a TCP close.
Test if “STRING1 OP STRING2” is true, and if not, fails the test. OP can be ==, <, <=, >, >= when STRING1 and STRING2 represent numbers in which case it’s an order operator. If STRING1 and STRING2 are meant as strings OP is a matching operator, either == (exact match) or ~ (regex match).
varnishtest will first try to resolve STRING1 and STRING2 by looking if they have special meanings, in which case, the resolved value is use for the test. Note that this value can be a string representing a number, allowing for tests such as:
expect req.http.x-num > 2
Here’s the list of recognized strings, most should be obvious as they either match VCL logic, or the txreq/txresp options:
Reads from the connection, expecting nothing to read but an EOF.
Control whether a failure of this entity should stop the test.
Gunzip the body in place.
Process STRING as a specification, NUMBER times.
Read NUMBER bytes from the connection.
Receive an HTTP chunk.
Receive a preface. If valid set the server to HTTP/2, abort otherwise.
Receive and parse a request’s headers and body.
Receive a request’s body.
Receive and parse a request’s headers (but not the body).
Receive and parse a response’s headers and body. If -no_obj is present, only get the headers.
Receive (part of) a response’s body.
-max : max length of this receive, 0 for all
Receive and parse a response’s headers.
Push STRING on the connection.
Write STRING on the socket NUMBER times.
Send string as TCP OOB urgent data. You will never need this.
Send bytes as described by STRING. STRING should consist of hex pairs possibly separated by whitespace or newlines. For example: “0F EE a5 3df2”.
Force internal HTTP/2 settings to certain values. Currently only support setting the decoding table size.
Same as for the top-level shell.
HTTP/2 introduces the concept of streams, and these come with their own specification, and as it’s quite big, have been moved to their own chapter.
Set the TCP timeout for this entity.
Send an HTTP/2 preface (“PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n”) and set client to HTTP/2.
Send a minimal request or response, but overload it if necessary.
txreq is client-specific and txresp is server-specific.
The only thing different between a request and a response, apart from who can send them is that the first line (request line vs status line), so all the options are prety much the same.
What method to use (default: “GET”).
Alias for -method.
What location to use (default “/”).
What protocol use in the status line. (default: “HTTP/1.1”).
What status code to return (default 200).
What message to put in the status line (default: “OK”).
These three switches can appear in any order but must come before the following ones.
Don’t include a Host header in the request.
Don’t include a Content-Length header.
Add STRING as a header, it must follow this format: “name: value”. It can be called multiple times.
Add STRING as a header with NUMBER bytes of content.
You can then use the arguments related to the body:
Input STRING as body.
Same as -body but content is read from FILE.
Generate and input a body that is NUMBER bytes-long.
Set the gzip level (call it before any of the other gzip switches).
Add extra gzip bits. You should never need it.
Gzip STRING and send it as body.
Combine -bodylen and -gzipbody: generate a string of length NUMBER, gzip it and send as body.
Write the body of a request or a response to a file. By using the shell command, higher-level checks on the body can be performed (eg. XML, JSON, …) provided that such checks can be delegated to an external program.
NOTE: This command is available everywhere commands are given.
Sleep for the number of seconds specified in the argument. The number can include a fractional part, e.g. 1.5.
NOTICE: err_shell is deprecated, use shell -err -expect instead.
This is very similar to the the shell command, except it takes a first string as argument before the command:
err_shell "foo" "echo foo"
err_shell expect the shell command to fail AND stdout to match the string, failing the test case otherwise.
Test that the required feature(s) for a test are available, and skip the test otherwise; or change the interpretation of the test, as documented below. feature takes any number of arguments from this list:
The SO_RCVTIMEO socket option is working
The environment is 64 bits
DNS lookups are working
The test has been started with ‘-i’
The test has been invoked by the root user
The varnish user is present
The vcache user is present
The varnish group is present
A command line that should execute with a zero exit status
Do not fail the test if a string of the form ${…} is not recognized as a macro.
Varnish was built with the deprecated persistent storage.
Be careful with ignore_unknown_macro, because it may cause a test with a misspelled macro to fail silently. You should only need it if you must run a test with strings of the form “${…}”.
Define and interact with haproxy instances.
To define a haproxy server, you’ll use this syntax:
haproxy hNAME -conf-OK CONFIG haproxy hNAME -conf-BAD ERROR CONFIG haproxy hNAME [-D] [-W] [-arg STRING] [-conf[+vcl] STRING]
The first haproxy hNAME invocation will start the haproxy master process in the background, waiting for the -start switch to actually start the child.
Arguments:
Identify the HAProxy server with a string, it must starts with ‘h’.
stdout/stderr should contain ‘Configuration file is valid’ The exit code should be 0.
“ERROR” should be part of the diagnostics on stdout/stderr. The exit code should be 1.
Run HAproxy in daemon mode. If not given ‘-d’ mode used.
Enable HAproxy in Worker mode.
Enable HAproxy Master CLI in Worker mode
Pass an argument to haproxy, for example “-h simple_list”.
Specify the spec to be run by the command line interface (CLI).
Specify the spec to be run by the command line interface (CLI) of the Master process.
Specify the configuration to be loaded by this HAProxy instance.
all server instances will be automatically appended
Start this HAProxy instance.
Stop this HAProxy instance.
Expect haproxy to exit(3) with this value
Regex match the CLI reception buffer with STRING if OP is ~ or, on the contraty, if OP is !~ check that there is no regex match.
Push STRING on the CLI connection. STRING will be terminated by an end of line character (n).
Reads the VSL and looks for records matching a given specification. It will process records trying to match the first pattern, and when done, will continue processing, trying to match the following pattern. If a pattern isn’t matched, the test will fail.
logexpect threads are declared this way:
logexpect lNAME -v <id> [-g <grouping>] [-d 0|1] [-q query] \
[vsl arguments] {
expect <skip> <vxid> <tag> <regex>
expect <skip> <vxid> <tag> <regex>
...
} [-start|-wait]
And once declared, you can start them, or wait on them:
logexpect lNAME <-start|-wait>
With:
Name the logexpect thread, it must start with ‘l’.
Specify the varnish instance to use (most of the time, id=v1).
Decide how records are grouped, see -g in man varnishlog for more information.
Start processing log records at the head of the log instead of the tail.
Filter records using a query expression, see man vsl-query for more information. Multiple -q options are not supported.
Also emit log records for misses (only for debugging)
Start the logexpect thread in the background.
Wait for the logexpect thread to finish
VSL arguments (similar to the varnishlog options):
Use caseless regex
Include tags
Include by regex
Transaction end timeout
And the arguments of the specifications lines are:
Max number of record to skip
vxid to match
Tag to match against
regular expression to match against (optional)
For skip, vxid and tag, ‘*’ matches anything, ‘=’ expects the value of the previous matched record.
Run a process with stdin+stdout on a pseudo-terminal and stderr on a pipe.
Output from the pseudo-terminal is copied verbatim to ${pNAME_out}, and the -log/-dump/-hexdump flags will also put it in the vtc-log.
The pseudo-terminal is not in ECHO mode, but if the programs run set it to ECHO mode (“stty sane”) any input sent to the process will also appear in this stream because of the ECHO.
Output from the stderr-pipe is copied verbatim to ${pNAME_err}, and is always included in the vtc_log.
[-start] [-run] [-write STRING] [-writeln STRING] [-kill STRING] [-stop] [-wait] [-close]
Name of the process. It must start with ‘p’.
The command(s) to run in this process.
Log output with vtc_hexdump(). Must be before -start/-run.
Log output with vtc_dump(). Must be before -start/-run.
Log output with VLU/vtc_log(). Must be before -start/-run.
Start the process.
Expect exit status N
Wait for the process to finish.
Shorthand for -start -wait.
In most cases, if you just want to start a process and wait for it to finish, you can use the shell command instead. The following commands are equivalent:
shell "do --something" process p1 "do --something" -run
However, you may use the the process variant to conveniently collect the standard input and output without dealing with shell redirections yourself. The shell command can also expect an expression from either output, consider using it if you only need to match one.
Send a signal to the process. The argument can be either the string “TERM”, “INT”, or “KILL” for SIGTERM, SIGINT or SIGKILL signals, respectively, or a hyphen (-) followed by the signal number.
If you need to use other signal names, you can use the kill(1) command directly:
shell "kill -USR1 ${pNAME_pid}"
Note that SIGHUP usage is discouraged in test cases.
Shorthand for -kill TERM.
Write a string to the process’ stdin.
Same as -write followed by a newline (\n).
Same as -write but interpreted as hexadecimal bytes.
Wait until at least NUMBER bytes have been received in total. If ‘+’ is prefixed, NUMBER new bytes must be received.
Wait for PAT to appear at LIN,COL on the virtual screen. Lines and columns are numbered 1…N LIN==0 means “on any line” COL==0 means “anywhere on the line”
Alias for “-kill HUP”
Dump the virtual screen into vtc_log
Set or change an environment variable:
setenv FOO "bar baz"
The above will set the environment variable $FOO to the value provided. There is also an -ifunset argument which will only set the value if the the environment variable does not already exist:
setenv -ifunset FOO quux
NOTE: This command is available everywhere commands are given.
Pass the string given as argument to a shell. If you have multiple commands to run, you can use curly brackets to describe a multi-lines script, eg:
shell {
echo begin
cat /etc/fstab
echo end
}
By default a zero exit code is expected, otherwise the vtc will fail.
Notice that the commandstring is prefixed with “exec 2>&1;” to combine stderr and stdout back to the test process.
Optional arguments:
Expect non-zero exit code.
Expect exit code N instead of zero.
Expect string to be found in stdout+err.
Expect regexp to match the stdout+err output.
(note: this section is at the top-level for easier navigation, but it’s part of the client/server specification)
Streams map roughly to a request in HTTP/2, a request is sent on stream N, the response too, then the stream is discarded. The main exception is the first stream, 0, that serves as coordinator.
Stream syntax follow the client/server one:
stream ID [SPEC] [ACTION]
ID is the HTTP/2 stream number, while SPEC describes what will be done in that stream.
Note that, when parsing a stream action, if the entity isn’t operating in HTTP/2 mode, these spec is ran before:
txpri/rxpri # client/server
stream 0 {
txsettings
rxsettings
txsettings -ack
rxsettings
expect settings.ack == true
} -run
And HTTP/2 mode is then activated before parsing the specification.
Run the specification in a thread, giving back control immediately.
Wait for the started thread to finish running the spec.
equivalent to calling -start then -wait.
The specification of a stream follows the exact same rules as one for a client or a server.
These four commands are about sending headers. txreq and txresp will send HEADER frames; txcont will send CONTINUATION frames; txpush PUSH frames. The only difference between txreq and txresp are the default headers set by each of them.
Do not add default headers. Useful to avoid duplicates when sending default headers using -hdr, -idxHdr and -litIdxHdr.
Set the :status pseudo-header.
Set the :path pseudo-header.
Set the :method pseudo-header.
Alias for -method.
Set the :scheme pseudo-header.
Insert a header, STRING1 being the name, and STRING2 the value.
Insert an indexed header, using INT as index.
Insert an literal, indexed header. The first argument specify if the header should be added to the table, shouldn’t, or mustn’t be compressed if/when retransmitted.
INT is the idex of the header name to use.
The third argument informs about the Huffman encoding: yes (huf) or no (plain).
The last term is the literal value of the header.
Insert a literal header, with the same first argument as -litIdxHdr.
The second and third terms tell what the name of the header is and if it should be Huffman-encoded, while the last two do the same regarding the value.
Specify a body, effectively putting STRING into a DATA frame after the HEADER frame is sent.
Same as -body but content is read from FILE.
Do the same thing as -body but generate a string of INT length for you.
Gzip STRING and send it as body.
Combine -bodylen and -gzipbody: generate a string of length NUMBER, gzip it and send as body.
Don’t set the END_STREAM flag automatically, making the peer expect a body after the headers.
Don’t set the END_HEADERS flag automatically, making the peer expect more HEADER frames.
Tell the peer that this content depends on the stream with the INT id.
Make the dependency exclusive (-dep is still needed).
Set the weight for the dependency.
The id of the promised stream.
Add string as padding to the frame, either the one you provided with -pad, or one that is generated for you, of length INT is -padlen case.
By default, data frames are empty. The receiving end will know the whole body has been delivered thanks to the END_STREAM flag set in the last DATA frame, and txdata automatically set it.
Data to be embedded into the frame.
Generate and INT-bytes long string to be sent in the frame.
Add string as padding to the frame, either the one you provided with -pad, or one that is generated for you, of length INT is -padlen case.
Don’t set the END_STREAM flag, allowing to send more data on this stream.
These are two convenience functions to receive headers and body of an incoming request or response. The only difference is that rxreq can only be by a server, and rxresp by a client.
rxhdrs will expect one HEADER frame, then, depending on the arguments, zero or more CONTINUATION frame.
Keep waiting for CONTINUATION frames until END_HEADERS flag is seen.
Retrieve INT - 1 CONTINUATION frames after the HEADER frame.
This works like rxhdrs, expecting a PUSH frame and then zero or more CONTINUATION frames.
Keep waiting for CONTINUATION frames until END_HEADERS flag is seen.
Retrieve INT - 1 CONTINUATION frames after the PUSH frame.
Receiving data is done using the rxdata keywords and will retrieve one DATA frame, if you wish to receive more, you can use these two convenience arguments:
keep waiting for DATA frame until one sets the END_STREAM flag
retrieve INT DATA frames.
Receive a frame, any frame.
Push bytes directly on the wire. sendhex takes exactly one argument: a string describing the bytes, in hex notation, with possible whitespaces between them. Here’s an example:
sendhex "00 00 08 00 0900 8d"
Receive a GOAWAY frame.
Possible options include:
set the error code to explain the termination. The second argument can be a integer or the string version of the error code as found in rfc7540#7.
the id of the “highest-numbered stream identifier for which the sender of the GOAWAY frame might have taken some action on or might yet take action on”.
specify the debug data, if any to append to the frame.
Same as the gunzip command for HTTP/1.
Receive a PING frame.
Send PING frame.
specify the payload of the frame, with STRING being an 8-char string.
set the ACK flag.
Receive a PRIORITY frame.
Send a PRIORITY frame
indicate the id of the stream the sender stream depends on.
the dependency should be made exclusive (only this streams depends on the parent stream).
an 8-bits integer is used to balance priority between streams depending on the same streams.
Receive a RST_STREAM frame.
Send a RST_STREAM frame. By default, txrst will send a 0 error code (NO_ERROR).
Sets the error code to be sent. The argument can be an integer or a string describing the error, such as NO_ERROR, or CANCEL (see rfc7540#11.4 for more strings).
Receive a SETTINGS frame.
SETTINGS frames must be acknowledge, arguments are as follow (most of them are from rfc7540#6.5.2):
headers table size
whether push frames are accepted or not
maximum concurrent streams allowed
sender’s initial window size
largest frame size authorized
maximum size of the header list authorized
set the ack bit
Receive a WINDOW_UPDATE frame.
Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the connection (from stream 0) or of the stream (any other stream).
give INT credits to the peer.
Same as the write_body command for HTTP/1.
expect in stream works as it does in client or server, except that the elements compared will be different.
Most of these elements will be frame specific, meaning that the last frame received on that stream must of the correct type.
Here the list of keywords you can look at.
Define and interact with syslog instances (for use with haproxy)
To define a syslog server, you’ll use this syntax:
syslog SNAME
Arguments:
Identify the syslog server with a string which must start with ‘S’.
Set the default syslog priority level used by any subsequent “recv” command. Any syslog dgram with a different level will be skipped by “recv” command. This default level value may be superseded by “recv” command if supplied as first argument: “recv <level>”.
Start the syslog server thread in the background.
NUMBER times.
Bind the syslog socket to a local address.
Wait for that thread to terminate.
Stop the syslog server thread.
Define and interact with varnish instances.
To define a Varnish server, you’ll use this syntax:
varnish vNAME [-arg STRING] [-vcl STRING] [-vcl+backend STRING]
[-errvcl STRING STRING] [-jail STRING] [-proto PROXY]
The first varnish vNAME invocation will start the varnishd master process in the background, waiting for the -start switch to actually start the child.
Types used in the description below:
is a ‘glob’ style pattern (ie: fnmatch(3)) as used in shell filename expansion.
Arguments:
Identify the Varnish server with a string, it must starts with ‘v’.
Pass an argument to varnishd, for example “-h simple_list”.
Specify the VCL to load on this Varnish instance. You’ll probably want to use multi-lines strings for this ({…}).
Do the exact same thing as -vcl, but adds the definition block of known backends (ie. already defined).
Load STRING2 as VCL, expecting it to fail, and Varnish to send an error string matching STRING2
Look at man varnishd (-j) for more information.
Have Varnish use the proxy protocol. Note that PROXY here is the actual string.
You can decide to start the Varnish instance and/or wait for several events:
varnish vNAME [-start] [-wait] [-wait-running] [-wait-stopped]
Start the child process.
Stop the child process.
Set the VCL syntax level for this command (default: 4.1)
Wait for that instance to terminate.
Wait for the Varnish child process to be started.
Wait for the Varnish child process to stop.
Once Varnish is stopped, clean everything after it. This is only used in very few tests and you should never need it.
Once Varnish is started, you can talk to it (as you would through varnishadm) with these additional switches:
varnish vNAME [-cli STRING] [-cliok STRING] [-clierr STRING]
[-clijson STRING] [-expect STRING OP NUMBER]
All four of these will send STRING to the CLI, the only difference is what they expect the result to be. -cli doesn’t expect anything, -cliok expects 200, -clierr expects STATUS, and -cliexpect expects the REGEXP to match the returned response.
Send STRING to the CLI, expect success (CLIS_OK/200) and check that the response is parsable JSON.
Look into the VSM and make sure the first VSC counter identified by PATTERN has a correct value. OP can be ==, >, >=, <, <=. For example:
varnish v1 -expect SM?.s1.g_space > 1000000
Expect varnishd to exit(3) with this value
Dump VSC counters matching PATTERN.
Wait until the logging thread has idled to make sure that all the generated log is flushed
Alternate name for ‘vtest’, see above.
This should be the first command in your vtc as it will identify the test case with a short yet descriptive sentence. It takes exactly one argument, a string, eg:
vtest "Check that vtest is actually a valid command"
It will also print that string in the log.
This document has been written by Guillaume Quintard.
This document is licensed under the same licence as Varnish itself. See LICENCE for details.
Copyright © 2006 Verdens Gang AS
Copyright © 2006–2020 Varnish Software AS
Licensed under the BSD-2-Clause License.
https://varnish-cache.org/docs/6.5/reference/vtc.html