varnishtest: VTC Tests for Varnish in CI
varnishtest runs .vtc test files that spin up mock servers and clients against a real Varnish instance and assert on the results.
varnishtest is how you actually test VCL behavior, not just compile it. A VTC file describes a server, a Varnish with your VCL, and clients that assert responses, all in one harness.
What it does
varnishtest reads one or more .vtc files, each of which defines mock backends (server), a Varnish instance loading your VCL (varnish), and clients that send requests and assert on responses. It runs them, reports each test as pass or fail, and exits non-zero if any test fails. It is a full behavioral test, not a syntax check.
Common usage
varnishtest test/cache.vtc
# verbose output for a failing test
varnishtest -v test/cache.vtc
# keep temp dirs on failure for debugging
varnishtest -k test/cache.vtcA minimal VTC
varnishtest "hit is cached"
server s1 { rxreq; txresp -body "ok" } -start
varnish v1 -vcl+backend { } -start
client c1 { txreq; rxresp; expect resp.status == 200 } -runOptions
| Flag | What it does |
|---|---|
| -v | Verbose: print the full transcript |
| -k | Keep temporary directories after a failure |
| -j <n> | Run <n> test jobs in parallel |
| -l | Leave the temp dir on any exit (with -k) |
| -t <s> | Per-test timeout in seconds |
In CI
Run varnishtest against your production VCL in the matching Varnish image so vmods and syntax align. Use -v when a test fails so the transcript shows the exact request and response, and -k to keep the temp dir for inspection. A non-zero exit fails the job on any assertion miss.
Common errors in CI
"---- v1 Not true: resp.status (503) == 200" is a typical assertion failure, printed with the failing expression and actual value. "VCL compilation failed" inside a test means the embedded VCL is broken (same as varnishd -C). "Could not open ... vtc" means a wrong test path. Flaky timeouts often need a larger -t on slow shared runners.