File: //usr/share/doc/varnish/html/reference/varnishtest.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>varnishtest — Varnish version 6.4.0 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '6.4.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Varnish version 6.4.0 documentation" href="../index.html" />
<link rel="up" title="The Varnish Reference Manual" href="index.html" />
<link rel="next" title="varnishtop" href="varnishtop.html" />
<link rel="prev" title="varnishstat" href="varnishstat.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="varnishtop.html" title="varnishtop"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="varnishstat.html" title="varnishstat"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" accesskey="U">The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="varnishtest">
<span id="varnishtest-1"></span><h1>varnishtest<a class="headerlink" href="#varnishtest" title="Permalink to this headline">¶</a></h1>
<div class="section" id="test-program-for-varnish">
<h2>Test program for Varnish<a class="headerlink" href="#test-program-for-varnish" title="Permalink to this headline">¶</a></h2>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Manual section:</th><td class="field-body">1</td>
</tr>
</tbody>
</table>
<div class="section" id="synopsis">
<h3>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h3>
<p>varnishtest [-hikLlqv] [-b size] [-D name=val] [-j jobs] [-n iter] [-t duration] file [file ...]</p>
</div>
<div class="section" id="description">
<h3>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h3>
<p>The varnishtest program is a script driven program used to test the
Varnish Cache.</p>
<p>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.</p>
<p>The following options are available:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-b <var>size</var></span></kbd></td>
<td>Set internal buffer size (default: 1M)</td></tr>
</tbody>
</table>
<p>-D name=val Define macro for use in scripts</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-h</span></kbd></td>
<td>Show help</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-i</span></kbd></td>
<td>Set PATH and vmod_path to find varnish binaries in build tree</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-j <var>jobs</var></span></kbd></td>
<td>Run this many tests in parallel</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-k</span></kbd></td>
<td>Continue on test failure</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-L</span></kbd></td>
<td>Always leave temporary vtc.*</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-l</span></kbd></td>
<td>Leave temporary vtc.* if test fails</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-n <var>iterations</var></span></kbd></td>
<td>Run tests this many times</td></tr>
</tbody>
</table>
<p>-p name=val Pass parameters to all varnishd command lines</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">-q</span></kbd></td>
<td>Quiet mode: report only failures</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-t <var>duration</var></span></kbd></td>
<td>Time tests out after this long (default: 60s)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">-v</span></kbd></td>
<td>Verbose mode: always report test log</td></tr>
</tbody>
</table>
<p>file File to use as a script</p>
<p>If <cite>TMPDIR</cite> is set in the environment, varnishtest creates temporary
<cite>vtc.*</cite> directories for each test in <cite>$TMPDIR</cite>, otherwise in <cite>/tmp</cite>.</p>
</div>
<div class="section" id="scripts">
<h3>SCRIPTS<a class="headerlink" href="#scripts" title="Permalink to this headline">¶</a></h3>
<p>The vtc syntax is documented at length in <a class="reference internal" href="vtc.html#vtc-7"><em>VTC</em></a>. Should you want more
examples than the one below, you can have a look at the Varnish source code
repository, under <cite>bin/varnishtest/tests/</cite>, where all the regression tests for
Varnish are kept.</p>
<p>An example:</p>
<div class="highlight-python"><pre>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</pre>
</div>
<p>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.</p>
</div>
<div class="section" id="testing-a-build-tree">
<h3>TESTING A BUILD TREE<a class="headerlink" href="#testing-a-build-tree" title="Permalink to this headline">¶</a></h3>
<p>Whether you are building a VMOD or trying to use one that you freshly
built, you can tell <tt class="docutils literal"><span class="pre">varnishtest</span></tt> to pass a <em>vmod_path</em> to <tt class="docutils literal"><span class="pre">varnishd</span></tt>
instances started using the <tt class="docutils literal"><span class="pre">varnish</span> <span class="pre">-start</span></tt> command in your test case:</p>
<div class="highlight-python"><pre>varnishtest -p vmod_path=... /path/to/*.vtc</pre>
</div>
<p>This way you can use the same test cases on both installed and built
VMODs:</p>
<div class="highlight-python"><pre>server s1 {...} -start
varnish v1 -vcl+backend {
import wossname;
...
} -start
...</pre>
</div>
<p>You are not limited to the <em>vmod_path</em> 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.</p>
<p>You can see the actual <tt class="docutils literal"><span class="pre">varnishd</span></tt> command lines in test outputs,
they look roughly like this:</p>
<div class="highlight-python"><pre>exec varnishd [varnishtest -p params] [testing params] [vtc -arg params]</pre>
</div>
<p>Parameters you define with <tt class="docutils literal"><span class="pre">varnishtest</span> <span class="pre">-p</span></tt> may be overriden by
parameters needed by <tt class="docutils literal"><span class="pre">varnishtest</span></tt> to run properly, and they may in
turn be overriden by parameters set in test scripts.</p>
<p>There's also a special mode in which <tt class="docutils literal"><span class="pre">varnishtest</span></tt> builds itself a
PATH and a <em>vmod_path</em> in order to find Varnish binaries (programs and
VMODs) in the build tree surrounding the <tt class="docutils literal"><span class="pre">varnishtest</span></tt> binary. This
is meant for testing of Varnish under development and will disregard
your <em>vmod_path</em> if you set one.</p>
<p>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 <em>pkg-config(1)</em> you can build a proper
PATH in order to access Varnish programs, and a <em>vmod_path</em> to access
both your VMOD and the built-in VMODs:</p>
<div class="highlight-python"><pre>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" ...</pre>
</div>
</div>
<div class="section" id="see-also">
<h3>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li>varnishtest source code repository with tests</li>
<li><a class="reference internal" href="varnishhist.html#varnishhist-1"><em>varnishhist</em></a></li>
<li><a class="reference internal" href="varnishlog.html#varnishlog-1"><em>varnishlog</em></a></li>
<li><a class="reference internal" href="varnishncsa.html#varnishncsa-1"><em>varnishncsa</em></a></li>
<li><a class="reference internal" href="varnishstat.html#varnishstat-1"><em>varnishstat</em></a></li>
<li><a class="reference internal" href="varnishtop.html#varnishtop-1"><em>varnishtop</em></a></li>
<li><a class="reference internal" href="vcl.html#vcl-7"><em>VCL</em></a></li>
<li><a class="reference internal" href="vtc.html#vtc-7"><em>VTC</em></a></li>
<li><a class="reference internal" href="vmod_vtc.html#vmod-vtc-3"><em>VMOD vtc - Utility module for varnishtest</em></a></li>
</ul>
</div>
<div class="section" id="history">
<h3>HISTORY<a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h3>
<p>The varnishtest program was developed by Poul-Henning Kamp
<<a class="reference external" href="mailto:phk%40phk.freebsd.dk">phk<span>@</span>phk<span>.</span>freebsd<span>.</span>dk</a>> in cooperation with Varnish Software AS. This manual
page was originally written by Stig Sandbeck Mathisen <<a class="reference external" href="mailto:ssm%40linpro.no">ssm<span>@</span>linpro<span>.</span>no</a>>
and updated by Kristian Lyngstøl <<a class="reference external" href="mailto:kristian%40varnish-cache.org">kristian<span>@</span>varnish-cache<span>.</span>org</a>>.</p>
</div>
<div class="section" id="copyright">
<h3>COPYRIGHT<a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h3>
<p>This document is licensed under the same licence as Varnish
itself. See LICENCE for details.</p>
<ul class="simple">
<li>Copyright (c) 2007-2016 Varnish Software AS</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">varnishtest</a><ul>
<li><a class="reference internal" href="#test-program-for-varnish">Test program for Varnish</a><ul>
<li><a class="reference internal" href="#synopsis">SYNOPSIS</a></li>
<li><a class="reference internal" href="#description">DESCRIPTION</a></li>
<li><a class="reference internal" href="#scripts">SCRIPTS</a></li>
<li><a class="reference internal" href="#testing-a-build-tree">TESTING A BUILD TREE</a></li>
<li><a class="reference internal" href="#see-also">SEE ALSO</a></li>
<li><a class="reference internal" href="#history">HISTORY</a></li>
<li><a class="reference internal" href="#copyright">COPYRIGHT</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="varnishstat.html"
title="previous chapter">varnishstat</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="varnishtop.html"
title="next chapter">varnishtop</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/reference/varnishtest.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="varnishtop.html" title="varnishtop"
>next</a> |</li>
<li class="right" >
<a href="varnishstat.html" title="varnishstat"
>previous</a> |</li>
<li><a href="../index.html">Varnish version 6.4.0 documentation</a> »</li>
<li><a href="index.html" >The Varnish Reference Manual</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2010-2014, Varnish Software AS.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>