passt/test/README.md

Scope

This directory contains test cases for passt and pasta and a simple POSIX shell-based framework to define them, and run them as a suite.

These tests can be run as part of a continuous integration workflow, and are also used to provide short usage demos, with video recording, for passt and pasta basic use cases.

Run

Dependencies

Packages

The tests require some package dependencies commonly available in Linux distributions. If some packages are not available, the test groups that need them will be selectively skipped.

This is a non-exhaustive list of packages that might not commonly be installed on a system, i.e. common utilities such as a shell are not included here.

Example for Debian, and possibly most Debian-based distributions:

build-essential git jq strace iperf3 qemu-system-x86 tmux sipcalc bc
clang-tidy cppcheck isc-dhcp-common udhcpc psmisc linux-cpupower
netcat-openbsd fakeroot lz4 lm-sensors qemu-system-arm qemu-system-ppc
qemu-system-misc qemu-system-x86`

Other tools

Test measuring request-response and connect-request-response latencies use neper, which is not commonly packaged by distributions and needs to be built and installed manually:

git clone https://github.com/google/neper
cd neper; make
cp tcp_crr tcp_rr udp_rr /usr/local/bin

Virtual machine images are built during test executions using mbuto, the shell script is sourced via git as needed, so there's no need to actually install it.

Special requirements for continuous integration and demo modes

Running the test suite as continuous integration or demo modes will record a video of the steps being executed, and create binary packages. The demo mode uses cool-retro-term as terminal, whereas the continuous integration mode uses MATE Terminal by default.

The following additional packages are commonly needed as well:

dbus-x11 xdotool x11-utils xvfb ffmpeg mate-terminal cool-retro-term xauth
dconf-cli alien linux-perf tshark sqlite3`

For convenience, suitable profiles for MATE Terminal and cool-retro-term are provided under the env directory. To source them:

dconf load /org/mate/terminal/profiles/ < env/mate-terminal.profile
cp env/cool_retro_term.sqlite ~/.local/share/cool-retro-term/QML/OfflineStorage/Databases/*.sqlite

Regular test

Just issue:

./run

from the test directory. Elevated privileges are not needed.

Continuous integration

Issuing:

./ci

will run the whole test suite while recording a video of the execution, and it will also build JavaScript fragments used on http://passt.top/ for performance data tables and links to specific video offsets.

Demo mode

Issuing:

./demo

will run the demo cases under demo, recording videos as well.

Framework

The implementation of the testing framework is under lib, and it provides facilities for terminal and tmux session management, interpretation of test directives, video recording, and suchlike. Test cases are organised in the remaining directories.

Test cases can be implemented as POSIX shell scripts, or as a set of directives, which are not formally documented here, but should be clear enough from the existing cases. The entry point for interpretation of test directives is implemented in lib/test.