VPP Handyman

A multipurpose web-based tool for VPP development. Provides a unified UI for packet capture, building VPP images, and running all three test frameworks (hs-test, kube-test, pytest).

Features

Packet Capture

• Three capture modes: trace (text), pcap (Wireshark-compatible), dispatch trace (pcap with buffer metadata)
• VPP input graph node selection for trace/dispatch (virtio, af_xdp, dpdk, memif, etc.)
• VPP interface selection for pcap (from show interface)
• BPF filtering: protocol, source/destination IP, source/destination port
• Compressed downloads: capture files are gzip-compressed

Build

• Debug and Release builds via sub-tabs (make build / make build-release)
• Git branch checkout before building
• Configurable thread count (-j flag)
• Dependency installation (make install-dep, make install-ext-deps)
• Live build log streaming

hs-test (Host Stack Test)

• One-click setup: builds VPP + Docker images (make -C test/hs-test build)
• Test discovery: lists all tests by suite via Ginkgo dry-run
• Run modes: all tests, by suite label, or specific test(s)
• Options: verbose, parallel, repeat, timeout, debug build
• Cleanup: removes Docker containers and namespaces

kube-test (Kubernetes Test)

• One-click setup: builds VPP + Docker images, optionally sets up KinD cluster
• Test discovery: lists all tests by suite
• Run modes: all tests, by suite, or specific test(s)
• Options: verbose, repeat, timeout, debug build
• Cleanup: removes Kubernetes pods and namespaces

Unit Test (pytest)

• Setup: make test-dep (creates venv, installs dependencies, patches scapy)
• Test discovery: discovers all test_*.py files with classes and methods
• Run modes: all tests, by suite (file), or specific test filter
• Options: verbose, jobs, retries, timeout, debug build, fail fast, extended tests
• Cleanup: test-wipe, test-wipe-papi, test-wipe-all, test-wipe-cov

Shared

• VPP repo path is synced across all tabs (except Packet Capture which uses VPP API socket)
• Live log streaming with status badges for all operations
• Stop button to kill running commands

Prerequisites

• Go 1.24+ for building this tool
• VPP source tree for build/test tabs
• Docker for hs-test
• Docker + KinD + kubectl for kube-test
• Python 3 for unit test discovery
• For packet capture: VPP running with socksvr { default } in startup.conf

Quick Start

# Build
make local-build

# Run (default: binds 0.0.0.0:8080)
./bin/vpp-handyman

# Or with custom options
./bin/vpp-handyman -port 9090 -socket /path/to/api.sock -bind 127.0.0.1

Then open http://<host>:8080 in your browser.

CLI Flags

Flag	Default	Description
-port	8080	HTTP server listen port
-socket	/run/vpp/api.sock	VPP binary API socket path (for packet capture)
-bind	0.0.0.0	Address to bind HTTP server to

API Endpoints

Packet Capture

Method	Path	Description
GET	/api/status	VPP connection status and version
POST	/api/connect	Connect to VPP
POST	/api/disconnect	Disconnect from VPP
GET	/api/interfaces	List VPP interfaces
POST	/api/capture/start	Start capture
GET	/api/capture/status	Poll capture progress
POST	/api/capture/stop	Stop capture
POST	/api/capture/clear	Clear captures
GET	/api/capture/download	Download capture file
POST	/api/vppctl	Execute VPP CLI command

Build

Method	Path	Description
POST	/api/build/start	Start debug/release build
GET	/api/build/status	Poll build progress
POST	/api/build/stop	Stop build
GET	/api/build/deps/check	Check dependency status
POST	/api/build/deps/install	Install dependencies

hs-test

Method	Path	Description
GET	/api/hstest/setup/status	Check setup status
POST	/api/hstest/setup	Run setup/build
GET	/api/hstest/list	List all tests by suite
POST	/api/hstest/run	Run tests
GET	/api/hstest/status	Poll run status
POST	/api/hstest/stop	Stop running command
POST	/api/hstest/cleanup	Cleanup containers

kube-test

Method	Path	Description
GET	/api/kubetest/setup/status	Check setup status
POST	/api/kubetest/setup	Run setup/build
GET	/api/kubetest/list	List all tests by suite
POST	/api/kubetest/run	Run tests
GET	/api/kubetest/status	Poll run status
POST	/api/kubetest/stop	Stop running command
POST	/api/kubetest/cleanup	Cleanup pods/namespaces

Unit Test (pytest)

Method	Path	Description
GET	/api/pytest/setup/status	Check setup status
POST	/api/pytest/setup	Run make test-dep
GET	/api/pytest/list	Discover all tests
POST	/api/pytest/run	Run tests
GET	/api/pytest/status	Poll run status
POST	/api/pytest/stop	Stop running command
POST	/api/pytest/cleanup	Run cleanup targets

Docker

# Build image
make image

# Run (mount the VPP socket for packet capture)
docker run --rm -p 8080:8080 \
  -v /run/vpp/api.sock:/run/vpp/api.sock \
  vpp-handyman:latest