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)