Provided by: varnish_5.2.1-1ubuntu0.1_amd64 bug

NAME

       varnishtest - Test program for Varnish

SYNOPSIS

       varnishtest  [-hikLlqvW]  [-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

       -W     Enable the witness facility for locking

       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 {<h1>FOO<esi:include src="/bar"/>BARF</h1>}

          } -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  overriden by parameters needed by
       varnishtest to run properly, and they may in turn be overriden 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

       • varnishtest source code repository with tests

       • varnishhist(1)varnishlog(1)varnishncsa(1)varnishstat(1)varnishtop(1)vcl(7)vtc(7)vmod_vtc(3)

HISTORY

       The  varnishtest  program  was  developed  by  Poul-Henning  Kamp  <phk@phk.freebsd.dk> in
       cooperation with Varnish Software AS.  This manual page was  originally  written  by  Stig
       Sandbeck    Mathisen    <ssm@linpro.no>    and    updated    by   Kristian   Lyngstøl   <‐
       kristian@varnish-cache.org>.

COPYRIGHT

       This document is licensed under the same  licence  as  Varnish  itself.  See  LICENCE  for
       details.

       • Copyright (c) 2007-2016 Varnish Software AS

                                                                                   VARNISHTEST(1)