# 🍓 ~~`rhubarb`~~`test.thing`

Allison Karlitskaya, Cockpit team ✈️, Red Hat

---

# A virtual machine runner script

## "ooo. we have one of those too!"

## ...mostly booting "bespoke" CI images

## (guest agents, provisioning tools, known credentials)

---

# Goals

## target stock qcow2 "cloud images"

## API for writing "drive from outside" tests in Python

## no cloud-init, ignition, kickstart, etc.

---

# How does it work?

## systemd!

## "Credentials" via SMBIOS type 11 "OEM strings"

## `vmm.notify_socket` → `sd_notify` → vsock → `test.thing`

## `test.thing` → `ssh` → vsock → `ssh-vsock@.service`

## `ssh.ephemeral-authorized_keys-all` (generated on each start)

## ssh control socket on host

---

# Guest compatibility

## ephemeral keys needs a pretty new systemd (v256)

## root ssh key provisioning as a fallback (v252)

## cloud-init after that (we still test RHEL8 in Cockpit, v239)

## "polyfills" for older guests, added with cloud-init

## I've been filing PRs with distros...

---

# vsock?

## virtio hardware device communicates with guest

## AF_VSOCK address family in the kernel

## no "network", no ips

## host side: AF_VSOCK vs. AF_UNIX

## `systemd-ssh-proxy`

---

# "Peers" / "Friends"

## `mkosi qemu`

## `systemd-vmspawn`

## ....something in Rust?

---

# `test.thing` is an API

# Supports "drive from outside" testing

# Don't trust the thing under test

---

# Availability / dependencies

# On PyPI (`test.thing`, `rhubarb` was taken 🙁)

# https://codeberg.org/lis/test.thing

# Python 3.12, stdlib-only, single file, copypastalib

# needs qemu, ssh, vhost-device-vsock, systemd-ssh-proxy

---

# API

```python
import asyncio
import testthing

async def run_machine(vm_image: str) -> None:
    with testthing.IpcDirectory() as ipc:
        async with testthing.VirtualMachine(
            vm_image, ipc=ipc, sit=True
        ) as vm:
            name_file = vm.root / 'run' / 'name'
            await name_file.write_text("world")

output = await vm.execute(r"""
                printf "Hello %s\n" "$(cat /run/name)"
            """)

assert output == "Hello World!\n"

asyncio.run(run_machine("myimage.qcow2"))
```

---

```text
$ python3 test.py

🤦 Traceback (most recent call last):
  File "/var/home/lis/src/talks/2025-all.systems.go-test.thing/test.py",
  line 15, in run_machine
    assert output == "Hello World!\n"
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
AssertionError

Guest is still running.  Connect with: ssh tt.0

Enter or EOF to exit ⏸️ 
```

---

# `ssh tt.0`?

```text
$ tail -n4 ~/.ssh/config

Host tt.*
	ControlPath ${XDG_RUNTIME_DIR}/test.thing/%h/ssh
```

---

# easy from pytest

```python
import pytest
import testthing

@pytest.mark.asyncio
async def test_vm() -> None:
    with testthing.IpcDirectory() as ipc:
        async with testthing.VirtualMachine("arch.qcow2", ipc=ipc) as vm:
            assert 'arch' in await vm.execute('cat', '/etc/os-release')
```

---

# or as a fixture

```python
from collections.abc import AsyncIterator

import pytest
import pytest_asyncio
import testthing

@pytest_asyncio.fixture(scope='session')
async def machine() -> AsyncIterator[testthing.VirtualMachine]:
    with testthing.IpcDirectory() as ipc:
        async with testthing.VirtualMachine("myimage.qcow2", ipc=ipc) as vm:
            yield vm

@pytest.mark.asyncio
async def test_true(machine: testthing.VirtualMachine) -> None:
    await machine.execute("true")

@pytest.mark.asyncio
async def test_false(machine: testthing.VirtualMachine) -> None:
    await machine.execute("false")
```

---

```text
=================== test session starts ===================
collected 2 items

fixtest.py::test_true PASSED                        [ 50%]
fixtest.py::test_false FAILED                       [100%]
======================== FAILURES =========================
_______________________ test_false ________________________
...
E   testthing.SubprocessError: Subprocess exited unexpectedly with return code 1:
E
E   ssh \
E         -F none \
E         -o ControlPath=/run/user/1000/test.thing/tt.0/ssh \
E         tt.0 \
E         -- 'set -eu;' \
E         false

../../test.thing/main/testthing.py:1107: SubprocessError
================= short test summary info =================
FAILED fixtest.py::test_false - testthing.SubprocessError: Subprocess exited unexpecte...
=============== 1 failed, 1 passed in 8.34s ===============
```

---

# CLI

```text
⬢ [lis@toolbx main]$ tt ./Arch-Linux-x86_64-cloudimg-20250915.421442.qcow2

🍓 VM running.  Connect with: ssh tt.0

[root@archlinux ~]# 
```

---

# CLI

```text
⬢ [lis@toolbx main]$ tt image.qcow2 grep NAME /etc/os-release
NAME="Arch Linux"
PRETTY_NAME="Arch Linux"
```

---

# CLI

```text
⬢ [lis@toolbx main]$ cat /etc/os-release | tt image.qcow2 grep NAME
NAME="Fedora Linux"
VERSION_CODENAME=""
PRETTY_NAME="Fedora Linux 42 (Container Image)"
CPE_NAME="cpe:/o:fedoraproject:fedora:42"
DEFAULT_HOSTNAME="fedora"
```

---

# CLI

```text
⬢ [lis@toolbx main]$ tt \
      -L 9091:127.0.0.1:9090 \
      -s cockpit.socket \
      bots/images/arch

Created symlink '/etc/systemd/system/sockets.target.wants/cockpit.socket' →
    '/usr/lib/systemd/system/cockpit.socket'.

🍓 VM running.  Connect with: ssh tt.0

[root@archlinux ~]# 
```

---

# Virtual Machine API

## Anyone interested in helping define this?

## https://codeberg.org/lis/test.thing/src/branch/main/doc/VirtualMachineAPI.md

---

# Codeberg

## Friendly reminder: GitHub is still proprietary software

---

# Ideas / TODO?

## hardware hot-plug via qmp

## cloud-hypervisor?

## "boot a directory"?

## (for Martin) a new name?

---

# fin.  thx 😊