VARNISHTEST(1) General Commands Manual VARNISHTEST(1)
NAME
varnishtest - Test program for Varnish
SYNOPSIS
varnishtest [-hikLlqv] [-b size] [-D name=val] [-j jobs] [-n iter] [-t
duration] file [file ...]
DESCRIPTION
The varnishtest program is a script driven program used to test the
Varnish Cache.
The varnishtest program, when started and given one or more script
files, can create a number of threads representing backends, some
threads representing clients, and a varnishd process. This is then used
to simulate a transaction to provoke a specific behavior.
The following options are available:
-b size
Set internal buffer size (default: 1M)
-D name=val Define macro for use in scripts
-h Show help
-i Set PATH and vmod_path to find varnish binaries in build tree
-j jobs
Run this many tests in parallel
-k Continue on test failure
-L Always leave temporary vtc.*
-l Leave temporary vtc.* if test fails
-n iterations
Run tests this many times
-p name=val Pass parameters to all varnishd command lines
-q Quiet mode: report only failures
-t duration
Time tests out after this long (default: 60s)
-v Verbose mode: always report test log
file File to use as a script
If TMPDIR is set in the environment, varnishtest creates temporary
vtc.* directories for each test in $TMPDIR, otherwise in /tmp.
SCRIPTS
The vtc syntax is documented at length in vtc(7). Should you want more
examples than the one below, you can have a look at the Varnish source
code repository, under bin/varnishtest/tests/, where all the regression
tests for Varnish are kept.
An example:
varnishtest "#1029"
server s1 {
rxreq
expect req.url == "/bar"
txresp -gzipbody {[bar]}
rxreq
expect req.url == "/foo"
txresp -body {
FOOBARF
}
} -start
varnish v1 -vcl+backend {
sub vcl_backend_response {
set beresp.do_esi = true;
if (bereq.url == "/foo") {
set beresp.ttl = 0s;
} else {
set beresp.ttl = 10m;
}
}
} -start
client c1 {
txreq -url "/bar" -hdr "Accept-Encoding: gzip"
rxresp
gunzip
expect resp.bodylen == 5
txreq -url "/foo" -hdr "Accept-Encoding: gzip"
rxresp
expect resp.bodylen == 21
} -run
When run, the above script will simulate a server (s1) that expects two
different requests. It will start a Varnish server (v1) and add the
backend definition to the VCL specified (-vcl+backend). Finally it
starts the c1-client, which is a single client sending two requests.
TESTING A BUILD TREE
Whether you are building a VMOD or trying to use one that you freshly
built, you can tell varnishtest to pass a vmod_path to varnishd
instances started using the varnish -start command in your test case:
varnishtest -p vmod_path=... /path/to/*.vtc
This way you can use the same test cases on both installed and built
VMODs:
server s1 {...} -start
varnish v1 -vcl+backend {
import wossname;
...
} -start
...
You are not limited to the vmod_path and can pass any parameter,
allowing you to run a build matrix without changing the test suite. You
can achieve the same with macros, but then they need to be defined on
each run.
You can see the actual varnishd command lines in test outputs, they
look roughly like this:
exec varnishd [varnishtest -p params] [testing params] [vtc -arg params]
Parameters you define with varnishtest -p may be overridden by
parameters needed by varnishtest to run properly, and they may in turn
be overridden by parameters set in test scripts.
There's also a special mode in which varnishtest builds itself a PATH
and a vmod_path in order to find Varnish binaries (programs and VMODs)
in the build tree surrounding the varnishtest binary. This is meant for
testing of Varnish under development and will disregard your vmod_path
if you set one.
If you need to test your VMOD against a Varnish build tree, you must
install it first, in a temp directory for instance. With information
provided by the installation's pkg-config(1) you can build a proper
PATH in order to access Varnish programs, and a vmod_path to access
both your VMOD and the built-in VMODs:
export PKG_CONFIG_PATH=/path/to/install/lib/pkgconfig
BINDIR="$(pkg-config --variable=bindir varnishapi)"
SBINDIR="$(pkg-config --variable=sbindir varnishapi)"
PATH="SBINDIR:BINDIR:$PATH"
VMODDIR="$(pkg-config --variable=vmoddir varnishapi)"
VMOD_PATH="/path/to/your/vmod/build/dir:$VMODDIR"
varnishtest -p vmod_path="$VMOD_PATH" ...
SEE ALSO
o varnishtest source code repository with tests
o varnishhist(1)
o varnishlog(1)
o varnishncsa(1)
o varnishstat(1)
o varnishtop(1)
o vcl(7)
o vtc(7)
o vmod_vtc(3)
HISTORY
The varnishtest program was developed by Poul-Henning Kamp
in cooperation with Varnish Software AS. This
manual page was originally written by Stig Sandbeck Mathisen
and updated by Kristian Lyngstol
.
COPYRIGHT
This document is licensed under the same licence as Varnish itself. See
LICENCE for details.
o Copyright (c) 2007-2016 Varnish Software AS
VARNISHTEST(1)