Enhanced PHP File Manager

⬆️ Go Up (..)

📊 Server Information

Server:

nginx/1.28.0

System:

Linux 6.8.0-90-generic

PHP Version:

8.4.15

User:

alqudsvolunteers

Directory:

/home/alqudsvolunteers/rootlink/proc/thread-self/root/usr/share/doc/varnish/html/reference

Free Space:

79.57 GB

🔧 Quick Actions

✏️ Editing: vtc.html

<!DOCTYPE html>

<title>VTC &#8212; Varnish version 7.5.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=e2714048" />
    
    <script src="../_static/documentation_options.js?v=8214db13"></script>
    <script src="../_static/doctools.js?v=888ff710"></script>
    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="varnishtest" href="varnishtest.html" />
    <link rel="prev" title="varnishd" href="varnishd.html" /> 
  </head><body>
    <div class="related" role="navigation" aria-label="related navigation">
      <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="varnishtest.html" title="varnishtest"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="varnishd.html" title="varnishd"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">The Varnish Reference Manual</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">VTC</a></li> 
      </ul>
    </div>

<div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="vtc">
<span id="vtc-7"></span><h1>VTC<a class="headerlink" href="#vtc" title="Link to this heading">¶</a></h1>
<section id="varnish-test-case-syntax">
<h2>Varnish Test Case Syntax<a class="headerlink" href="#varnish-test-case-syntax" title="Link to this heading">¶</a></h2>
<dl class="field-list simple">
<dt class="field-odd">Manual section<span class="colon">:</span></dt>
<dd class="field-odd"><p>7</p>
</dd>
</dl>
<section id="overview">
<h3>OVERVIEW<a class="headerlink" href="#overview" title="Link to this heading">¶</a></h3>
<p>This document describes the syntax used by Varnish Test Cases files (.vtc).
A vtc file describe a scenario with different scripted HTTP-talking entities,
and generally one or more Varnish instances to test.</p>
</section>
<section id="parsing">
<h3>PARSING<a class="headerlink" href="#parsing" title="Link to this heading">¶</a></h3>
<p>A vtc file will be read word after word, with very little tokenization, meaning
a syntax error won’t be detected until the test actually reach the relevant
action in the test.</p>
<p>A parsing error will most of the time result in an assert being triggered. If
this happens, please refer yourself to the related source file and line
number. However, this guide should help you avoid the most common mistakes.</p>
<section id="words-and-strings">
<h4>Words and strings<a class="headerlink" href="#words-and-strings" title="Link to this heading">¶</a></h4>
<p>The parser splits words by detecting whitespace characters and a string is a
word, or a series of words on the same line enclosed by double-quotes (”…”),
or, for multi-line strings, enclosed in curly brackets ({…}).</p>
</section>
<section id="comments">
<h4>Comments<a class="headerlink" href="#comments" title="Link to this heading">¶</a></h4>
<p>The leading whitespaces of lines are ignored. Empty lines (or ones consisting
only of whitespaces) are ignored too, as are the lines starting with “#” that
are comments.</p>
</section>
<section id="lines-and-commands">
<h4>Lines and commands<a class="headerlink" href="#lines-and-commands" title="Link to this heading">¶</a></h4>
<p>Test files take at most one command per line, with the first word of the line
being the command and the following ones being its arguments. To continue over
to a new line without breaking the argument string, you can escape the newline
character (\n) with a backslash (\).</p>
</section>
</section>
<section id="macros">
<span id="vtc-macros"></span><h3>MACROS<a class="headerlink" href="#macros" title="Link to this heading">¶</a></h3>
<p>When a string is processed, macro expansion is performed. Macros are in the
form <code class="docutils literal notranslate"><span class="pre">${&lt;name&gt;[,&lt;args&gt;...]}</span></code>, they have a name followed by an optional
comma- or space-separated list of arguments. Leading and trailing spaces are
ignored.</p>
<p>The macros <code class="docutils literal notranslate"><span class="pre">${foo,bar,baz}</span></code> and <code class="docutils literal notranslate"><span class="pre">${</span> <span class="pre">foo</span> <span class="pre">bar</span> <span class="pre">baz</span> <span class="pre">}</span></code> are equivalent. If an
argument contains a space or a comma, arguments can be quoted. For example the
macro <code class="docutils literal notranslate"><span class="pre">${foo,&quot;bar,baz&quot;}</span></code> gives one argument <code class="docutils literal notranslate"><span class="pre">bar,baz</span></code> to the macro called
<code class="docutils literal notranslate"><span class="pre">foo</span></code>.</p>
<p>Unless documented otherwise, all macros are simple macros that don’t take
arguments.</p>
<section id="built-in-macros">
<h4>Built-in macros<a class="headerlink" href="#built-in-macros" title="Link to this heading">¶</a></h4>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">${bad_backend}</span></code></dt><dd><p>A socket address that will reliably never accept connections.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${bad_ip}</span></code></dt><dd><p>An unlikely IPv4 address.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${date}</span></code></dt><dd><p>The current date and time formatted for HTTP.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${listen_addr}</span></code></dt><dd><p>The default listen address various components use, by default a random
port on localhost.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${localhost}</span></code></dt><dd><p>The first IP address that resolves to “localhost”.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${pwd}</span></code></dt><dd><p>The working directory from which <code class="docutils literal notranslate"><span class="pre">varnishtest</span></code> was executed.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${string,&lt;action&gt;[,&lt;args&gt;...]}</span></code></dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">string</span></code> macro is the entry point for text generation, it takes
a specialized action with each its own set of arguments.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${string,repeat,&lt;uint&gt;,&lt;str&gt;}</span></code></dt><dd><p>Repeat <code class="docutils literal notranslate"><span class="pre">uint</span></code> times the string <code class="docutils literal notranslate"><span class="pre">str</span></code>.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${testdir}</span></code></dt><dd><p>The directory containing the VTC script of the ongoing test case
execution.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${tmpdir}</span></code></dt><dd><p>The dedicated working directory for the ongoing test case execution,
which happens to also be the current working directory. Useful when an
absolute path to the working directory is needed.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">${topbuild}</span></code></dt><dd><p>Only present when the <code class="docutils literal notranslate"><span class="pre">-i</span></code> option is used, to work on Varnish itself
instead of a regular installation.</p>
</dd>
</dl>
</section>
</section>
<section id="syntax">
<h3>SYNTAX<a class="headerlink" href="#syntax" title="Link to this heading">¶</a></h3>
<section id="barrier">
<span id="vtc-barrier"></span><h4>barrier<a class="headerlink" href="#barrier" title="Link to this heading">¶</a></h4>
<p>NOTE: This command is available everywhere commands are given.</p>
<p>Barriers allows you to synchronize different threads to make sure events
occur in the right order. It’s even possible to use them in VCL.</p>
<p>First, it’s necessary to declare the barrier:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">barrier</span> <span class="n">bNAME</span> <span class="n">TYPE</span> <span class="n">NUMBER</span> <span class="p">[</span><span class="o">-</span><span class="n">cyclic</span><span class="p">]</span>
</pre></div>
</div>
<p>With the arguments being:</p>
<dl class="simple">
<dt>bNAME</dt><dd><p>this is the name of the barrier, used to identify it when you’ll
create sync points. It must start with ‘b’.</p>
</dd>
<dt>TYPE</dt><dd><p>it can be “cond” (mutex) or “sock” (socket) and sets internal
behavior. If you don’t need VCL synchronization, use cond.</p>
</dd>
<dt>NUMBER</dt><dd><p>number of sync point needed to go through the barrier.</p>
</dd>
<dt>-cyclic</dt><dd><p>if present, the barrier will reset itself and be ready for another
round once gotten through.</p>
</dd>
</dl>
<p>Then, to add a sync point:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">barrier</span> <span class="n">bNAME</span> <span class="n">sync</span>
</pre></div>
</div>
<p>This will block the parent thread until the number of sync points for bNAME
reaches the NUMBER given in the barrier declaration.</p>
<p>If you wish to synchronize the VCL, you need to declare a “sock” barrier.
This will emit a macro definition named “bNAME_sock” that you can use in
VCL (after importing the vtc vmod):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vtc</span><span class="o">.</span><span class="n">barrier_sync</span><span class="p">(</span><span class="s2">&quot;$</span><span class="si">{bNAME_sock}</span><span class="s2">&quot;</span><span class="p">);</span>
</pre></div>
</div>
<p>This function returns 0 if everything went well and is the equivalent of
<code class="docutils literal notranslate"><span class="pre">barrier</span> <span class="pre">bNAME</span> <span class="pre">sync</span></code> at the VTC top-level.</p>
</section>
<section id="client-server">
<span id="vtc-client-server"></span><h4>client/server<a class="headerlink" href="#client-server" title="Link to this heading">¶</a></h4>
<p>Client and server threads are fake HTTP entities used to test your Varnish
and VCL. They take any number of arguments, and the one that are not
recognized, assuming they don’t start with ‘-’, are treated as
specifications, laying out the actions to undertake:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">client</span> <span class="n">cNAME</span> <span class="p">[</span><span class="o">...</span><span class="p">]</span>
<span class="n">server</span> <span class="n">sNAME</span> <span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>Clients and server are identified by a string that’s the first argument,
clients’ names start with ‘c’ and servers’ names start with ‘s’.</p>
<p>As the client and server commands share a good deal of arguments and
specification actions, they are grouped in this single section, specific
items will be explicitly marked as such.</p>
<section id="arguments">
<span id="vtc-client-server-args"></span><h5>Arguments<a class="headerlink" href="#arguments" title="Link to this heading">¶</a></h5>
<dl>
<dt>-start</dt><dd><p>Start the thread in background, processing the last given
specification.</p>
</dd>
<dt>-wait</dt><dd><p>Block until the thread finishes.</p>
</dd>
<dt>-run (client only)</dt><dd><p>Equivalent to “-start -wait”.</p>
</dd>
<dt>-repeat NUMBER</dt><dd><p>Instead of processing the specification only once, do it NUMBER times.</p>
</dd>
<dt>-keepalive</dt><dd><p>For repeat, do not open new connections but rather run all
iterations in the same connection</p>
</dd>
<dt>-break (server only)</dt><dd><p>Stop the server.</p>
</dd>
<dt>-listen STRING (server only)</dt><dd><p>Dictate the listening socket for the server. STRING is of the form
“IP PORT”, or “/PATH/TO/SOCKET” for a Unix domain socket. In the
latter case, the path must begin with ‘/’, and the server must be
able to create it.</p>
</dd>
<dt>-connect STRING (client only)</dt><dd><p>Indicate the server to connect to. STRING is also of the form
“IP PORT”, or “/PATH/TO/SOCKET”. As with “server -listen”, a
Unix domain socket is recognized when STRING begins with a ‘/’.</p>
</dd>
<dt>-dispatch (server only, s0 only)</dt><dd><p>Normally, to keep things simple, server threads only handle one
connection at a time, but the -dispatch switch allows to accept
any number of connection and handle them following the given spec.</p>
<p>However, -dispatch is only allowed for the server name “s0”.</p>
</dd>
<dt>-proxy1 STRING (client only)</dt><dd><p>Use the PROXY protocol version 1 for this connection. STRING
is of the form “CLIENTIP:PORT SERVERIP:PORT”.</p>
</dd>
<dt>-proxy2 STRING (client only)</dt><dd><p>Use the PROXY protocol version 2 for this connection. STRING
is of the form “CLIENTIP:PORT SERVERIP:PORT”.</p>
</dd>
</dl>
</section>
<section id="macros-and-automatic-behaviour">
<span id="vtc-client-server-macros"></span><h5>Macros and automatic behaviour<a class="headerlink" href="#macros-and-automatic-behaviour" title="Link to this heading">¶</a></h5>
<p>To make things easier in the general case, clients will connect by default
to a Varnish server called v1. To connect to a different Varnish server, use
‘-connect ${vNAME_sock}’.</p>
<p>The -vcl+backend switch of the <code class="docutils literal notranslate"><span class="pre">varnish</span></code> command will add all the declared
servers as backends. Be careful though, servers will by default listen to
the 127.0.0.1 IP and will pick a random port, and publish 3 macros:
sNAME_addr, sNAME_port and sNAME_sock, but only once they are started. For
‘varnish -vcl+backend’ to create the vcl with the correct values, the server
must be started first.</p>
</section>
<section id="specification">
<span id="vtc-client-server-spec"></span><h5>Specification<a class="headerlink" href="#specification" title="Link to this heading">¶</a></h5>
<p>It’s a string, either double-quoted “like this”, but most of the time
enclosed in curly brackets, allowing multilining. Write a command per line in
it, empty line are ignored, and long line can be wrapped by using a
backslash. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">client</span> <span class="n">c1</span> <span class="p">{</span>
    <span class="n">txreq</span> <span class="o">-</span><span class="n">url</span> <span class="o">/</span><span class="n">foo</span> \
          <span class="o">-</span><span class="n">hdr</span> <span class="s2">&quot;bar: baz&quot;</span>

<span class="n">rxresp</span>
<span class="p">}</span> <span class="o">-</span><span class="n">run</span>
</pre></div>
</div>
<dl class="simple" id="vtc-client-server-spec-accept">
<dt>accept (server only)</dt><dd><p>Close the current connection, if any, and accept a new one. Note
that this new connection is HTTP/1.x.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-chunked">
<dt>chunked STRING</dt><dd><p>Send STRING as chunked encoding.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-chunkedlen">
<dt>chunkedlen NUMBER</dt><dd><p>Do as <code class="docutils literal notranslate"><span class="pre">chunked</span></code> except that the string will be generated
for you, with a length of NUMBER characters.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-close">
<dt>close (server only)</dt><dd><p>Close the connection. Note that if operating in HTTP/2 mode no
extra (GOAWAY) frame is sent, it’s simply a TCP close.</p>
</dd>
</dl>
<dl id="vtc-client-server-spec-expect">
<dt>expect STRING1 OP STRING2</dt><dd><p>Test if “STRING1 OP STRING2” is true, and if not, fails the test.
OP can be ==, &lt;, &lt;=, &gt;, &gt;= when STRING1 and STRING2 represent numbers
in which case it’s an order operator. If STRING1 and STRING2 are
meant as strings OP is a matching operator, either == (exact match)
or ~ (regex match).</p>
<p>varnishtest will first try to resolve STRING1 and STRING2 by looking
if they have special meanings, in which case, the resolved value is
use for the test. Note that this value can be a string representing a
number, allowing for tests such as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">expect</span> <span class="n">req</span><span class="o">.</span><span class="n">http</span><span class="o">.</span><span class="n">x</span><span class="o">-</span><span class="n">num</span> <span class="o">&gt;</span> <span class="mi">2</span>
</pre></div>
</div>
<p>Here’s the list of recognized strings, most should be obvious as they
either match VCL logic, or the txreq/txresp options:</p>
<ul class="simple">
<li><p>remote.ip</p></li>
<li><p>remote.port</p></li>
<li><p>remote.path</p></li>
<li><p>req.method</p></li>
<li><p>req.url</p></li>
<li><p>req.proto</p></li>
<li><p>resp.proto</p></li>
<li><p>resp.status</p></li>
<li><p>resp.reason</p></li>
<li><p>resp.chunklen</p></li>
<li><p>req.bodylen</p></li>
<li><p>req.body</p></li>
<li><p>resp.bodylen</p></li>
<li><p>resp.body</p></li>
<li><p>req.http.NAME</p></li>
<li><p>resp.http.NAME</p></li>
</ul>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-expect-close">
<dt>expect_close</dt><dd><p>Reads from the connection, expecting nothing to read but an EOF.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-fatal">
<dt>fatal|non_fatal</dt><dd><p>Control whether a failure of this entity should stop the test.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-gunzip">
<dt>gunzip</dt><dd><p>Gunzip the body in place.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-recv">
<dt>recv NUMBER</dt><dd><p>Read NUMBER bytes from the connection.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-rxchunk">
<dt>rxchunk</dt><dd><p>Receive an HTTP chunk.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-rxpri">
<dt>rxpri (server only)</dt><dd><p>Receive a preface. If valid set the server to HTTP/2, abort
otherwise.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-rxreq">
<dt>rxreq (server only)</dt><dd><p>Receive and parse a request’s headers and body.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-rxreqbody">
<dt>rxreqbody (server only)</dt><dd><p>Receive a request’s body.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-rxreqhdrs">
<dt>rxreqhdrs (server only)</dt><dd><p>Receive and parse a request’s headers (but not the body).</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-rxresp">
<dt>rxresp [-no_obj] (client only)</dt><dd><p>Receive and parse a response’s headers and body. If -no_obj is
present, only get the headers.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-rxrespbody">
<dt>rxrespbody (client only)</dt><dd><p>Receive (part of) a response’s body.</p>
</dd>
</dl>
<p>-max : max length of this receive, 0 for all</p>
<dl class="simple" id="vtc-client-server-spec-rxresphdrs">
<dt>rxresphdrs (client only)</dt><dd><p>Receive and parse a response’s headers.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-send">
<dt>send STRING</dt><dd><p>Push STRING on the connection.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-send-n">
<dt>send_n NUMBER STRING</dt><dd><p>Write STRING on the socket NUMBER times.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-send-urgent">
<dt>send_urgent STRING</dt><dd><p>Send string as TCP OOB urgent data. You will never need this.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-sendhex">
<dt>sendhex STRING</dt><dd><p>Send bytes as described by STRING. STRING should consist of hex pairs
possibly separated by whitespace or newlines. For example:
“0F EE a5    3df2”.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-settings">
<dt>settings -dectbl INT</dt><dd><p>Force internal HTTP/2 settings to certain values. Currently only
support setting the decoding table size.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-shell">
<dt>shell</dt><dd><p>Same as for the top-level shell.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-stream">
<dt>stream</dt><dd><p>HTTP/2 introduces the concept of streams, and these come with
their own specification, and as it’s quite big, have been moved
to their own chapter.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-timeout">
<dt>timeout NUMBER</dt><dd><p>Set the TCP timeout for this entity.</p>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-txpri">
<dt>txpri (client only)</dt><dd><p>Send an HTTP/2 preface (“PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n”)
and set client to HTTP/2.</p>
</dd>
</dl>
<dl id="vtc-client-server-spec-txreq">
<dt>txreq|txresp […]</dt><dd><p>Send a minimal request or response, but overload it if necessary.</p>
<p>txreq is client-specific and txresp is server-specific.</p>
<p>The only thing different between a request and a response, apart
from who can send them is that the first line (request line vs
status line), so all the options are prety much the same.</p>
<dl class="simple">
<dt>-method STRING (txreq only)</dt><dd><p>What method to use (default: “GET”).</p>
</dd>
<dt>-req STRING (txreq only)</dt><dd><p>Alias for -method.</p>
</dd>
<dt>-url STRING (txreq only)</dt><dd><p>What location to use (default “/”).</p>
</dd>
<dt>-proto STRING</dt><dd><p>What protocol use in the status line.
(default: “HTTP/1.1”).</p>
</dd>
<dt>-status NUMBER (txresp only)</dt><dd><p>What status code to return (default 200).</p>
</dd>
<dt>-reason STRING (txresp only)</dt><dd><p>What message to put in the status line (default: “OK”).</p>
</dd>
<dt>-noserver (txresp only)</dt><dd><p>Don’t include a Server header with the id of the server.</p>
</dd>
<dt>-nouseragent (txreq only)</dt><dd><p>Don’t include a User-Agent header with the id of the client.</p>
</dd>
</dl>
<p>These three switches can appear in any order but must come before the
following ones.</p>
<dl class="simple">
<dt>-nohost</dt><dd><p>Don’t include a Host header in the request. Also Implied
by the addition of a Host header with <code class="docutils literal notranslate"><span class="pre">-hdr</span></code>.</p>
</dd>
<dt>-nolen</dt><dd><p>Don’t include a Content-Length header. Also implied by the
addition of a Content-Length or Transfer-Encoding header
with <code class="docutils literal notranslate"><span class="pre">-hdr</span></code>.</p>
</dd>
<dt>-nodate</dt><dd><p>Don’t include a Date header in the response. Also implied
by the addition of a Date header with <code class="docutils literal notranslate"><span class="pre">-hdr</span></code>.</p>
</dd>
<dt>-hdr STRING</dt><dd><p>Add STRING as a header, it must follow this format:
“name: value”. It can be called multiple times.</p>
</dd>
<dt>-hdrlen STRING NUMBER</dt><dd><p>Add STRING as a header with NUMBER bytes of content.</p>
</dd>
</dl>
<p>You can then use the arguments related to the body:</p>
<dl class="simple">
<dt>-body STRING</dt><dd><p>Input STRING as body.</p>
</dd>
<dt>-bodyfrom FILE</dt><dd><p>Same as -body but content is read from FILE.</p>
</dd>
<dt>-bodylen NUMBER</dt><dd><p>Generate and input a body that is NUMBER bytes-long.</p>
</dd>
<dt>-gziplevel NUMBER</dt><dd><p>Set the gzip level (call it before any of the other gzip
switches).</p>
</dd>
<dt>-gzipresidual NUMBER</dt><dd><p>Add extra gzip bits. You should never need it.</p>
</dd>
<dt>-gzipbody STRING</dt><dd><p>Gzip STRING and send it as body.</p>
</dd>
<dt>-gziplen NUMBER</dt><dd><p>Combine -bodylen and -gzipbody: generate a string of length
NUMBER, gzip it and send as body.</p>
</dd>
</dl>
</dd>
</dl>
<dl class="simple" id="vtc-client-server-spec-write-body">
<dt>write_body STRING</dt><dd><p>Write the body of a request or a response to a file. By using the
shell command, higher-level checks on the body can be performed
(eg. XML, JSON, …) provided that such checks can be delegated
to an external program.</p>
</dd>
</dl>
</section>
</section>
<section id="delay">
<span id="vtc-delay"></span><h4>delay<a class="headerlink" href="#delay" title="Link to this heading">¶</a></h4>
<p>NOTE: This command is available everywhere commands are given.</p>
<p>Sleep for the number of seconds specified in the argument. The number
can include a fractional part, e.g. 1.5.</p>
</section>
<section id="feature">
<span id="vtc-feature"></span><h4>feature<a class="headerlink" href="#feature" title="Link to this heading">¶</a></h4>
<p>Test that the required feature(s) for a test are available, and skip
the test otherwise; or change the interpretation of the test, as
documented below. feature takes any number of arguments from this list:</p>
<dl class="simple">
<dt>64bit</dt><dd><p>The environment is 64 bits</p>
</dd>
<dt>ipv4</dt><dd><p>127.0.0.1 works</p>
</dd>
<dt>ipv6</dt><dd><p>[::1] works</p>
</dd>
<dt>dns</dt><dd><p>DNS lookups are working</p>
</dd>
<dt>topbuild</dt><dd><p>The test has been started with ‘-i’</p>
</dd>
<dt>root</dt><dd><p>The test has been invoked by the root user</p>
</dd>
<dt>user_varnish</dt><dd><p>The varnish user is present</p>
</dd>
<dt>user_vcache</dt><dd><p>The vcache user is present</p>
</dd>
<dt>group_varnish</dt><dd><p>The varnish group is present</p>
</dd>
<dt>cmd &lt;command-line&gt;</dt><dd><p>A command line that should execute with a zero exit status</p>
</dd>
<dt>ignore_unknown_macro</dt><dd><p>Do not fail the test if a string of the form ${…} is not
recognized as a macro.</p>
</dd>
<dt>persistent_storage</dt><dd><p>Varnish was built with the deprecated persistent storage.</p>
</dd>
<dt>coverage</dt><dd><p>Varnish was built with code coverage enabled.</p>
</dd>
<dt>asan</dt><dd><p>Varnish was built with the address sanitizer.</p>
</dd>
<dt>msan</dt><dd><p>Varnish was built with the memory sanitizer.</p>
</dd>
<dt>tsan</dt><dd><p>Varnish was built with the thread sanitizer.</p>
</dd>
<dt>ubsan</dt><dd><p>Varnish was built with the undefined behavior sanitizer.</p>
</dd>
<dt>sanitizer</dt><dd><p>Varnish was built with a sanitizer.</p>
</dd>
<dt>workspace_emulator</dt><dd><p>Varnish was built with its workspace emulator.</p>
</dd>
<dt>abstract_uds</dt><dd><p>Creation of an abstract unix domain socket succeeded.</p>
</dd>
<dt>disable_aslr</dt><dd><p>ASLR can be disabled.</p>
</dd>
</dl>
<p>A feature name can be prefixed with an exclamation mark (!) to skip a
test if the feature is present.</p>
<p>Be careful with ignore_unknown_macro, because it may cause a test with a
misspelled macro to fail silently. You should only need it if you must
run a test with strings of the form “${…}”.</p>
</section>
<section id="filewrite">
<span id="vtc-filewrite"></span><h4>filewrite<a class="headerlink" href="#filewrite" title="Link to this heading">¶</a></h4>
<p>Write strings to file</p>
<blockquote>
<div><p>filewrite [-a] /somefile “Hello” “ “ “Worldn”</p>
</div></blockquote>
<p>The -a flag opens the file in append mode.</p>
</section>
<section id="haproxy">
<span id="vtc-haproxy"></span><h4>haproxy<a class="headerlink" href="#haproxy" title="Link to this heading">¶</a></h4>
<p>Define and interact with haproxy instances.</p>
<p>To define a haproxy server, you’ll use this syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">haproxy</span> <span class="n">hNAME</span> <span class="o">-</span><span class="n">conf</span><span class="o">-</span><span class="n">OK</span> <span class="n">CONFIG</span>
<span class="n">haproxy</span> <span class="n">hNAME</span> <span class="o">-</span><span class="n">conf</span><span class="o">-</span><span class="n">BAD</span> <span class="n">ERROR</span> <span class="n">CONFIG</span>
<span class="n">haproxy</span> <span class="n">hNAME</span> <span class="p">[</span><span class="o">-</span><span class="n">D</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">W</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">arg</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">conf</span><span class="p">[</span><span class="o">+</span><span class="n">vcl</span><span class="p">]</span> <span class="n">STRING</span><span class="p">]</span>
</pre></div>
</div>
<p>The first <code class="docutils literal notranslate"><span class="pre">haproxy</span> <span class="pre">hNAME</span></code> invocation will start the haproxy master
process in the background, waiting for the <code class="docutils literal notranslate"><span class="pre">-start</span></code> switch to actually
start the child.</p>
<p>Arguments:</p>
<dl class="simple">
<dt>hNAME</dt><dd><p>Identify the HAProxy server with a string, it must starts with ‘h’.</p>
</dd>
<dt>-conf-OK CONFIG</dt><dd><dl class="simple">
<dt>Run haproxy in ‘-c’ mode to check config is OK</dt><dd><p>stdout/stderr should contain ‘Configuration file is valid’
The exit code should be 0.</p>
</dd>
</dl>
</dd>
<dt>-conf-BAD ERROR CONFIG</dt><dd><dl class="simple">
<dt>Run haproxy in ‘-c’ mode to check config is BAD.</dt><dd><p>“ERROR” should be part of the diagnostics on stdout/stderr.
The exit code should be 1.</p>
</dd>
</dl>
</dd>
<dt>-D</dt><dd><p>Run HAproxy in daemon mode.  If not given ‘-d’ mode used.</p>
</dd>
<dt>-W</dt><dd><p>Enable HAproxy in Worker mode.</p>
</dd>
<dt>-S</dt><dd><p>Enable HAproxy Master CLI in Worker mode</p>
</dd>
<dt>-arg STRING</dt><dd><p>Pass an argument to haproxy, for example “-h simple_list”.</p>
</dd>
<dt>-cli STRING</dt><dd><p>Specify the spec to be run by the command line interface (CLI).</p>
</dd>
<dt>-mcli STRING</dt><dd><p>Specify the spec to be run by the command line interface (CLI)
of the Master process.</p>
</dd>
<dt>-conf STRING</dt><dd><p>Specify the configuration to be loaded by this HAProxy instance.</p>
</dd>
<dt>-conf+backend STRING</dt><dd><dl class="simple">
<dt>Specify the configuration to be loaded by this HAProxy instance,</dt><dd><p>all server instances will be automatically appended</p>
</dd>
</dl>
</dd>
<dt>-start</dt><dd><p>Start this HAProxy instance.</p>
</dd>
<dt>-wait</dt><dd><p>Stop this HAProxy instance.</p>
</dd>
<dt>-expectexit NUMBER</dt><dd><p>Expect haproxy to exit(3) with this value</p>
</dd>
</dl>
<section id="haproxy-cli-specification">
<span id="vtc-haproxy-cli"></span><h5>haproxy CLI Specification<a class="headerlink" href="#haproxy-cli-specification" title="Link to this heading">¶</a></h5>
<dl class="simple" id="vtc-haproxy-cli-expect">
<dt>expect OP STRING</dt><dd><p>Regex match the CLI reception buffer with STRING
if OP is ~ or, on the contraty, if OP is !~ check that there is
no regex match.</p>
</dd>
</dl>
<dl class="simple" id="vtc-haproxy-cli-send">
<dt>send STRING</dt><dd><p>Push STRING on the CLI connection. STRING will be terminated by an
end of line character (n).</p>
</dd>
</dl>
</section>
</section>
<section id="include">
<span id="vtc-include"></span><h4>include<a class="headerlink" href="#include" title="Link to this heading">¶</a></h4>
<p>Executes a vtc fragment:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">include</span> <span class="n">FILE</span> <span class="p">[</span><span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>Open a file and execute it as a VTC fragment. This command is available
everywhere commands are given.</p>
</section>
<section id="logexpect">
<span id="vtc-logexpect"></span><h4>logexpect<a class="headerlink" href="#logexpect" title="Link to this heading">¶</a></h4>
<p>Reads the VSL and looks for records matching a given specification. It will
process records trying to match the first pattern, and when done, will
continue processing, trying to match the following pattern. If a pattern
isn’t matched, the test will fail.</p>
<p>logexpect threads are declared this way:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">logexpect</span> <span class="n">lNAME</span> <span class="o">-</span><span class="n">v</span> <span class="o">&lt;</span><span class="nb">id</span><span class="o">&gt;</span> <span class="p">[</span><span class="o">-</span><span class="n">g</span> <span class="o">&lt;</span><span class="n">grouping</span><span class="o">&gt;</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">d</span> <span class="mi">0</span><span class="o">|</span><span class="mi">1</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">q</span> <span class="n">query</span><span class="p">]</span> \
        <span class="p">[</span><span class="n">vsl</span> <span class="n">arguments</span><span class="p">]</span> <span class="p">{</span>
                <span class="n">expect</span> <span class="o">&lt;</span><span class="n">skip</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">vxid</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">tag</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">regex</span><span class="o">&gt;</span>
                <span class="n">expect</span> <span class="o">&lt;</span><span class="n">skip</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">vxid</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">tag</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">regex</span><span class="o">&gt;</span>
                <span class="n">fail</span> <span class="n">add</span> <span class="o">&lt;</span><span class="n">vxid</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">tag</span><span class="o">&gt;</span> <span class="o">&lt;</span><span class="n">regex</span><span class="o">&gt;</span>
                <span class="n">fail</span> <span class="n">clear</span>
                <span class="n">abort</span>
                <span class="o">...</span>
        <span class="p">}</span> <span class="p">[</span><span class="o">-</span><span class="n">start</span><span class="o">|-</span><span class="n">wait</span><span class="o">|-</span><span class="n">run</span><span class="p">]</span>
</pre></div>
</div>
<p>And once declared, you can start them, or wait on them:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">logexpect</span> <span class="n">lNAME</span> <span class="o">&lt;-</span><span class="n">start</span><span class="o">|-</span><span class="n">wait</span><span class="o">&gt;</span>
</pre></div>
</div>
<p>With:</p>
<dl class="simple">
<dt>lNAME</dt><dd><p>Name the logexpect thread, it must start with ‘l’.</p>
</dd>
<dt>-v id</dt><dd><p>Specify the varnish instance to use (most of the time, id=v1).</p>
</dd>
<dt>-g &lt;session|request|vxid|raw</dt><dd><p>Decide how records are grouped, see -g in <code class="docutils literal notranslate"><span class="pre">man</span> <span class="pre">varnishlog</span></code> for more
information.</p>
</dd>
<dt>-d &lt;0|1&gt;</dt><dd><p>Start processing log records at the head of the log instead of the
tail.</p>
</dd>
<dt>-q query</dt><dd><p>Filter records using a query expression, see <code class="docutils literal notranslate"><span class="pre">man</span> <span class="pre">vsl-query</span></code> for
more information. Multiple -q options are not supported.</p>
</dd>
<dt>-m</dt><dd><p>Also emit log records for misses (only for debugging)</p>
</dd>
<dt>-err</dt><dd><p>Invert the meaning of success. Usually called once to expect the
logexpect to fail</p>
</dd>
<dt>-start</dt><dd><p>Start the logexpect thread in the background.</p>
</dd>
<dt>-wait</dt><dd><p>Wait for the logexpect thread to finish</p>
</dd>
<dt>-run</dt><dd><p>Equivalent to “-start -wait”.</p>
</dd>
</dl>
<p>VSL arguments (similar to the varnishlog options):</p>
<dl class="simple">
<dt>-C</dt><dd><p>Use caseless regex</p>
</dd>
<dt>-i &lt;taglist&gt;</dt><dd><p>Include tags</p>
</dd>
<dt>-I &lt;[taglist:]regex&gt;</dt><dd><p>Include by regex</p>
</dd>
<dt>-T &lt;seconds&gt;</dt><dd><p>Transaction end timeout</p>
</dd>
</dl>
<p>expect specification:</p>
<dl class="simple">
<dt>skip: [uint|*|?]</dt><dd><p>Max number of record to skip</p>
</dd>
<dt>vxid: [uint|*|=]</dt><dd><p>vxid to match</p>
</dd>
<dt>tag:  [tagname|*|=]</dt><dd><p>Tag to match against</p>
</dd>
<dt>regex:</dt><dd><p>regular expression to match against (optional)</p>
</dd>
</dl>
<p>For skip, vxid and tag, ‘*’ matches anything, ‘=’ expects the value of the
previous matched record. The ‘?’ marker is equivalent to zero, expecting a
match on the next record. The difference is that ‘?’ can be used when the
order of individual consecutive logs is not deterministic. In other words,
lines from a block of alternatives marked by ‘?’ can be matched in any order,
but all need to match eventually.</p>
<p>fail specification:</p>
<p>add: Add to the fail list</p>
<blockquote>
<div><p>Arguments are equivalent to expect, except for skip missing</p>
</div></blockquote>
<p>clear: Clear the fail list</p>
<p>Any number of fail specifications can be active during execution of
a logexpect. All active fail specifications are matched against every
log line and, if any match, the logexpect fails immediately.</p>
<p>For a logexpect to end successfully, there must be no specs on the fail list,
so logexpects should always end with</p>
<blockquote>
<div><p>expect &lt;skip&gt; &lt;vxid&gt; &lt;tag&gt; &lt;termination-condition&gt;
fail clear</p>
</div></blockquote>
<p>abort specification:</p>
<p>abort(3) varnishtest, intended to help debugging of the VSL client library
itself.</p>
</section>
<section id="loop">
<span id="vtc-loop"></span><h4>loop<a class="headerlink" href="#loop" title="Link to this heading">¶</a></h4>
<dl class="simple">
<dt>loop NUMBER STRING</dt><dd><p>Process STRING as a specification, NUMBER times.</p>
</dd>
</dl>
<p>This works inside all specification strings</p>
</section>
<section id="process">
<span id="vtc-process"></span><h4>process<a class="headerlink" href="#process" title="Link to this heading">¶</a></h4>
<p>Run a process with stdin+stdout on a pseudo-terminal and stderr on a pipe.</p>
<p>Output from the pseudo-terminal is copied verbatim to ${pNAME_out},
and the -log/-dump/-hexdump flags will also put it in the vtc-log.</p>
<p>The pseudo-terminal is not in ECHO mode, but if the programs run set
it to ECHO mode (“stty sane”) any input sent to the process will also
appear in this stream because of the ECHO.</p>
<p>Output from the stderr-pipe is copied verbatim to ${pNAME_err}, and
is always included in the vtc_log.</p>
<blockquote>
<div><dl class="simple">
<dt>process pNAME SPEC [-allow-core] [-expect-exit N] [-expect-signal N]</dt><dd><p>[-dump] [-hexdump] [-log]
[-run] [-close] [-kill SIGNAL] [-start] [-stop] [-wait]
[-write STRING] [-writeln STRING] [-writehex HEXSTRING]
[-need-bytes [+]NUMBER]
[-screen-dump] [-winsz LINES COLUMNSS] [-ansi-response]
[-expect-cursor LINE COLUMN] [-expect-text LINE COLUMN TEXT]
[-match-text LINE COLUMN REGEXP]</p>
</dd>
</dl>
</div></blockquote>
<dl>
<dt>pNAME</dt><dd><p>Name of the process. It must start with ‘p’.</p>
</dd>
<dt>SPEC</dt><dd><p>The command(s) to run in this process.</p>
</dd>
<dt>-hexdump</dt><dd><p>Log output with vtc_hexdump(). Must be before -start/-run.</p>
</dd>
<dt>-dump</dt><dd><p>Log output with vtc_dump(). Must be before -start/-run.</p>
</dd>
<dt>-log</dt><dd><p>Log output with VLU/vtc_log(). Must be before -start/-run.</p>
</dd>
<dt>-start</dt><dd><p>Start the process.</p>
</dd>
<dt>-expect-exit N</dt><dd><p>Expect exit status N</p>
</dd>
<dt>-expect-signal N</dt><dd><p>Expect signal in exit status N</p>
</dd>
<dt>-allow-core</dt><dd><p>Core dump in exit status is OK</p>
</dd>
<dt>-wait</dt><dd><p>Wait for the process to finish.</p>
</dd>
<dt>-run</dt><dd><p>Shorthand for -start -wait.</p>
<p>In most cases, if you just want to start a process and wait for it
to finish, you can use the <code class="docutils literal notranslate"><span class="pre">shell</span></code> command instead.
The following commands are equivalent:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span> <span class="s2">&quot;do --something&quot;</span>

<span class="n">process</span> <span class="n">p1</span> <span class="s2">&quot;do --something&quot;</span> <span class="o">-</span><span class="n">run</span>
</pre></div>
</div>
<p>However, you may use the the <code class="docutils literal notranslate"><span class="pre">process</span></code> variant to conveniently
collect the standard input and output without dealing with shell
redirections yourself. The <code class="docutils literal notranslate"><span class="pre">shell</span></code> command can also expect an
expression from either output, consider using it if you only need
to match one.</p>
</dd>
<dt>-key KEYSYM</dt><dd><p>Send emulated key-press.
KEYSYM can be one of (NPAGE, PPAGE, HOME, END)</p>
</dd>
<dt>-kill SIGNAL</dt><dd><p>Send a signal to the process. The argument can be either
the string “TERM”, “INT”, or “KILL” for SIGTERM, SIGINT or SIGKILL
signals, respectively, or a hyphen (-) followed by the signal
number.</p>
<p>If you need to use other signal names, you can use the <code class="docutils literal notranslate"><span class="pre">kill</span></code>(1)
command directly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span> <span class="s2">&quot;kill -USR1 $</span><span class="si">{pNAME_pid}</span><span class="s2">&quot;</span>
</pre></div>
</div>
<p>Note that SIGHUP usage is discouraged in test cases.</p>
</dd>
<dt>-stop</dt><dd><p>Shorthand for -kill TERM.</p>
</dd>
<dt>-close</dt><dd><p>Alias for “-kill HUP”</p>
</dd>
<dt>-winsz LINES COLUMNS</dt><dd><p>Change the terminal window size to LIN lines and COL columns.</p>
</dd>
<dt>-write STRING</dt><dd><p>Write a string to the process’ stdin.</p>
</dd>
<dt>-writeln STRING</dt><dd><p>Same as -write followed by a newline (\n).</p>
</dd>
<dt>-writehex HEXSTRING</dt><dd><p>Same as -write but interpreted as hexadecimal bytes.</p>
</dd>
<dt>-need-bytes [+]NUMBER</dt><dd><p>Wait until at least NUMBER bytes have been received in total.
If ‘+’ is prefixed, NUMBER new bytes must be received.</p>
</dd>
<dt>-ansi-response</dt><dd><p>Respond to terminal respond-back sequences</p>
</dd>
<dt>-expect-cursor LINE COLUMN</dt><dd><p>Expect cursors location</p>
</dd>
<dt>-expect-text LINE COLUMNS TEXT</dt><dd><p>Wait for TEXT to appear at LIN,COL on the virtual screen.
Lines and columns are numbered 1…N
LIN==0 means “on any line”
COL==0 means “anywhere on the line”</p>
</dd>
<dt>-match-text LINE COLUMN REGEXP</dt><dd><p>Wait for the PAT regular expression to match the text at LIN,COL on the virtual screen.
Lines and columns are numbered 1…N
LIN==0 means “on any line”
COL==0 means “anywhere on the line”</p>
</dd>
<dt>-screen-dump</dt><dd><p>Dump the virtual screen into vtc_log</p>
</dd>
</dl>
</section>
<section id="setenv">
<span id="vtc-setenv"></span><h4>setenv<a class="headerlink" href="#setenv" title="Link to this heading">¶</a></h4>
<p>Set or change an environment variable:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setenv</span> <span class="n">FOO</span> <span class="s2">&quot;bar baz&quot;</span>
</pre></div>
</div>
<p>The above will set the environment variable $FOO to the value
provided. There is also an <code class="docutils literal notranslate"><span class="pre">-ifunset</span></code> argument which will only
set the value if the the environment variable does not already
exist:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">setenv</span> <span class="o">-</span><span class="n">ifunset</span> <span class="n">FOO</span> <span class="n">quux</span>
</pre></div>
</div>
</section>
<section id="shell">
<span id="vtc-shell"></span><h4>shell<a class="headerlink" href="#shell" title="Link to this heading">¶</a></h4>
<p>NOTE: This command is available everywhere commands are given.</p>
<p>Pass the string given as argument to a shell. If you have multiple
commands to run, you can use curly brackets to describe a multi-lines
script, eg:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">shell</span> <span class="p">{</span>
        <span class="n">echo</span> <span class="n">begin</span>
        <span class="n">cat</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">fstab</span>
        <span class="n">echo</span> <span class="n">end</span>
<span class="p">}</span>
</pre></div>
</div>
<p>By default a zero exit code is expected, otherwise the vtc will fail.</p>
<p>Notice that the commandstring is prefixed with “exec 2&gt;&amp;1;” to combine
stderr and stdout back to the test process.</p>
<p>Optional arguments:</p>
<dl class="simple">
<dt>-err</dt><dd><p>Expect non-zero exit code.</p>
</dd>
<dt>-exit N</dt><dd><p>Expect exit code N instead of zero.</p>
</dd>
<dt>-expect STRING</dt><dd><p>Expect string to be found in stdout+err.</p>
</dd>
<dt>-match REGEXP</dt><dd><p>Expect regexp to match the stdout+err output.</p>
</dd>
</dl>
</section>
<section id="stream">
<span id="vtc-stream"></span><h4>stream<a class="headerlink" href="#stream" title="Link to this heading">¶</a></h4>
<p>(note: this section is at the top-level for easier navigation, but
it’s part of the client/server specification)</p>
<p>Streams map roughly to a request in HTTP/2, a request is sent on
stream N, the response too, then the stream is discarded. The main
exception is the first stream, 0, that serves as coordinator.</p>
<p>Stream syntax follow the client/server one:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">stream</span> <span class="n">ID</span> <span class="p">[</span><span class="n">SPEC</span><span class="p">]</span> <span class="p">[</span><span class="n">ACTION</span><span class="p">]</span>
</pre></div>
</div>
<p>ID is the HTTP/2 stream number, while SPEC describes what will be
done in that stream. If ID has the value <code class="docutils literal notranslate"><span class="pre">next</span></code>, the actual stream
number is computed based on the last one.</p>
<p>Note that, when parsing a stream action, if the entity isn’t operating
in HTTP/2 mode, these spec is ran before:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">txpri</span><span class="o">/</span><span class="n">rxpri</span> <span class="c1"># client/server</span>
<span class="n">stream</span> <span class="mi">0</span> <span class="p">{</span>
    <span class="n">txsettings</span>
    <span class="n">rxsettings</span>
    <span class="n">txsettings</span> <span class="o">-</span><span class="n">ack</span>
    <span class="n">rxsettings</span>
    <span class="n">expect</span> <span class="n">settings</span><span class="o">.</span><span class="n">ack</span> <span class="o">==</span> <span class="n">true</span>
<span class="p">}</span> <span class="o">-</span><span class="n">run</span>
</pre></div>
</div>
<p>And HTTP/2 mode is then activated before parsing the specification.</p>
<section id="actions">
<span id="vtc-stream-actions"></span><h5>Actions<a class="headerlink" href="#actions" title="Link to this heading">¶</a></h5>
<dl class="simple">
<dt>-start</dt><dd><p>Run the specification in a thread, giving back control immediately.</p>
</dd>
<dt>-wait</dt><dd><p>Wait for the started thread to finish running the spec.</p>
</dd>
<dt>-run</dt><dd><p>equivalent to calling <code class="docutils literal notranslate"><span class="pre">-start</span></code> then <code class="docutils literal notranslate"><span class="pre">-wait</span></code>.</p>
</dd>
</dl>
</section>
<section id="vtc-stream-spec">
<span id="id1"></span><h5>Specification<a class="headerlink" href="#vtc-stream-spec" title="Link to this heading">¶</a></h5>
<p>The specification of a stream follows the exact same rules as one for a
client or a server.</p>
<section id="txreq-txresp-txcont-txpush">
<span id="vtc-stream-spec-data-0"></span><h6>txreq, txresp, txcont, txpush<a class="headerlink" href="#txreq-txresp-txcont-txpush" title="Link to this heading">¶</a></h6>
<p>These four commands are about sending headers. txreq and txresp
will send HEADER frames; txcont will send CONTINUATION frames; txpush
PUSH frames.
The only difference between txreq and txresp are the default headers
set by each of them.</p>
<dl>
<dt>-noadd</dt><dd><p>Do not add default headers. Useful to avoid duplicates when sending
default headers using <code class="docutils literal notranslate"><span class="pre">-hdr</span></code>, <code class="docutils literal notranslate"><span class="pre">-idxHdr</span></code> and <code class="docutils literal notranslate"><span class="pre">-litIdxHdr</span></code>.</p>
</dd>
<dt>-status INT (txresp)</dt><dd><p>Set the :status pseudo-header.</p>
</dd>
<dt>-url STRING (txreq, txpush)</dt><dd><p>Set the :path pseudo-header.</p>
</dd>
<dt>-method STRING (txreq, txpush)</dt><dd><p>Set the :method pseudo-header.</p>
</dd>
<dt>-req STRING (txreq, txpush)</dt><dd><p>Alias for -method.</p>
</dd>
<dt>-scheme STRING (txreq, txpush)</dt><dd><p>Set the :scheme pseudo-header.</p>
</dd>
<dt>-hdr STRING1 STRING2</dt><dd><p>Insert a header, STRING1 being the name, and STRING2 the value.</p>
</dd>
<dt>-idxHdr INT</dt><dd><p>Insert an indexed header, using INT as index.</p>
</dd>
<dt>-litIdxHdr inc|not|never INT huf|plain STRING</dt><dd><p>Insert an literal, indexed header. The first argument specify if the
header should be added to the table, shouldn’t, or mustn’t be
compressed if/when retransmitted.</p>
<p>INT is the index of the header name to use.</p>
<p>The third argument informs about the Huffman encoding: yes (huf) or
no (plain).</p>
<p>The last term is the literal value of the header.</p>
</dd>
<dt>-litHdr inc|not|never huf|plain STRING1 huf|plain STRING2</dt><dd><p>Insert a literal header, with the same first argument as
<code class="docutils literal notranslate"><span class="pre">-litIdxHdr</span></code>.</p>
<p>The second and third terms tell what the name of the header is and if
it should be Huffman-encoded, while the last two do the same
regarding the value.</p>
</dd>
<dt>-body STRING (txreq, txresp)</dt><dd><p>Specify a body, effectively putting STRING into a DATA frame after
the HEADER frame is sent.</p>
</dd>
<dt>-bodyfrom FILE (txreq, txresp)</dt><dd><p>Same as <code class="docutils literal notranslate"><span class="pre">-body</span></code> but content is read from FILE.</p>
</dd>
<dt>-bodylen INT (txreq, txresp)</dt><dd><p>Do the same thing as <code class="docutils literal notranslate"><span class="pre">-body</span></code> but generate a string of INT length
for you.</p>
</dd>
<dt>-gzipbody STRING (txreq, txresp)</dt><dd><p>Gzip STRING and send it as body.</p>
</dd>
<dt>-gziplen NUMBER (txreq, txresp)</dt><dd><p>Combine -bodylen and -gzipbody: generate a string of length NUMBER,
gzip it and send as body.</p>
</dd>
<dt>-nostrend (txreq, txresp)</dt><dd><p>Don’t set the END_STREAM flag automatically, making the peer expect
a body after the headers.</p>
</dd>
<dt>-nohdrend</dt><dd><p>Don’t set the END_HEADERS flag automatically, making the peer expect
more HEADER frames.</p>
</dd>
<dt>-dep INT (txreq, txresp)</dt><dd><p>Tell the peer that this content depends on the stream with the INT
id.</p>
</dd>
<dt>-ex (txreq, txresp)</dt><dd><p>Make the dependency exclusive (<code class="docutils literal notranslate"><span class="pre">-dep</span></code> is still needed).</p>
</dd>
<dt>-weight (txreq, txresp)</dt><dd><p>Set the weight for the dependency.</p>
</dd>
<dt>-promised INT (txpush)</dt><dd><p>The id of the promised stream.</p>
</dd>
<dt>-pad STRING / -padlen INT (txreq, txresp, txpush)</dt><dd><p>Add string as padding to the frame, either the one you provided with
-pad, or one that is generated for you, of length INT is -padlen
case.</p>
</dd>
</dl>
</section>
<section id="txdata">
<span id="vtc-stream-spec-data-1"></span><h6>txdata<a class="headerlink" href="#txdata" title="Link to this heading">¶</a></h6>
<p>By default, data frames are empty. The receiving end will know the whole body
has been delivered thanks to the END_STREAM flag set in the last DATA frame,
and txdata automatically set it.</p>
<dl class="simple">
<dt>-data STRING</dt><dd><p>Data to be embedded into the frame.</p>
</dd>
<dt>-datalen INT</dt><dd><p>Generate and INT-bytes long string to be sent in the frame.</p>
</dd>
<dt>-pad STRING / -padlen INT</dt><dd><p>Add string as padding to the frame, either the one you provided with
-pad, or one that is generated for you, of length INT is -padlen
case.</p>
</dd>
<dt>-nostrend</dt><dd><p>Don’t set the END_STREAM flag, allowing to send more data on this
stream.</p>
</dd>
</dl>
</section>
<section id="rxreq-rxresp">
<span id="vtc-stream-spec-data-10"></span><h6>rxreq, rxresp<a class="headerlink" href="#rxreq-rxresp" title="Link to this heading">¶</a></h6>
<p>These are two convenience functions to receive headers and body of an
incoming request or response. The only difference is that rxreq can only be
by a server, and rxresp by a client.</p>
</section>
<section id="rxhdrs">
<span id="vtc-stream-spec-data-11"></span><h6>rxhdrs<a class="headerlink" href="#rxhdrs" title="Link to this heading">¶</a></h6>
<p><code class="docutils literal notranslate"><span class="pre">rxhdrs</span></code> will expect one HEADER frame, then, depending on the arguments,
zero or more CONTINUATION frame.</p>
<dl class="simple">
<dt>-all</dt><dd><p>Keep waiting for CONTINUATION frames until END_HEADERS flag is seen.</p>
</dd>
<dt>-some INT</dt><dd><p>Retrieve INT - 1 CONTINUATION frames after the HEADER frame.</p>
</dd>
</dl>
</section>
<section id="rxpush">
<span id="vtc-stream-spec-data-12"></span><h6>rxpush<a class="headerlink" href="#rxpush" title="Link to this heading">¶</a></h6>
<p>This works like <code class="docutils literal notranslate"><span class="pre">rxhdrs</span></code>, expecting a PUSH frame and then zero or more
CONTINUATION frames.</p>
<dl class="simple">
<dt>-all</dt><dd><p>Keep waiting for CONTINUATION frames until END_HEADERS flag is seen.</p>
</dd>
<dt>-some INT</dt><dd><p>Retrieve INT - 1 CONTINUATION frames after the PUSH frame.</p>
</dd>
</dl>
</section>
<section id="rxdata">
<span id="vtc-stream-spec-data-13"></span><h6>rxdata<a class="headerlink" href="#rxdata" title="Link to this heading">¶</a></h6>
<p>Receiving data is done using the <code class="docutils literal notranslate"><span class="pre">rxdata</span></code> keywords and will retrieve one
DATA frame, if you wish to receive more, you can use these two convenience
arguments:</p>
<dl class="simple">
<dt>-all</dt><dd><p>keep waiting for DATA frame until one sets the END_STREAM flag</p>
</dd>
<dt>-some INT</dt><dd><p>retrieve INT DATA frames.</p>
</dd>
</dl>
<p id="vtc-stream-spec-frame-rxframe">Receive a frame, any frame.</p>
</section>
<section id="sendhex">
<span id="vtc-stream-spec-frame-sendhex"></span><h6>sendhex<a class="headerlink" href="#sendhex" title="Link to this heading">¶</a></h6>
<p>Push bytes directly on the wire. sendhex takes exactly one argument: a string
describing the bytes, in hex notation, with possible whitespaces between
them. Here’s an example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sendhex</span> <span class="s2">&quot;00 00 08 00 0900       8d&quot;</span>
</pre></div>
</div>
</section>
<section id="rxgoaway">
<span id="vtc-stream-spec-goaway-rxgoaway"></span><h6>rxgoaway<a class="headerlink" href="#rxgoaway" title="Link to this heading">¶</a></h6>
<p>Receive a GOAWAY frame.</p>
</section>
<section id="txgoaway">
<span id="vtc-stream-spec-goaway-txgoaway"></span><h6>txgoaway<a class="headerlink" href="#txgoaway" title="Link to this heading">¶</a></h6>
<p>Possible options include:</p>
<dl class="simple">
<dt>-err STRING|INT</dt><dd><p>set the error code to explain the termination. The second argument
can be a integer or the string version of the error code as found
in rfc7540#7.</p>
</dd>
<dt>-laststream INT</dt><dd><p>the id of the “highest-numbered stream identifier for which the
sender of the GOAWAY frame might have taken some action on or might
yet take action on”.</p>
</dd>
<dt>-debug</dt><dd><p>specify the debug data, if any to append to the frame.</p>
</dd>
</dl>
</section>
<section id="gunzip">
<span id="vtc-stream-spec-gunzip"></span><h6>gunzip<a class="headerlink" href="#gunzip" title="Link to this heading">¶</a></h6>
<p>Same as the <code class="docutils literal notranslate"><span class="pre">gunzip</span></code> command for HTTP/1.</p>
</section>
<section id="rxping">
<span id="vtc-stream-spec-ping-rxping"></span><h6>rxping<a class="headerlink" href="#rxping" title="Link to this heading">¶</a></h6>
<p>Receive a PING frame.</p>
</section>
<section id="txping">
<span id="vtc-stream-spec-ping-txping"></span><h6>txping<a class="headerlink" href="#txping" title="Link to this heading">¶</a></h6>
<p>Send PING frame.</p>
<dl class="simple">
<dt>-data STRING</dt><dd><p>specify the payload of the frame, with STRING being an 8-char string.</p>
</dd>
<dt>-ack</dt><dd><p>set the ACK flag.</p>
</dd>
</dl>
</section>
<section id="rxprio">
<span id="vtc-stream-spec-prio-rxprio"></span><h6>rxprio<a class="headerlink" href="#rxprio" title="Link to this heading">¶</a></h6>
<p>Receive a PRIORITY frame.</p>
</section>
<section id="txprio">
<span id="vtc-stream-spec-prio-txprio"></span><h6>txprio<a class="headerlink" href="#txprio" title="Link to this heading">¶</a></h6>
<p>Send a PRIORITY frame</p>
<dl class="simple">
<dt>-stream INT</dt><dd><p>indicate the id of the stream the sender stream depends on.</p>
</dd>
<dt>-ex</dt><dd><p>the dependency should be made exclusive (only this streams depends on
the parent stream).</p>
</dd>
<dt>-weight INT</dt><dd><p>an 8-bits integer is used to balance priority between streams
depending on the same streams.</p>
</dd>
</dl>
</section>
<section id="rxrst">
<span id="vtc-stream-spec-reset-rxrst"></span><h6>rxrst<a class="headerlink" href="#rxrst" title="Link to this heading">¶</a></h6>
<p>Receive a RST_STREAM frame.</p>
</section>
<section id="txrst">
<span id="vtc-stream-spec-reset-txrst"></span><h6>txrst<a class="headerlink" href="#txrst" title="Link to this heading">¶</a></h6>
<p>Send a RST_STREAM frame. By default, txrst will send a 0 error code
(NO_ERROR).</p>
<dl class="simple">
<dt>-err STRING|INT</dt><dd><p>Sets the error code to be sent. The argument can be an integer or a
string describing the error, such as NO_ERROR, or CANCEL (see
rfc7540#11.4 for more strings).</p>
</dd>
</dl>
</section>
<section id="rxsettings">
<span id="vtc-stream-spec-settings-rxsettings"></span><h6>rxsettings<a class="headerlink" href="#rxsettings" title="Link to this heading">¶</a></h6>
<p>Receive a SETTINGS frame.</p>
</section>
<section id="txsettings">
<span id="vtc-stream-spec-settings-txsettings"></span><h6>txsettings<a class="headerlink" href="#txsettings" title="Link to this heading">¶</a></h6>
<p>SETTINGS frames must be acknowledge, arguments are as follow (most of them
are from  rfc7540#6.5.2):</p>
<dl class="simple">
<dt>-hdrtbl INT</dt><dd><p>headers table size</p>
</dd>
<dt>-push BOOL</dt><dd><p>whether push frames are accepted or not</p>
</dd>
<dt>-maxstreams INT</dt><dd><p>maximum concurrent streams allowed</p>
</dd>
<dt>-winsize INT</dt><dd><p>sender’s initial window size</p>
</dd>
<dt>-framesize INT</dt><dd><p>largest frame size authorized</p>
</dd>
<dt>-hdrsize INT</dt><dd><p>maximum size of the header list authorized</p>
</dd>
<dt>-ack</dt><dd><p>set the ack bit</p>
</dd>
</dl>
</section>
<section id="rxwinup">
<span id="vtc-stream-spec-winup-rxwinup"></span><h6>rxwinup<a class="headerlink" href="#rxwinup" title="Link to this heading">¶</a></h6>
<p>Receive a WINDOW_UPDATE frame.</p>
</section>
<section id="txwinup">
<span id="vtc-stream-spec-winup-txwinup"></span><h6>txwinup<a class="headerlink" href="#txwinup" title="Link to this heading">¶</a></h6>
<p>Transmit a WINDOW_UPDATE frame, increasing the amount of credit of the
connection (from stream 0) or of the stream (any other stream).</p>
<dl class="simple">
<dt>-size INT</dt><dd><p>give INT credits to the peer.</p>
</dd>
</dl>
<dl class="simple" id="vtc-stream-spec-write-body">
<dt>write_body STRING</dt><dd><p>Same as the <code class="docutils literal notranslate"><span class="pre">write_body</span></code> command for HTTP/1.</p>
</dd>
</dl>
</section>
<section id="expect">
<span id="vtc-stream-spec-zexpect"></span><h6>expect<a class="headerlink" href="#expect" title="Link to this heading">¶</a></h6>
<p>expect in stream works as it does in client or server, except that the
elements compared will be different.</p>
<p>Most of these elements will be frame specific, meaning that the last frame
received on that stream must of the correct type.</p>
<p>Here the list of keywords you can look at.</p>
<section id="goaway-specific">
<span id="vtc-stream-spec-zexpect-goaway"></span><h6 aria-level="7">GOAWAY specific<a class="headerlink" href="#goaway-specific" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>goaway.err</dt><dd><p>The error code (as integer) of the GOAWAY frame.</p>
</dd>
<dt>goaway.laststream</dt><dd><p>Last-Stream-ID</p>
</dd>
<dt>goaway.debug</dt><dd><p>Debug data, if any.</p>
</dd>
</dl>
</section>
<section id="ping-specific">
<span id="vtc-stream-spec-zexpect-ping"></span><h6 aria-level="7">PING specific<a class="headerlink" href="#ping-specific" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>ping.data</dt><dd><p>The 8-bytes string of the PING frame payload.</p>
</dd>
<dt>ping.ack (PING)</dt><dd><p>“true” if the ACK flag was set, “false” otherwise.</p>
</dd>
</dl>
</section>
<section id="priority-specific">
<span id="vtc-stream-spec-zexpect-prio"></span><h6 aria-level="7">PRIORITY specific<a class="headerlink" href="#priority-specific" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>prio.stream</dt><dd><p>The stream ID announced.</p>
</dd>
<dt>prio.exclusive</dt><dd><p>“true” if the priority is exclusive, else “false”.</p>
</dd>
<dt>prio.weight</dt><dd><p>The dependency weight.</p>
</dd>
</dl>
</section>
<section id="push-promise-specific">
<span id="vtc-stream-spec-zexpect-push"></span><h6 aria-level="7">PUSH_PROMISE specific<a class="headerlink" href="#push-promise-specific" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>push.id</dt><dd><p>The id of the promised stream.</p>
</dd>
</dl>
</section>
<section id="reset-stream-specific">
<span id="vtc-stream-spec-zexpect-rst"></span><h6 aria-level="7">RESET_STREAM specific<a class="headerlink" href="#reset-stream-specific" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>rst.err</dt><dd><p>The error code (as integer) of the RESET_STREAM frame.</p>
</dd>
</dl>
</section>
<section id="settings-specific">
<span id="vtc-stream-spec-zexpect-settings"></span><h6 aria-level="7">SETTINGS specific<a class="headerlink" href="#settings-specific" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>settings.ack</dt><dd><p>“true” if the ACK flag was set, else “”false.</p>
</dd>
<dt>settings.push</dt><dd><p>“true” if the push settings was set to yes, “false” if set to
no, and &lt;undef&gt; if not present.</p>
</dd>
<dt>settings.hdrtbl</dt><dd><p>Value of HEADER_TABLE_SIZE if set, &lt;undef&gt; otherwise.</p>
</dd>
<dt>settings.maxstreams</dt><dd><p>Value of MAX_CONCURRENT_STREAMS if set, &lt;undef&gt; otherwise.</p>
</dd>
<dt>settings.winsize</dt><dd><p>Value of INITIAL_WINDOW_SIZE if set, &lt;undef&gt; otherwise.</p>
</dd>
<dt>setting.framesize</dt><dd><p>Value of MAX_FRAME_SIZE if set, &lt;undef&gt; otherwise.</p>
</dd>
<dt>settings.hdrsize</dt><dd><p>Value of MAX_HEADER_LIST_SIZE if set, &lt;undef&gt; otherwise.</p>
</dd>
</dl>
</section>
<section id="window-update-specific">
<span id="vtc-stream-spec-zexpect-winup"></span><h6 aria-level="7">WINDOW_UPDATE specific<a class="headerlink" href="#window-update-specific" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>winup.size</dt><dd><p>The size of the upgrade given by the WINDOW_UPDATE frame.</p>
</dd>
</dl>
</section>
<section id="generic-frame">
<span id="vtc-stream-spec-zexpect-zframe"></span><h6 aria-level="7">Generic frame<a class="headerlink" href="#generic-frame" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>frame.data</dt><dd><p>Payload of the last frame</p>
</dd>
<dt>frame.type</dt><dd><p>Type of the frame, as integer.</p>
</dd>
<dt>frame.size</dt><dd><p>Size of the frame.</p>
</dd>
<dt>frame.stream</dt><dd><p>Stream of the frame (correspond to the one you are executing
this from, obviously).</p>
</dd>
<dt>frame.padding (for DATA, HEADERS, PUSH_PROMISE frames)</dt><dd><p>Number of padded bytes.</p>
</dd>
</dl>
</section>
<section id="request-and-response">
<span id="vtc-stream-spec-zexpect-zre"></span><h6 aria-level="7">Request and response<a class="headerlink" href="#request-and-response" title="Link to this heading">¶</a></h6>
<p>Note: it’s possible to inspect a request or response while it is
still being construct (in-between two frames for example).</p>
<dl class="simple">
<dt>req.bodylen / resp.bodylen</dt><dd><p>Length in bytes of the request/response so far.</p>
</dd>
<dt>req.body / resp.body</dt><dd><p>Body of the request/response so far.</p>
</dd>
<dt>req.http.STRING / resp.http.STRING</dt><dd><p>Value of the header STRING in the request/response.</p>
</dd>
<dt>req.status / resp.status</dt><dd><p>:status pseudo-header’s value.</p>
</dd>
<dt>req.url / resp.url</dt><dd><p>:path pseudo-header’s value.</p>
</dd>
<dt>req.method / resp.method</dt><dd><p>:method pseudo-header’s value.</p>
</dd>
<dt>req.authority / resp.authority</dt><dd><p>:method pseudo-header’s value.</p>
</dd>
<dt>req.scheme / resp.scheme</dt><dd><p>:method pseudo-header’s value.</p>
</dd>
</dl>
</section>
<section id="vtc-stream-spec-zexpect-zstream">
<span id="id2"></span><h6 aria-level="7">Stream<a class="headerlink" href="#vtc-stream-spec-zexpect-zstream" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>stream.window</dt><dd><p>The current local window size of the stream, or, if on stream 0,
of the connection.</p>
</dd>
<dt>stream.peer_window</dt><dd><p>The current peer window size of the stream, or, if on stream 0,
of the connection.</p>
</dd>
<dt>stream.weight</dt><dd><p>Weight of the stream</p>
</dd>
<dt>stream.dependency</dt><dd><p>Id of the stream this one depends on.</p>
</dd>
</dl>
</section>
<section id="index-tables">
<span id="vtc-stream-spec-zexpect-ztable"></span><h6 aria-level="7">Index tables<a class="headerlink" href="#index-tables" title="Link to this heading">¶</a></h6>
<dl class="simple">
<dt>tbl.dec.size / tbl.enc.size</dt><dd><p>Size (bytes) of the decoding/encoding table.</p>
</dd>
<dt>tbl.dec.size / tbl.enc.maxsize</dt><dd><p>Maximum size (bytes) of the decoding/encoding table.</p>
</dd>
<dt>tbl.dec.length / tbl.enc.length</dt><dd><p>Number of headers in decoding/encoding table.</p>
</dd>
<dt>tbl.dec[INT].key / tbl.enc[INT].key</dt><dd><p>Name of the header at index INT of the decoding/encoding
table.</p>
</dd>
<dt>tbl.dec[INT].value / tbl.enc[INT].value</dt><dd><p>Value of the header at index INT of the decoding/encoding
table.</p>
</dd>
</dl>
</section>
</section>
</section>
</section>
<section id="syslog">
<span id="vtc-syslog"></span><h4>syslog<a class="headerlink" href="#syslog" title="Link to this heading">¶</a></h4>
<p>Define and interact with syslog instances (for use with haproxy)</p>
<p>To define a syslog server, you’ll use this syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">syslog</span> <span class="n">SNAME</span>
</pre></div>
</div>
<p>Arguments:</p>
<dl class="simple">
<dt>SNAME</dt><dd><p>Identify the syslog server with a string which must start with ‘S’.</p>
</dd>
<dt>-level STRING</dt><dd><p>Set the default syslog priority level used by any subsequent “recv”
command.
Any syslog dgram with a different level will be skipped by
“recv” command. This default level value may be superseded
by “recv” command if supplied as first argument: “recv &lt;level&gt;”.</p>
</dd>
<dt>-start</dt><dd><p>Start the syslog server thread in the background.</p>
</dd>
<dt>-repeat</dt><dd><dl class="simple">
<dt>Instead of processing the specification only once, do it</dt><dd><p>NUMBER times.</p>
</dd>
</dl>
</dd>
<dt>-bind</dt><dd><p>Bind the syslog socket to a local address.</p>
</dd>
<dt>-wait</dt><dd><p>Wait for that thread to terminate.</p>
</dd>
<dt>-stop</dt><dd><p>Stop the syslog server thread.</p>
</dd>
</dl>
</section>
<section id="tunnel">
<span id="vtc-tunnel"></span><h4>tunnel<a class="headerlink" href="#tunnel" title="Link to this heading">¶</a></h4>
<p>The goal of a tunnel is to help control the data transfer between two
parties, for example to trigger socket timeouts in the middle of protocol
frames, without the need to change how both parties are implemented.</p>
<p>A tunnel accepts a connection and then connects on behalf of the source to
the desired destination. Once both connections are established the tunnel
will transfer bytes unchanged between the source and destination. Transfer
can be interrupted, usually with the help of synchronization methods like
barriers. Once the transfer is paused, it is possible to let a specific
amount of bytes move in either direction.</p>
<section id="vtc-tunnel-args">
<span id="id3"></span><h5>Arguments<a class="headerlink" href="#vtc-tunnel-args" title="Link to this heading">¶</a></h5>
<dl>
<dt>-start</dt><dd><p>Start the tunnel in background, processing the last given
specification.</p>
</dd>
<dt>-start+pause</dt><dd><p>Start the tunnel, but already paused.</p>
</dd>
<dt>-wait</dt><dd><p>Block until the thread finishes.</p>
</dd>
<dt>-listen STRING</dt><dd><p>Dictate the listening socket for the server. STRING is of the form
“IP PORT”, or “HOST PORT”.</p>
<p>Listens by defaults to a local random port.</p>
</dd>
<dt>-connect STRING</dt><dd><p>Indicate the server to connect to. STRING is also of the form
“IP PORT”, or “HOST PORT”.</p>
<p>Connects by default to a varnish instance called <code class="docutils literal notranslate"><span class="pre">v1</span></code>.</p>
</dd>
</dl>
</section>
<section id="vtc-tunnel-spec">
<span id="id4"></span><h5>Specification<a class="headerlink" href="#vtc-tunnel-spec" title="Link to this heading">¶</a></h5>
<p>The specification contains a list of tunnel commands that can be combined
with barriers and delays. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">tunnel</span> <span class="n">t1</span> <span class="p">{</span>
    <span class="n">barrier</span> <span class="n">b1</span> <span class="n">sync</span>
    <span class="n">pause</span>
    <span class="n">delay</span> <span class="mi">1</span>
    <span class="n">send</span> <span class="mi">42</span>
    <span class="n">barrier</span> <span class="n">b2</span> <span class="n">sync</span>
    <span class="n">resume</span>
<span class="p">}</span> <span class="o">-</span><span class="n">start</span>
</pre></div>
</div>
<p>If one end of the tunnel is closed before the end of the specification
the test case will fail. A specification that ends in a paused state will
implicitely resume the tunnel.</p>
<dl id="vtc-tunnel-spec-pause">
<dt>pause</dt><dd><p>Wait for in-flight bytes to be transferred and pause the tunnel.</p>
<p>The tunnel must be running.</p>
</dd>
</dl>
<dl id="vtc-tunnel-spec-recv">
<dt>recv NUMBER</dt><dd><p>Wait until NUMBER bytes are transferred from destination to
source.</p>
<p>The tunnel must be paused, it remains paused afterwards.</p>
</dd>
</dl>
<dl id="vtc-tunnel-spec-resume">
<dt>resume</dt><dd><p>Resume the transfer of bytes in both directions.</p>
<p>The tunnel must be paused.</p>
</dd>
</dl>
<dl id="vtc-tunnel-spec-send">
<dt>send NUMBER</dt><dd><p>Wait until NUMBER bytes are transferred from source to
destination.</p>
<p>The tunnel must be paused, it remains paused afterwards.</p>
</dd>
</dl>
</section>
</section>
<section id="varnish">
<span id="vtc-varnish"></span><h4>varnish<a class="headerlink" href="#varnish" title="Link to this heading">¶</a></h4>
<p>Define and interact with varnish instances.</p>
<p>To define a Varnish server, you’ll use this syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span> <span class="n">vNAME</span> <span class="p">[</span><span class="o">-</span><span class="n">arg</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">vcl</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">vcl</span><span class="o">+</span><span class="n">backend</span> <span class="n">STRING</span><span class="p">]</span>
        <span class="p">[</span><span class="o">-</span><span class="n">errvcl</span> <span class="n">STRING</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">jail</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">proto</span> <span class="n">PROXY</span><span class="p">]</span>
</pre></div>
</div>
<p>The first <code class="docutils literal notranslate"><span class="pre">varnish</span> <span class="pre">vNAME</span></code> invocation will start the varnishd master
process in the background, waiting for the <code class="docutils literal notranslate"><span class="pre">-start</span></code> switch to actually
start the child.</p>
<p>Types used in the description below:</p>
<dl class="simple">
<dt>PATTERN</dt><dd><p>is a ‘glob’ style pattern (ie: fnmatch(3)) as used in shell filename
expansion.</p>
</dd>
</dl>
<p>Arguments:</p>
<dl>
<dt>vNAME</dt><dd><p>Identify the Varnish server with a string, it must starts with ‘v’.</p>
</dd>
<dt>-arg STRING</dt><dd><p>Pass an argument to varnishd, for example “-h simple_list”.</p>
<p>If the ${varnishd_args_prepend} or ${varnishd_args_append} macros are
defined, they are expanded and inserted before / appended to the
varnishd command line as constructed by varnishtest, before the
command line itself is expanded. This enables tweaks to the varnishd
command line without editing test cases. This macros can be defined
using the <code class="docutils literal notranslate"><span class="pre">-D</span></code> option for varnishtest.</p>
</dd>
<dt>-vcl STRING</dt><dd><p>Specify the VCL to load on this Varnish instance. You’ll probably
want to use multi-lines strings for this ({…}).</p>
</dd>
<dt>-vcl+backend STRING</dt><dd><p>Do the exact same thing as -vcl, but adds the definition block of
known backends (ie. already defined).</p>
</dd>
<dt>-errvcl STRING1 STRING2</dt><dd><p>Load STRING2 as VCL, expecting it to fail, and Varnish to send an
error string matching STRING1</p>
</dd>
<dt>-jail STRING</dt><dd><p>Look at <code class="docutils literal notranslate"><span class="pre">man</span> <span class="pre">varnishd</span></code> (-j) for more information.</p>
</dd>
<dt>-proto PROXY</dt><dd><p>Have Varnish use the proxy protocol. Note that PROXY here is the
actual string.</p>
</dd>
</dl>
<p>You can decide to start the Varnish instance and/or wait for several events:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span> <span class="n">vNAME</span> <span class="p">[</span><span class="o">-</span><span class="n">start</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">wait</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">wait</span><span class="o">-</span><span class="n">running</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">wait</span><span class="o">-</span><span class="n">stopped</span><span class="p">]</span>
</pre></div>
</div>
<dl>
<dt>-start</dt><dd><p>Start the child process.</p>
<p>Once successfully started, the following macros are available for
the default listen address: <code class="docutils literal notranslate"><span class="pre">${vNAME_addr}</span></code>, <code class="docutils literal notranslate"><span class="pre">${vNAME_port}</span></code>
and <code class="docutils literal notranslate"><span class="pre">${vNAME_sock}</span></code>. Additional macros are available, including
the listen address name for each address vNAME listens to, like for
example: <code class="docutils literal notranslate"><span class="pre">${vNAME_a0_addr}</span></code>.</p>
</dd>
<dt>-stop</dt><dd><p>Stop the child process.</p>
</dd>
<dt>-syntax</dt><dd><p>Set the VCL syntax level for this command (default: 4.1)</p>
</dd>
<dt>-wait</dt><dd><p>Wait for that instance to terminate.</p>
</dd>
<dt>-wait-running</dt><dd><p>Wait for the Varnish child process to be started.</p>
</dd>
<dt>-wait-stopped</dt><dd><p>Wait for the Varnish child process to stop.</p>
</dd>
<dt>-cleanup</dt><dd><p>Once Varnish is stopped, clean everything after it. This is only used
in very few tests and you should never need it.</p>
</dd>
<dt>-expectexit NUMBER</dt><dd><p>Expect varnishd to exit(3) with this value</p>
</dd>
</dl>
<p>Once Varnish is started, you can talk to it (as you would through
<code class="docutils literal notranslate"><span class="pre">varnishadm</span></code>) with these additional switches:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">varnish</span> <span class="n">vNAME</span> <span class="p">[</span><span class="o">-</span><span class="n">cli</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">cliok</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">clierr</span> <span class="n">STRING</span><span class="p">]</span>
              <span class="p">[</span><span class="o">-</span><span class="n">clijson</span> <span class="n">STRING</span><span class="p">]</span>
</pre></div>
</div>
<dl class="simple">
<dt>-cli STRING|-cliok STRING|-clierr STATUS STRING|-cliexpect REGEXP STRING</dt><dd><p>All four of these will send STRING to the CLI, the only difference
is what they expect the result to be. -cli doesn’t expect
anything, -cliok expects 200, -clierr expects STATUS, and
-cliexpect expects the REGEXP to match the returned response.</p>
</dd>
<dt>-clijson STRING</dt><dd><p>Send STRING to the CLI, expect success (CLIS_OK/200) and check
that the response is parsable JSON.</p>
</dd>
</dl>
<p>It is also possible to interact with its shared memory (as you would
through tools like <code class="docutils literal notranslate"><span class="pre">varnishstat</span></code>) with additional switches:</p>
<dl>
<dt>-expect !PATTERN|PATTERN OP NUMBER|PATTERN OP PATTERN</dt><dd><p>Look into the VSM and make sure the first VSC counter identified by
PATTERN has a correct value. OP can be ==, &gt;, &gt;=, &lt;, &lt;=. For
example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>varnish v1 -expect SM?.s1.g_space &gt; 1000000
varnish v1 -expect cache_hit &gt;= cache_hit_grace
</pre></div>
</div>
<p>In the ! form the test fails if a counter matches PATTERN.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">MAIN.</span></code> namespace can be omitted from PATTERN.</p>
<p>The test takes up to 5 seconds before timing out.</p>
</dd>
<dt>-vsc PATTERN</dt><dd><p>Dump VSC counters matching PATTERN.</p>
</dd>
<dt>-vsl_catchup</dt><dd><p>Wait until the logging thread has idled to make sure that all
the generated log is flushed</p>
</dd>
</dl>
</section>
<section id="varnishtest">
<span id="vtc-varnishtest"></span><h4>varnishtest<a class="headerlink" href="#varnishtest" title="Link to this heading">¶</a></h4>
<p>Alternate name for ‘vtest’, see above.</p>
</section>
<section id="vtest">
<span id="vtc-vtest"></span><h4>vtest<a class="headerlink" href="#vtest" title="Link to this heading">¶</a></h4>
<p>This should be the first command in your vtc as it will identify the test
case with a short yet descriptive sentence. It takes exactly one argument, a
string, eg:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">vtest</span> <span class="s2">&quot;Check that vtest is actually a valid command&quot;</span>
</pre></div>
</div>
<p>It will also print that string in the log.</p>
</section>
</section>
<section id="history">
<h3>HISTORY<a class="headerlink" href="#history" title="Link to this heading">¶</a></h3>
<p>This document has been written by Guillaume Quintard.</p>
</section>
<section id="see-also">
<h3>SEE ALSO<a class="headerlink" href="#see-also" title="Link to this heading">¶</a></h3>
<ul class="simple">
<li><p><a class="reference internal" href="varnishtest.html#varnishtest-1"><span class="std std-ref">varnishtest</span></a></p></li>
<li><p><a class="reference internal" href="vmod_vtc.html#vmod-vtc-3"><span class="std std-ref">VMOD vtc - Utility module for varnishtest</span></a></p></li>
</ul>
</section>
<section id="copyright">
<h3>COPYRIGHT<a class="headerlink" href="#copyright" title="Link to this heading">¶</a></h3>
<p>This document is licensed under the same licence as Varnish
itself. See LICENCE for details.</p>
<ul class="simple">
<li><p>Copyright (c) 2006-2016 Varnish Software AS</p></li>
</ul>
</section>
</section>
</section>

<div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../index.html">Table of Contents</a></h3>
    <ul>
<li><a class="reference internal" href="#">VTC</a><ul>
<li><a class="reference internal" href="#varnish-test-case-syntax">Varnish Test Case Syntax</a><ul>
<li><a class="reference internal" href="#overview">OVERVIEW</a></li>
<li><a class="reference internal" href="#parsing">PARSING</a><ul>
<li><a class="reference internal" href="#words-and-strings">Words and strings</a></li>
<li><a class="reference internal" href="#comments">Comments</a></li>
<li><a class="reference internal" href="#lines-and-commands">Lines and commands</a></li>
</ul>
</li>
<li><a class="reference internal" href="#macros">MACROS</a><ul>
<li><a class="reference internal" href="#built-in-macros">Built-in macros</a></li>
</ul>
</li>
<li><a class="reference internal" href="#syntax">SYNTAX</a><ul>
<li><a class="reference internal" href="#barrier">barrier</a></li>
<li><a class="reference internal" href="#client-server">client/server</a><ul>
<li><a class="reference internal" href="#arguments">Arguments</a></li>
<li><a class="reference internal" href="#macros-and-automatic-behaviour">Macros and automatic behaviour</a></li>
<li><a class="reference internal" href="#specification">Specification</a></li>
</ul>
</li>
<li><a class="reference internal" href="#delay">delay</a></li>
<li><a class="reference internal" href="#feature">feature</a></li>
<li><a class="reference internal" href="#filewrite">filewrite</a></li>
<li><a class="reference internal" href="#haproxy">haproxy</a><ul>
<li><a class="reference internal" href="#haproxy-cli-specification">haproxy CLI Specification</a></li>
</ul>
</li>
<li><a class="reference internal" href="#include">include</a></li>
<li><a class="reference internal" href="#logexpect">logexpect</a></li>
<li><a class="reference internal" href="#loop">loop</a></li>
<li><a class="reference internal" href="#process">process</a></li>
<li><a class="reference internal" href="#setenv">setenv</a></li>
<li><a class="reference internal" href="#shell">shell</a></li>
<li><a class="reference internal" href="#stream">stream</a><ul>
<li><a class="reference internal" href="#actions">Actions</a></li>
<li><a class="reference internal" href="#vtc-stream-spec">Specification</a><ul>
<li><a class="reference internal" href="#txreq-txresp-txcont-txpush">txreq, txresp, txcont, txpush</a></li>
<li><a class="reference internal" href="#txdata">txdata</a></li>
<li><a class="reference internal" href="#rxreq-rxresp">rxreq, rxresp</a></li>
<li><a class="reference internal" href="#rxhdrs">rxhdrs</a></li>
<li><a class="reference internal" href="#rxpush">rxpush</a></li>
<li><a class="reference internal" href="#rxdata">rxdata</a></li>
<li><a class="reference internal" href="#sendhex">sendhex</a></li>
<li><a class="reference internal" href="#rxgoaway">rxgoaway</a></li>
<li><a class="reference internal" href="#txgoaway">txgoaway</a></li>
<li><a class="reference internal" href="#gunzip">gunzip</a></li>
<li><a class="reference internal" href="#rxping">rxping</a></li>
<li><a class="reference internal" href="#txping">txping</a></li>
<li><a class="reference internal" href="#rxprio">rxprio</a></li>
<li><a class="reference internal" href="#txprio">txprio</a></li>
<li><a class="reference internal" href="#rxrst">rxrst</a></li>
<li><a class="reference internal" href="#txrst">txrst</a></li>
<li><a class="reference internal" href="#rxsettings">rxsettings</a></li>
<li><a class="reference internal" href="#txsettings">txsettings</a></li>
<li><a class="reference internal" href="#rxwinup">rxwinup</a></li>
<li><a class="reference internal" href="#txwinup">txwinup</a></li>
<li><a class="reference internal" href="#expect">expect</a><ul>
<li><a class="reference internal" href="#goaway-specific">GOAWAY specific</a></li>
<li><a class="reference internal" href="#ping-specific">PING specific</a></li>
<li><a class="reference internal" href="#priority-specific">PRIORITY specific</a></li>
<li><a class="reference internal" href="#push-promise-specific">PUSH_PROMISE specific</a></li>
<li><a class="reference internal" href="#reset-stream-specific">RESET_STREAM specific</a></li>
<li><a class="reference internal" href="#settings-specific">SETTINGS specific</a></li>
<li><a class="reference internal" href="#window-update-specific">WINDOW_UPDATE specific</a></li>
<li><a class="reference internal" href="#generic-frame">Generic frame</a></li>
<li><a class="reference internal" href="#request-and-response">Request and response</a></li>
<li><a class="reference internal" href="#vtc-stream-spec-zexpect-zstream">Stream</a></li>
<li><a class="reference internal" href="#index-tables">Index tables</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#syslog">syslog</a></li>
<li><a class="reference internal" href="#tunnel">tunnel</a><ul>
<li><a class="reference internal" href="#vtc-tunnel-args">Arguments</a></li>
<li><a class="reference internal" href="#vtc-tunnel-spec">Specification</a></li>
</ul>
</li>
<li><a class="reference internal" href="#varnish">varnish</a></li>
<li><a class="reference internal" href="#varnishtest">varnishtest</a></li>
<li><a class="reference internal" href="#vtest">vtest</a></li>
</ul>
</li>
<li><a class="reference internal" href="#history">HISTORY</a></li>
<li><a class="reference internal" href="#see-also">SEE ALSO</a></li>
<li><a class="reference internal" href="#copyright">COPYRIGHT</a></li>
</ul>
</li>
</ul>
</li>
</ul>

</div>
  <div>
    <h4>Previous topic</h4>
    <p class="topless"><a href="varnishd.html"
                          title="previous chapter">varnishd</a></p>
  </div>
  <div>
    <h4>Next topic</h4>
    <p class="topless"><a href="varnishtest.html"
                          title="next chapter">varnishtest</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../_sources/reference/vtc.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <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="varnishtest.html" title="varnishtest"
             >next</a> |</li>
        <li class="right" >
          <a href="varnishd.html" title="varnishd"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="../index.html">Varnish version 7.5.0 documentation</a> &#187;</li>
          <li class="nav-item nav-item-1"><a href="index.html" >The Varnish Reference Manual</a> &#187;</li>
        <li class="nav-item nav-item-this"><a href="">VTC</a></li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
    &#169; Copyright 2010-2014, Varnish Software AS.
      Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.
    </div>
  </body>
</html>

❌ Cancel

🗂️ Enhanced PHP File Manager

📊 Server Information

🔧 Quick Actions

✏️ Editing: vtc.html

📤 Upload File

📁 Create Folder

📄 Create File

✏️ Rename Item

🗑️ Delete Confirmation