From a556abbdfc7ebe808b4e421e2fdf79ee83fb2849 Mon Sep 17 00:00:00 2001 From: Joachim Wiberg Date: Tue, 17 Mar 2026 18:33:40 +0100 Subject: [PATCH] doc: expand test-arch with physical device test mode instructions Also, update testing-overview.svg to support dark mode view. Signed-off-by: Joachim Wiberg --- doc/img/testing-overview.svg | 3803 +--------------------------------- doc/test-arch.md | 63 +- doc/testing.md | 8 +- 3 files changed, 62 insertions(+), 3812 deletions(-) diff --git a/doc/img/testing-overview.svg b/doc/img/testing-overview.svg index 80aeaefc..4732b04d 100644 --- a/doc/img/testing-overview.svg +++ b/doc/img/testing-overview.svg @@ -1,3799 +1,4 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + +
/test/env
/9pm/9pm.py
YANG
YANG
some-test.py
some-test.py
/test/case/*/*.py
Infamy
log.dot
YANG
phy.dot
image
unsquashfs
phy.dot
qeneth
suite
phy.dot
suite
YANG
YANG
YANG
Each test can be individually run as an executable
Suite execution of multiple tests and report generation
TAP
docker
podman
python venv
Reproducible environments to run tests
 \ No newline at end of file diff --git a/doc/test-arch.md b/doc/test-arch.md index 7b1f4197..dd8437b9 100644 --- a/doc/test-arch.md +++ b/doc/test-arch.md @@ -243,20 +243,59 @@ spanning tree matches the expected one. Integration to Infix -------------------- -When the test environment is started with Qeneth, it doesn't use the -base image directly. Instead, it creates a copy and inserts a `test-mode` -flag into it. During the bootstrap phase, the system checks for the -presence of the test-mode flag (file). -If the flag exists, a 'test-config.cfg' file is generated. In the -following step, the system loads the 'test-config' instead of the -standard `startup-config` (or `factory-config`). This configuration -is simple and safe, equivalent to the one used in 'Secure Mode' -(also known as 'failure-config'). +### Test Mode -Additionally, the configuration enables extra RPCs related to system -restart and configuration overrides, allowing tests to be run even on -systems where the factory configuration may potentially create L2 loops. +Infix supports a *test mode* that makes devices safe and predictable to +test against. When active, each boot starts from a known-good +`test-config` (equivalent to the failure/secure config) instead of the +stored startup or factory configuration. This prevents any persistent +configuration from interfering with tests and avoids L2 loops that a +factory config might create. It also enables two extra RPCs used by +Infamy: + +- `infix-test:test/reset` — reload the `test-config` into the running + datastore (called by `env.attach()` at the start of each test) +- `infix-test:test/override-startup` — boot from the startup datastore + once, instead of the `test-config` (used by tests that verify + save-and-reboot behaviour) + +Test mode is activated by the presence of an empty file named +`test-mode` on the device's `aux` partition (`/mnt/aux/test-mode`). + +### Test Mode on Virtual Devices + +When the test environment is started with Qeneth, the `inject-test-mode` +script (`test/inject-test-mode`) is run automatically. It copies the +base disk image and writes the `test-mode` marker into the `aux` +partition of that copy, which is then used as the Qeneth backing image. + +### Test Mode on Physical Devices + +For a physical device, log in as `root` (or `admin`) and create the +marker file on the `aux` partition, then reboot: + +``` +# touch /mnt/aux/test-mode +# reboot +``` + +Alternatively, if you want to prepare the disk image before flashing, +use the `inject-test-mode` script: + +``` +$ test/inject-test-mode -b infix-.img -o infix--test.img +``` + +Flash `infix--test.img` to the device instead of the plain +image. The device will boot into test mode on first power-on. + +> [!NOTE] +> Test mode persists across reboots until the marker file is removed +> (`rm /mnt/aux/test-mode`). A device in test mode always starts from +> the `test-config`, so any configuration changes are lost on reboot +> unless `startup_override()` is called first (or the marker is removed +> and a normal startup config is saved). [9PM]: https://github.com/rical/9pm [Qeneth]: https://github.com/wkz/qeneth diff --git a/doc/testing.md b/doc/testing.md index 9a71917f..eb3d1476 100644 --- a/doc/testing.md +++ b/doc/testing.md @@ -37,7 +37,7 @@ $ make TEST_MODE=host test ... ``` -This typically used when testing on physical hardware. By default the +This is typically used when testing on physical hardware. By default the topology will be sourced from `/etc/infamy.dot`, but this can be overwritten by setting the `TOPOLOGY` variable: @@ -46,6 +46,12 @@ $ make TEST_MODE=host TOPOLOGY=~/my-topology.dot test ... ``` +> [!IMPORTANT] +> Physical devices must be put into *test mode* before running tests. +> See [Test Mode](test-arch.md#test-mode) in the architecture document +> for details. The short version: log in to the device and run +> `touch /mnt/aux/test-mode && reboot`. + ### `make run` Devices Some tests only require a single DUT. These can therefore be run