.\" Man page generated from reStructuredText. . .TH VARNISHTEST 1 "" "" "" .SH NAME varnishtest \- Test program for Varnish . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH SYNOPSIS .sp varnishtest [\-hikLlqvW] [\-b size] [\-D name=val] [\-j jobs] [\-n iter] [\-t duration] file [file ...] .SH DESCRIPTION .sp The varnishtest program is a script driven program used to test the Varnish Cache. .sp 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. .sp The following options are available: .INDENT 0.0 .TP .BI \-b \ size Set internal buffer size (default: 1M) .UNINDENT .sp \-D name=val Define macro for use in scripts .INDENT 0.0 .TP .B \-h Show help .TP .B \-i Set PATH and vmod_path to find varnish binaries in build tree .TP .BI \-j \ jobs Run this many tests in parallel .TP .B \-k Continue on test failure .TP .B \-L Always leave temporary vtc.* .TP .B \-l Leave temporary vtc.* if test fails .TP .BI \-n \ iterations Run tests this many times .UNINDENT .sp \-p name=val Pass parameters to all varnishd command lines .INDENT 0.0 .TP .B \-q Quiet mode: report only failures .TP .BI \-t \ duration Time tests out after this long (default: 60s) .TP .B \-v Verbose mode: always report test log .TP .B \-W Enable the witness facility for locking .UNINDENT .sp file File to use as a script .sp If \fITMPDIR\fP is set in the environment, varnishtest creates temporary \fIvtc.*\fP directories for each test in \fI$TMPDIR\fP, otherwise in \fI/tmp\fP\&. .SH SCRIPTS .sp The vtc syntax is documented at length in \fIvtc(7)\fP\&. Should you want more examples than the one below, you can have a look at the Varnish source code repository, under \fIbin/varnishtest/tests/\fP, where all the regression tests for Varnish are kept. .sp An example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C varnishtest "#1029" server s1 { rxreq expect req.url == "/bar" txresp \-gzipbody {[bar]} rxreq expect req.url == "/foo" txresp \-body {

FOOBARF

} } \-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 .ft P .fi .UNINDENT .UNINDENT .sp 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. .SH TESTING A BUILD TREE .sp Whether you are building a VMOD or trying to use one that you freshly built, you can tell \fBvarnishtest\fP to pass a \fIvmod_path\fP to \fBvarnishd\fP instances started using the \fBvarnish \-start\fP command in your test case: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C varnishtest \-p vmod_path=... /path/to/*.vtc .ft P .fi .UNINDENT .UNINDENT .sp This way you can use the same test cases on both installed and built VMODs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C server s1 {...} \-start varnish v1 \-vcl+backend { import wossname; ... } \-start \&... .ft P .fi .UNINDENT .UNINDENT .sp You are not limited to the \fIvmod_path\fP 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. .sp You can see the actual \fBvarnishd\fP command lines in test outputs, they look roughly like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C exec varnishd [varnishtest \-p params] [testing params] [vtc \-arg params] .ft P .fi .UNINDENT .UNINDENT .sp Parameters you define with \fBvarnishtest \-p\fP may be overriden by parameters needed by \fBvarnishtest\fP to run properly, and they may in turn be overriden by parameters set in test scripts. .sp There\(aqs also a special mode in which \fBvarnishtest\fP builds itself a PATH and a \fIvmod_path\fP in order to find Varnish binaries (programs and VMODs) in the build tree surrounding the \fBvarnishtest\fP binary. This is meant for testing of Varnish under development and will disregard your \fIvmod_path\fP if you set one. .sp 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\(aqs \fIpkg\-config(1)\fP you can build a proper PATH in order to access Varnish programs, and a \fIvmod_path\fP to access both your VMOD and the built\-in VMODs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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" ... .ft P .fi .UNINDENT .UNINDENT .SH SEE ALSO .INDENT 0.0 .IP \(bu 2 varnishtest source code repository with tests .IP \(bu 2 \fIvarnishhist(1)\fP .IP \(bu 2 \fIvarnishlog(1)\fP .IP \(bu 2 \fIvarnishncsa(1)\fP .IP \(bu 2 \fIvarnishstat(1)\fP .IP \(bu 2 \fIvarnishtop(1)\fP .IP \(bu 2 \fIvcl(7)\fP .IP \(bu 2 \fIvtc(7)\fP .IP \(bu 2 \fIvmod_vtc(3)\fP .UNINDENT .SH HISTORY .sp The varnishtest program was developed by Poul\-Henning Kamp <\fI\%phk@phk.freebsd.dk\fP> in cooperation with Varnish Software AS. This manual page was originally written by Stig Sandbeck Mathisen <\fI\%ssm@linpro.no\fP> and updated by Kristian Lyngstøl <\fI\%kristian@varnish\-cache.org\fP>. .SH COPYRIGHT .sp This document is licensed under the same licence as Varnish itself. See LICENCE for details. .INDENT 0.0 .IP \(bu 2 Copyright (c) 2007\-2016 Varnish Software AS .UNINDENT .\" Generated by docutils manpage writer. .