Testing and Development

Testing and Development

Development setup

git clone https://github.com/Kookiejarz/Auto_XDP.git
cd Auto_XDP
python3 -m pip install -e '.[dev]'

Python 3.10 is the minimum supported grammar. The development extras install pytest, mypy, and PyYAML.

Stable test entry point

Use tests/run.sh; CI uses the same interface.

Suite	Coverage
static	Python 3.10 syntax, TOML/JSON, workflow YAML, shell syntax, and suite metadata.
check	static plus mypy.
unit	Deterministic in-process contracts.
component	CLI, temporary filesystem, subprocess, and controlled OS adapters.
smoke	Installer environment/dry-run and command entry points.
distro	static + unit + component + smoke.
type	mypy only.
build	Real native/BPF compilation contracts.
kernel	Privileged kernel/XDP and packet-policy integration.
installed	Non-destructive checks against an installed runtime.
uninstall	Full teardown and residue checks.
all	distro + type + build + kernel.
list	Registered Bash test programs.

Examples:

bash tests/run.sh check
bash tests/run.sh unit
bash tests/run.sh component
bash tests/run.sh smoke
bash tests/run.sh distro

On a disposable, privileged Linux test host:

sudo bash tests/run.sh kernel
sudo bash tests/run.sh installed
sudo bash tests/run.sh uninstall

uninstall removes the active installation. Never run it on a host you did not intend to tear down.

Register a Bash test

A Bash test file declares one metadata line:

# auto-xdp-test-suite: component

It sources tests/bash/testlib.sh, defines top-level test_* functions, and ends with:

run_discovered_tests "${BASH_SOURCE[0]}" "component"
finish_tests

Functions run in definition order. Do not maintain a second workflow or runner registry.

Python test boundaries

Unmarked tests are deterministic unit contracts. They should avoid uncontrolled time, network, subprocesses, root, and source-text inspection. Use the registered component marker for filesystem, CLI, subprocess, or controlled adapter behavior.

Tests should assert stable boundaries such as exit status, persisted configuration, installed artifacts, map ABI, pinned-program identity, rollback state, and packet verdicts.

CI layout

The Full Validation workflow has three main layers:

1. Quality: static, mypy, unit, component, and smoke.
2. Distribution installs: privileged containers for Debian, Ubuntu, Fedora, openSUSE, Arch, Alpine, AlmaLinux, and Rocky Linux, including reinstall over an existing deployment.
3. Ubuntu E2E: a BTF-capable VM testing veth install, installed runtime, kernel packet policy, upgrade/rollback, uninstall residue, clean reinstall, and nftables fallback.

Quality gates the later jobs.

BPF development checks

make -C handlers
bash tests/run.sh build
sudo bash tests/run.sh kernel

Always verify against the real BPF compiler and kernel verifier. A Python model or source-text assertion does not replace load-time verification. Shared map layout changes require synchronized updates to XDP, tc, handlers, userspace wrappers, ABI manifests, and migration tests.

Contribution and security

• Keep one logical change per pull request.
• Use feature/<description>, fix/<description>, or docs/<description> branches.
• Explain what changed, why, impact, alternatives for fixes, and validation performed.
• Run the smallest relevant suite plus check; use kernel/E2E coverage for dataplane or lifecycle changes.
• Report firewall bypasses, unsafe privileged operations, and other vulnerabilities through GitHub Private Vulnerability Reporting.