1VARNISHTEST(1) VARNISHTEST(1)
2
6 varnishtest - Test program for Varnish
7
9 varnishtest [-hikLlqvW] [-b size] [-D name=val] [-j jobs] [-n iter] [-t
10 duration] file [file ...]
11
13 The varnishtest program is a script driven program used to test the
14 Varnish Cache.
15 The varnishtest program, when started and given one or more script
17 files, can create a number of threads representing backends, some
18 threads representing clients, and a varnishd process. This is then used
19 to simulate a transaction to provoke a specific behavior.
20 The following options are available:
22 -b size
24 Set internal buffer size (default: 1M)
25 -D name=val Define macro for use in scripts
27 -h Show help
29 -i Set PATH and vmod_path to find varnish binaries in build tree
31 -j jobs
33 Run this many tests in parallel
34 -k Continue on test failure
36 -L Always leave temporary vtc.*
38 -l Leave temporary vtc.* if test fails
40 -n iterations
42 Run tests this many times
43 -p name=val Pass parameters to all varnishd command lines
45 -q Quiet mode: report only failures
47 -t duration
49 Time tests out after this long (default: 60s)
50 -v Verbose mode: always report test log
52 -W Enable the witness facility for locking
54 file File to use as a script
56 If TMPDIR is set in the environment, varnishtest creates temporary
58 vtc.* directories for each test in $TMPDIR, otherwise in /tmp.
59
61 The vtc syntax is documented at length in vtc(7). Should you want more
62 examples than the one below, you can have a look at the Varnish source
63 code repository, under bin/varnishtest/tests/, where all the regression
64 tests for Varnish are kept.
65 An example:
67 varnishtest "#1029"
69 server s1 {
71 rxreq
72 expect req.url == "/bar"
73 txresp -gzipbody {[bar]}
74 rxreq
76 expect req.url == "/foo"
77 txresp -body {<h1>FOO<esi:include src="/bar"/>BARF</h1>}
78 } -start
80 varnish v1 -vcl+backend {
82 sub vcl_backend_response {
83 set beresp.do_esi = true;
84 if (bereq.url == "/foo") {
85 set beresp.ttl = 0s;
86 } else {
87 set beresp.ttl = 10m;
88 }
89 }
90 } -start
91 client c1 {
93 txreq -url "/bar" -hdr "Accept-Encoding: gzip"
94 rxresp
95 gunzip
96 expect resp.bodylen == 5
97 txreq -url "/foo" -hdr "Accept-Encoding: gzip"
99 rxresp
100 expect resp.bodylen == 21
101 } -run
102 When run, the above script will simulate a server (s1) that expects two
104 different requests. It will start a Varnish server (v1) and add the
105 backend definition to the VCL specified (-vcl+backend). Finally it
106 starts the c1-client, which is a single client sending two requests.
107
109 Whether you are building a VMOD or trying to use one that you freshly
110 built, you can tell varnishtest to pass a vmod_path to varnishd
111 instances started using the varnish -start command in your test case:
112 varnishtest -p vmod_path=... /path/to/*.vtc
114 This way you can use the same test cases on both installed and built
116 VMODs:
117 server s1 {...} -start
119 varnish v1 -vcl+backend {
121 import wossname;
122 ...
124 } -start
125 ...
127 You are not limited to the vmod_path and can pass any parameter, allow‐
129 ing you to run a build matrix without changing the test suite. You can
130 achieve the same with macros, but then they need to be defined on each
131 run.
132 You can see the actual varnishd command lines in test outputs, they
134 look roughly like this:
135 exec varnishd [varnishtest -p params] [testing params] [vtc -arg params]
137 Parameters you define with varnishtest -p may be overriden by parame‐
139 ters needed by varnishtest to run properly, and they may in turn be
140 overriden by parameters set in test scripts.
141 There's also a special mode in which varnishtest builds itself a PATH
143 and a vmod_path in order to find Varnish binaries (programs and VMODs)
144 in the build tree surrounding the varnishtest binary. This is meant for
145 testing of Varnish under development and will disregard your vmod_path
146 if you set one.
147 If you need to test your VMOD against a Varnish build tree, you must
149 install it first, in a temp directory for instance. With information
150 provided by the installation's pkg-config(1) you can build a proper
151 PATH in order to access Varnish programs, and a vmod_path to access
152 both your VMOD and the built-in VMODs:
153 export PKG_CONFIG_PATH=/path/to/install/lib/pkgconfig
155 BINDIR="$(pkg-config --variable=bindir varnishapi)"
157 SBINDIR="$(pkg-config --variable=sbindir varnishapi)"
158 PATH="SBINDIR:BINDIR:$PATH"
159 VMODDIR="$(pkg-config --variable=vmoddir varnishapi)"
161 VMOD_PATH="/path/to/your/vmod/build/dir:$VMODDIR"
162 varnishtest -p vmod_path="$VMOD_PATH" ...
164
166 · varnishtest source code repository with tests
167 · varnishhist(1)
169 · varnishlog(1)
171 · varnishncsa(1)
173 · varnishstat(1)
175 · varnishtop(1)
177 · vcl(7)
179 · vtc(7)
181 · vmod_vtc(3)
183
185 The varnishtest program was developed by Poul-Henning Kamp <‐
186 phk@phk.freebsd.dk> in cooperation with Varnish Software AS. This man‐
187 ual page was originally written by Stig Sandbeck Mathisen <‐
188 ssm@linpro.no> and updated by Kristian Lyngstøl <‐
189 kristian@varnish-cache.org>.
190
192 This document is licensed under the same licence as Varnish itself. See
193 LICENCE for details.
194 · Copyright (c) 2007-2016 Varnish Software AS
196 VARNISHTEST(1)