1VARNISHTEST(1)                                                  VARNISHTEST(1)
2
3
4

NAME

6       varnishtest - Test program for Varnish
7

SYNOPSIS

9       varnishtest  [-hikLlqv] [-b size] [-D name=val] [-j jobs] [-n iter] [-t
10       duration] file [file ...]
11

DESCRIPTION

13       The varnishtest program is a script driven program  used  to  test  the
14       Varnish Cache.
15
16       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
21       The following options are available:
22
23       -b size
24              Set internal buffer size (default: 1M)
25
26       -D name=val      Define macro for use in scripts
27
28       -h     Show help
29
30       -i     Set PATH and vmod_path to find varnish binaries in build tree
31
32       -j jobs
33              Run this many tests in parallel
34
35       -k     Continue on test failure
36
37       -L     Always leave temporary vtc.*
38
39       -l     Leave temporary vtc.* if test fails
40
41       -n iterations
42              Run tests this many times
43
44       -p name=val      Pass parameters to all varnishd command lines
45
46       -q     Quiet mode: report only failures
47
48       -t duration
49              Time tests out after this long (default: 60s)
50
51       -v     Verbose mode: always report test log
52
53       file             File to use as a script
54
55       If TMPDIR is set in  the  environment,  varnishtest  creates  temporary
56       vtc.* directories for each test in $TMPDIR, otherwise in /tmp.
57

SCRIPTS

59       The  vtc syntax is documented at length in vtc(7). Should you want more
60       examples than the one below, you can have a look at the Varnish  source
61       code repository, under bin/varnishtest/tests/, where all the regression
62       tests for Varnish are kept.
63
64       An example:
65
66          varnishtest "#1029"
67
68          server s1 {
69                  rxreq
70                  expect req.url == "/bar"
71                  txresp -gzipbody {[bar]}
72
73                  rxreq
74                  expect req.url == "/foo"
75                  txresp -body {<h1>FOO<esi:include src="/bar"/>BARF</h1>}
76
77          } -start
78
79          varnish v1 -vcl+backend {
80                  sub vcl_backend_response {
81                          set beresp.do_esi = true;
82                          if (bereq.url == "/foo") {
83                                  set beresp.ttl = 0s;
84                          } else {
85                                  set beresp.ttl = 10m;
86                          }
87                  }
88          } -start
89
90          client c1 {
91                  txreq -url "/bar" -hdr "Accept-Encoding: gzip"
92                  rxresp
93                  gunzip
94                  expect resp.bodylen == 5
95
96                  txreq -url "/foo" -hdr "Accept-Encoding: gzip"
97                  rxresp
98                  expect resp.bodylen == 21
99          } -run
100
101       When run, the above script will simulate a server (s1) that expects two
102       different  requests.  It  will  start a Varnish server (v1) and add the
103       backend definition to the  VCL  specified  (-vcl+backend).  Finally  it
104       starts the c1-client, which is a single client sending two requests.
105

TESTING A BUILD TREE

107       Whether  you  are building a VMOD or trying to use one that you freshly
108       built, you can tell varnishtest to pass a  vmod_path  to  varnishd  in‐
109       stances started using the varnish -start command in your test case:
110
111          varnishtest -p vmod_path=... /path/to/*.vtc
112
113       This  way  you  can use the same test cases on both installed and built
114       VMODs:
115
116          server s1 {...} -start
117
118          varnish v1 -vcl+backend {
119              import wossname;
120
121              ...
122          } -start
123
124          ...
125
126       You are not limited to the vmod_path and can pass any parameter, allow‐
127       ing  you to run a build matrix without changing the test suite. You can
128       achieve the same with macros, but then they need to be defined on  each
129       run.
130
131       You  can  see  the  actual varnishd command lines in test outputs, they
132       look roughly like this:
133
134          exec varnishd [varnishtest -p params] [testing params] [vtc -arg params]
135
136       Parameters you define with varnishtest -p may be overridden by  parame‐
137       ters  needed  by  varnishtest  to run properly, and they may in turn be
138       overridden by parameters set in test scripts.
139
140       There's also a special mode in which varnishtest builds itself  a  PATH
141       and  a vmod_path in order to find Varnish binaries (programs and VMODs)
142       in the build tree surrounding the varnishtest binary. This is meant for
143       testing  of Varnish under development and will disregard your vmod_path
144       if you set one.
145
146       If you need to test your VMOD against a Varnish build  tree,  you  must
147       install  it  first,  in a temp directory for instance. With information
148       provided by the installation's pkg-config(1) you  can  build  a  proper
149       PATH  in  order  to  access Varnish programs, and a vmod_path to access
150       both your VMOD and the built-in VMODs:
151
152          export PKG_CONFIG_PATH=/path/to/install/lib/pkgconfig
153
154          BINDIR="$(pkg-config --variable=bindir varnishapi)"
155          SBINDIR="$(pkg-config --variable=sbindir varnishapi)"
156          PATH="SBINDIR:BINDIR:$PATH"
157
158          VMODDIR="$(pkg-config --variable=vmoddir varnishapi)"
159          VMOD_PATH="/path/to/your/vmod/build/dir:$VMODDIR"
160
161          varnishtest -p vmod_path="$VMOD_PATH" ...
162

SEE ALSO

164       • varnishtest source code repository with tests
165
166varnishhist(1)
167
168varnishlog(1)
169
170varnishncsa(1)
171
172varnishstat(1)
173
174varnishtop(1)
175
176vcl(7)
177
178vtc(7)
179
180vmod_vtc(3)
181

HISTORY

183       The  varnishtest  program  was  developed  by  Poul-Henning   Kamp   <‐
184       phk@phk.freebsd.dk> in cooperation with Varnish Software AS.  This man‐
185       ual  page  was  originally  written  by  Stig  Sandbeck   Mathisen   <‐
186       ssm@linpro.no>     and     updated     by    Kristian    Lyngstøl    <‐
187       kristian@varnish-cache.org>.
188
190       This document is licensed under the same licence as Varnish itself. See
191       LICENCE for details.
192
193       • Copyright (c) 2007-2016 Varnish Software AS
194
195
196
197
198                                                                VARNISHTEST(1)
Impressum