VM Testing

VM Testing

The package ships a QEMU-based VM harness for end-to-end testing against a real Cockpit instance running on a real OS. It spins up cloud VMs (Arch, Debian, Fedora by default), installs Cockpit, and mounts your built plugin via virtfs — no packaging or installation step required.

Prerequisites

Arch Linux:

sudo pacman -S qemu-full cloud-image-utils wget

KVM access is strongly recommended. Without it the VMs run without hardware acceleration and will be significantly slower.

How it works

1. A base cloud image is downloaded once per distro and kept on disk
2. Each VM gets a thin overlay disk so the base image is never modified
3. cloud-init provisions the VM on first boot: creates a test user, installs Cockpit and any plugin-specific packages, and mounts your plugin's src/ directory read-only into the Cockpit install path via 9p/virtfs
4. Changes to your built output (src/main.js, src/main.css) are immediately visible inside the VM without a restart

Plugin configuration

Each plugin provides scripts/test-vm.config.sh to customise the harness:

PLUGIN_NAME="cockpit-caddy"
MOUNT_TAG="cockpit_caddy"
INSTALL_PATH="/usr/share/cockpit/cockpit-caddy"

extra_packages() {
  echo "caddy"
}

extra_runcmd() {
  echo "  - systemctl enable --now caddy"
}

Usage

Add to your plugin's package.json:

"vm": "node_modules/@rxtx4816/cockpit-plugin-base-react/scripts/test-vm.sh"

Then:

npm run build                    # build the plugin first
npm run vm download arch         # download base image (once)
npm run vm start arch            # start the VM
npm run vm wait arch             # block until cloud-init finishes (~2 min first boot)
# open https://localhost:9090 — login: test / test

After the initial boot, subsequent starts are fast (no re-provisioning unless you clean).

All commands

Command	Description
download [vm|all]	Download base cloud images
build	Run npm run build
start [vm ...]	Start VM(s) in background
wait <vm>	Block until cloud-init completes
stop [vm ...]	Stop VM(s)
status	Show all VMs with ports and running state
ssh <vm>	Open an SSH session into the VM
logs <vm>	Tail the VM serial console
clean [vm ...]	Wipe disk and cloud-init state (base image kept)
rebuild [vm ...]	clean + start in one step
reset [vm ...]	Remove all VM files including base image

Ports

By default the VMs are assigned sequential ports starting from:

• Cockpit: 9090, 9091, 9092 (arch, debian, fedora)
• SSH: 2220, 2221, 2222

These can be changed in your test-vm.config.sh via SSH_BASE and COCKPIT_BASE.

Live reload workflow

Because the plugin is mounted via virtfs, you can iterate quickly:

npm run watch       # rebuild on source changes
npm run vm start arch
npm run vm wait arch
# reload the browser tab after each rebuild — no VM restart needed

Environment overrides

Variable	Default	Description
VM_MEM	1024	Memory per VM in MB
VM_CPUS	2	vCPU count
VM_DISK_SIZE	12G	Overlay disk size

---

Automated browser tests (Playwright)

The VM harness pairs naturally with Playwright E2E tests. Once a VM is running, point Playwright at it and let the tests drive the full UI in Chromium.

The base library ships a pluginPage fixture that handles Cockpit login automatically, and a createPlaywrightConfig factory that pre-configures baseURL, ignoreHTTPSErrors, and Chromium as the only browser. Consumer plugins just call the factory and write their tests.

npm run build
npm run vm start arch
npm run vm wait arch
npm run test:e2e          # headless
npm run test:e2e:ui       # visual runner — great for debugging

To target a non-default VM:

BASE_URL=https://localhost:9091 npm run test:e2e   # second VM port

See Testing for complete setup and usage documentation.