VINYLTEST(1)

📦
version 9.1.0 · 3 versions
, in arch rolling

💅 VINYLTEST — the vinyltest(1) page, but make it make sense

okay so this is the manual page for vinyltest, straight out of the General Commands Manual section, and we're gonna get through it together bestie 🫶

✨ NAME ✨

vinyltest — the test program for Vinyl Cache. that's it, that's the whole vibe check 💖

🦋 SYNOPSIS 🦋

vinyltest [-hikLlqv] [-b size] [-D name=val] [-j jobs] [-n iter] [-t duration] file [file ...]

like, one or more *file*s, and a whole alphabet of flags. iconic behavior honestly 🔥

🌸 DESCRIPTION 🌸

vinyltest is a script driven program — the scripts do all the work, she just runs them — and its whole job is to test the Vinyl Cache. no cap.

here's the cute part: when you start vinyltest and hand it one or more script files, it can spin up a bunch of threads that represent backends, some threads that represent clients, and a vinyld process. then all of that gets used to simulate a transaction, specifically to provoke a specific behavior. lowkey a little theatre production 🎀

the following options are available:

  • -b size — set the internal buffer size (default: 1M)
  • -D name=val — define a macro for use in scripts
  • -h — show help
  • -i — set PATH and vmod_path to find Vinyl Cache binaries in the build tree
  • -j jobs — run this many tests in parallel
  • -k — continue on test failure (girlboss move honestly)
  • -L — always leave temporary vtc.*
  • -l — leave temporary vtc.* if the test fails
  • -n iterations — run tests this many times
  • -p name=val — pass parameters to all vinyld 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

so if TMPDIR is set in the environment, vinyltest creates temporary vtc.* directories for each test inside $TMPDIR, otherwise it goes to /tmp. respect the environment variable, periodt 💜

also, at several points during a test, the process will be forked and excess file descriptors are closed. heads up though: on systems without the closefrom system call, or without read access to /proc/<PID>/fd, this can eat up significant amounts of time and CPU 😭 you can mitigate it by lowering the file descriptor limit. ngl that's the whole tip, no extra lore.

🧚 SCRIPTS 🧚

the vtc syntax is documented at length in vtc(7) — go read that if you want the deep lore. and if you want more examples than the one below, you can have a look at the Vinyl Cache source code repository, under bin/vinyltest/tests/, where all the regression tests for Vinyl Cache are kept. slay 💅

an example:

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

vinyl 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 vinyld (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. she's doing a lot but she's handling it ✨

🌈 TESTING A BUILD TREE 🌈

whether you're building a VMOD or trying to use one that you freshly built, you can tell vinyltest to pass a vmod_path to vinyld instances started using the vinyl -start command in your test case:

vinyltest -p vmod_path=... /path/to/*.vtc

this way you can use the same test cases on both installed and built VMODs:

server s1 {...} -start

vinyl v1 -vcl+backend {
    import wossname;

    ...
} -start

...

you are not limited to the vmod_path — you can pass any parameter, which lets you 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, and nobody has time for that 🙈)

you can see the actual vinyld command lines in test outputs, they look roughly like this:

exec vinyld [vinyltest -p params] [testing params] [vtc -arg params]

parameters you define with vinyltest -p may be overridden by parameters needed by vinyltest to run properly, and they may in turn be overridden by parameters set in test scripts. it's giving layered authority, ikyk 😌

there's also a special mode in which vinyltest builds itself a PATH and a vmod_path in order to find Vinyl Cache binaries (programs and VMODs) in the build tree surrounding the vinyltest binary. this is meant for testing of Vinyl Cache under development, and will disregard your vmod_path if you set one.

okay so if you need to test your VMOD against a Vinyl Cache build tree, you must install it first — in a temp directory for instance. no shortcuts bestie.

with information provided by the installation's pkg-config(1) you can build a proper PATH in order to access Vinyl 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 vinylapi)"
SBINDIR="$(pkg-config --variable=sbindir vinylapi)"
PATH="SBINDIR:BINDIR:$PATH"

VMODDIR="$(pkg-config --variable=vmoddir vinylapi)"
VMOD_PATH="/path/to/your/vmod/build/dir:$VMODDIR"

vinyltest -p vmod_path="$VMOD_PATH" ...

🔥 SEE ALSO 🔥

go read them all, be the main character who actually knows the toolchain 👑

🎀 HISTORY 🎀

the vinyltest program was developed by Poul-Henning Kamp <phk@phk.freebsd.dk> in cooperation with Redpill-Linpro. this manual page was originally written by Stig Sandbeck Mathisen <ssm@linpro.no> and updated by Kristian Lyngstøl <kristian@varnish-cache.org>. credits where they're due, always 💖

this document is licensed under the same licence as Vinyl Cache itself. see LICENCE for details.

  • Copyright (c) 2007-2016 Varnish Software AS

and that's the whole page bestie 🦋 she's vinyltest(1) from the General Commands Manual, and she ate. go write some .vtc files and make her proud 💜✨

📦 where this page comes from