VTest2 Development Assistant

This skill provides expert guidance for working with VTest2, a standalone HTTP testing program originally derived from Varnish's varnishtest. VTest2 is designed to test HTTP clients, servers, and proxies using a domain-specific scripting language (.vtc files).

What This Skill Does

Assists with VTest2 development tasks including:

Instructions

Build Operations

When user requests to build VTest2:

1. **Basic build without Varnish support:**

- Run `make vtest`

- For testing: `make test`

- For cleanup: `make clean`

2. **Build with Varnish support:**

- Run `make varnishtest VARNISH_SRC=/path/to/varnish-cache`

- Verify the path to Varnish-Cache source is correct

3. **Verify generated files exist before compilation:**

- Check `src/teken_state.h` (generated from `src/sequences` using awk)

- Check `src/vtc_h2_dectbl.h` (generated from `src/tbl/vhp_huffman.h` using Python)

- These must exist before attempting compilation

4. **Syncing with Varnish-Cache:**

- Run `make update` to pull updates from Varnish-Cache repository

- Set `VARNISHSRC` environment variable to use local repository instead of cloning

Code Navigation

When user asks about code structure or architecture:

1. **Direct to key files based on task:**

- Entry point and test orchestration: `src/vtc_main.c`

- Core test execution: `src/vtc.c`

- HTTP/1.1 implementation: `src/vtc_http.c`, `src/vtc_http.h`

- HTTP/2 support: `src/vtc_http2.c`

- TLS/SSL support: `src/vtc_tls.c`

- Client commands: `src/vtc_client.c`

- Server commands: `src/vtc_server.c`

- Process management: `src/vtc_process.c`

- Synchronization: `src/vtc_barrier.c`

- Varnish-specific: `src/vtc_varnish.c` (conditional)

- HAProxy testing: `src/vtc_haproxy.c`

2. **Explain the command system:**

- Commands registered via `cmds.h` using X-macros

- **CMD_GLOBAL**: Available everywhere (barrier, delay, shell, include)

- **CMD_TOP**: Top-level test commands (client, server, process, varnish, haproxy)

- Extensions can add commands via `-E extension_shlib` using `add_cmd()`

3. **Explain core concepts:**

- **Test Execution Model**: Tests run in forked child processes with temporary directories, parallel execution via `-j`

- **Macro System**: Static (`-D name=val`), dynamic, function macros (`${date}`), automatic macros (`sNAME_addr`, `sNAME_port`)

- **Session Abstraction**: Shared HTTP session handling with pluggable connect/disconnect callbacks

- **Session Operations Pattern**: `struct sess_ops` with function pointers for poll/read/write/close, enabling transparent TCP/TLS switching

- **Terminal Emulation**: Full VT220 emulation via `teken.c` for testing interactive programs

Writing VTC Test Files

When user needs to create or debug .vtc test files:

1. **Basic test structure:**

```vtc

vtest "Test description"

server s1 {

rxreq

txresp

} -start

client c1 -connect ${s1_sock} {

txreq

rxresp

expect resp.status == 200

} -run

```

2. **TLS test example:**

```vtc

vtest "Basic TLS test"

server s1 {

tls_config {

cert = "/path/to/cert.pem"

version = TLSv1.2 TLSv1.3

}

tls_handshake

rxreq

txresp -status 200

} -start

client c1 {

tls_config {

servername = "example.com"

verify_peer = false

}

tls_handshake

txreq -url "/"

rxresp

expect resp.status == 200

expect tls.version == "TLSv1.3"

} -run

```

3. **Key test file requirements:**

- Must start with `vtest` or `varnishtest` followed by description

- Test names follow pattern `a[0-9]{5}.vtc` in `tests/` directory

- Use `-l` or `-L` options to preserve test directories for debugging

TLS Implementation

When user works with TLS features:

1. **Explain TLS configuration options:**

- **Common**: `cert`, `version`, `cipher_list`, `ciphersuites`, `alpn`

- **Server-only**: `client_vfy`, `client_vfy_ca`, `staple`

- **Client-only**: `servername`, `verify_peer`, `sess_out`, `sess_in`, `cert_status`

2. **TLS variables for expect commands (after `tls_handshake`):**

- `tls.version`, `tls.cipher`, `tls.servername`, `tls.alpn`

- `tls.alert`, `tls.failed`

- `tls.cert[N].subject`, `tls.cert[N].issuer`, `tls.cert[N].subject_alt_names`

- `tls.sess_reused`, `tls.staple_requested`

- `tls.ocsp_cert_status`, `tls.ocsp_resp_status`, `tls.ocsp_verify`

3. **Explain session operations abstraction:**

- `struct sess_ops` defines function pointers for poll/read/write/close

- `struct http` contains operation pointers defaulting to plain FD operations (`http_fd_so`)

- After `tls_handshake`, operations switch to TLS implementations (`tlsconn_so`)

- All HTTP I/O code remains unchanged - transparently uses correct operations

4. **Point to TLS documentation:**

- Detailed implementation docs in `TLS-IMPL.md`

- Default self-signed certificate (CN=example.com) in `builtin_cert.h`

Platform-Specific Guidance

When user encounters platform-specific issues:

1. **Linux (primary platform):**

- Dependencies: libpcre2-dev, zlib, libssl-dev (OpenSSL 1.0.x+, recommend 1.1.0+)

- Uses `dlopen()` by name for extensions

- Primary development and testing platform

2. **macOS:**

- Libraries via Homebrew

- OpenSSL 3.x via `brew install openssl@3`

- Current Makefile has hardcoded paths; consider `pkg-config --cflags --libs libssl libcrypto` for portability

- Bound but non-listening sockets timeout instead of refusing (bad_backend_fd closed)

- TLS compiles but may have runtime issues with file descriptor management in `VSUB_closefrom()`

- **Recommend testing TLS features on Linux**

3. **FreeBSD jails:**

- localhost/127.0.0.1 becomes jail's IP address

Development Best Practices

When user modifies code:

1. **Code in `lib/` is synced from Varnish-Cache:**

- **Do NOT modify directly**

- Contains shared utilities: vsb, vqueue, vtcp, miniobj, etc.

2. **Conditional compilation flags:**

- `VTEST_WITH_VTC_VARNISH`: Varnish integration

- `VTEST_WITH_VTC_LOGEXPECT`: Log expectation matching

- `VTEST_WITH_VTC_VSM`: Varnish Shared Memory support

3. **Adding custom commands:**

- Use extensions via `-E extension_shlib`

- Register with `add_cmd(name, function, flags)`

4. **Debugging utilities:**

- Use Varnish utility libraries: miniobj (object checking), vsb (string buffers), vqueue (linked lists)

- Preserve test directories with `-l` or `-L` options

- OpenSSL version detection at compile-time via `OPENSSL_VERSION_NUMBER`

Examples

**Building with Varnish support:**

```bash

make varnishtest VARNISH_SRC=../varnish-cache

```

**Running tests:**

```bash

make test

```

**Creating a basic HTTP test:**

```vtc

vtest "Simple GET request"

server s1 {

rxreq

txresp -status 200 -body "Hello World"

} -start

client c1 -connect ${s1_sock} {

txreq -url "/test"

rxresp

expect resp.status == 200

expect resp.body == "Hello World"

} -run

```

Important Notes