Live System Testing

Live tests run KIAUH workflows against a real Debian 12 QEMU/KVM VM. They are isolated from the local developer machine by design.

Safety Rules

Live tests NEVER run on the local machine.
They require KIAUH_LIVE_ALLOW=1.
The target host must be explicitly set via KIAUH_LIVE_TARGET_HOST and match the VM in the inventory.
Local hostnames, loopback addresses, and the current hostname are blocked.

Prepare a VM

Create a Debian 12 QEMU/KVM VM.
Create a user with passwordless sudo.
Install an SSH key for that user.
Install KIAUH on the VM (e.g. clone this repository).

Create a clean snapshot named clean:

virsh snapshot-create-as debian12-kiauh clean

Inventory

Edit kiauh/live/inventory.yaml or point to a custom file:

vms:
  - name: debian12-kiauh
    host: 192.168.122.10
    user: kiauh
    key_file: ~/.ssh/kiauh_vm
    os: debian-12
    domain: debian12-kiauh
    snapshot: clean

Run Live Tests

export KIAUH_LIVE_ALLOW=1
export KIAUH_LIVE_TARGET_HOST=192.168.122.10
pytest -m live

Each scenario reverts the VM to the clean snapshot first, so scenarios are independent.

Add a Scenario

Create a YAML file in kiauh/live/scenarios/:

name: Install Klipper on Debian 12
vm: debian12-kiauh
os: debian-12
steps:
  - command: ["kiauh", "install", "klipper", "--count", "1"]
    timeout: 600
expected:
  - type: service
    name: klipper.service
    state: running

Supported assertion types: service, file, package, port, command.

Troubleshooting

UnsafeTargetError: check KIAUH_LIVE_ALLOW and KIAUH_LIVE_TARGET_HOST.
InventoryError: check the inventory YAML path and format.
LiveRunnerError during snapshot revert: ensure virsh works and the domain and snapshot names match the inventory.

1.8 KiB Raw Blame History