---
name: "varnishtest"
section: "1"
platform: "linux"
package: "varnish"
version: "7.7.0-3+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/varnishtest"
---

# varnishtest(1)

Test program for Varnish

## NAME

varnishtest - Test program for Varnish

## SYNOPSIS

varnishtest \[-hikLlqv\] \[-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

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)](/vtc/7.md)*. 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 overridden by parameters needed by **varnishtest** to run properly, and they may in turn be overridden 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)](/pkg-config/1.md)* 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)](/varnishhist/1.md)*

- •

  *[varnishlog(1)](/varnishlog/1.md)*

- •

  *[varnishncsa(1)](/varnishncsa/1.md)*

- •

  *[varnishstat(1)](/varnishstat/1.md)*

- •

  *[varnishtop(1)](/varnishtop/1.md)*

- •

  *[vcl(7)](/vcl/7.md)*

- •

  *[vtc(7)](/vtc/7.md)*

- •

  *[vmod\_vtc(3)](/vmod_vtc/3.md)*

## 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