rvbox/docs/testing-vm.md

Provisioned Windows test VM

This page is the authoritative record for the resettable Windows smoke fixture. It describes the machine that is available today; it is not the complete Windows release matrix. Keep the values here in sync with the VM before adding or changing native test automation.

Last configuration check: 2026-09-09 UTC. The VM was observed powered off with baseline-disk-first selected. A test run must still perform its own identity, snapshot, readiness, and exclusive-lease checks rather than relying on that observation.

Identity and access

Item	Value
Test VM	rvbox-win10-test
VM UUID	6cdc114f-71e5-4167-a394-e922e14e6f5c
VM group	/RVBox/Tests
VirtualBox host	SSH alias helium-remote; host address 192.168.50.162; host user cabbage
Host platform	Arch Linux; kernel 7.2.2-arch1-1; VirtualBox 7.2.16r174877
VM configuration	/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/rvbox-win10-test.vbox
VM logs	/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/Logs
Snapshot folder	/home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/Snapshots
Guest OS	Windows 10 Pro 22H2, build 19045.2006, en-US, BIOS boot
Guest account	Local rvboxtest; split-token local administrator; console session 1 was observed during provisioning
Guest Additions	7.2.16r174877; Guest Control readiness requires GuestAdditionsRunLevel=3
Last observed state	poweroff; current snapshot baseline-disk-first

The Guest Control credential is test-only. The account name is safe to record, but the password value is intentionally not committed to this repository. On the Helium host, the approved password-file location is:

/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password

The file must be mode 0600 and must be supplied with VirtualBox --passwordfile. Agents and CI must obtain the value through the operator's test secret store or this host-only file; never put the password in a command line, run manifest, log, artifact, or checked-in document. The SSH key and the Helium host account credential follow the same rule.

Hardware and device profile

Item	Value
Memory / CPUs	4096 MiB RAM; 2 vCPUs; 100% execution cap; host CPU profile
Display	VBoxSVGA; 64 MiB VRAM; 3D acceleration disabled
Firmware / boot	BIOS; disk first, DVD second; install media is detached after provisioning
System disk	40 GiB dynamically allocated VDI; logical base path /home/cabbage/VMs/rvbox-win10-test.vdi; active snapshot differencing disks live under the snapshot folder above
Install media	/media/Data2/Downloaded/Win10_22H2_English_x64.iso, Windows image index 6
Audio	Virtual audio disabled (audio=none, playback and capture off)
USB	OHCI, EHCI, and xHCI disabled; no USB filters
Clipboard / drag and drop	Disabled, including clipboard file transfers
Network adapter	One Intel 82540EM adapter, cable connected, NAT attachment; MAC 080027036E7C
Shared folders	None; there is no shared-folder contract for tests

This is a minimum smoke profile (2 vCPU/4 GiB), not the recommended release host profile. It is suitable for bounded tests and may be too small for long parallel suites.

Network and remote-control endpoints

The guest address is assigned by VirtualBox NAT/DHCP. 10.0.2.15 was the last observed guest IPv4 address, but it is not a stable identity and must not be hard-coded into a harness.

Endpoint	Configuration and use
Host management	SSH to helium-remote, then invoke VBoxManage; do not assume VBoxManage is installed on the Linux controller
Guest management	VirtualBox Guest Control over the host; use explicit executable/argument vectors and the password file above
VRDE (VirtualBox RDP)	Enabled for diagnostics at 192.168.50.162:3389; external authentication, VBoxAuthSimple user rvboxtest, Security/Method=negotiate, single connection reuse, multiconnection off
VRDE TLS material	Auto-generated certificate and private key under /home/cabbage/VirtualBox VMs/RVBox/Tests/rvbox-win10-test/; keep both on Helium and do not copy them into the repository or test artifacts
VRDE channels	Input/display enabled; audio, upstream audio, USB, clipboard, and RDP device redirection disabled; no video channel
Native Windows RDP forward	NAT rule rvbox-rdp: host 192.168.50.162:3390 to guest port 3389
Native Windows RDP state	Disabled in the baseline (TermService stopped and fDenyTSConnections=1); do not treat port 3390 as usable until a test explicitly enables and later restores it

VRDE is not the supported test-control channel. It is retained for bounded diagnostic probes only: some RDP clients negotiate input capabilities that VirtualBox 7.2.16 does not handle reliably, and earlier probes included headless-server crashes. Use Guest Control for deterministic setup, execution, and collection. Do not expose the VM's RDP endpoints beyond the test LAN.

Snapshots and reset contract

Two clean snapshots exist and must be retained:

Snapshot	UUID	Description
baseline-clean	5e79176a-3e56-4c5d-bb61-a405a6dcdd59	baseline-windows10-pro-22h2-rvboxtest-guest-additions
baseline-disk-first	9430a9a4-754a-4b22-beaa-8dfd90043f5b	baseline-windows10-pro-22h2-disk-first; current smoke baseline

Restore only while the VM is powered off. Every destructive or potentially stateful run must:

1. Acquire the run lease and verify the VM name, UUID, and snapshot UUID.
2. Restore baseline-disk-first if the current state is not the baseline.
3. Start headless and wait for VMState=running plus Guest Additions readiness.
4. Run the bounded test, collect redacted artifacts, and close every Guest Control process that was opened by the run.
5. Request a graceful guest shutdown and wait for VMState=poweroff.
6. Restore baseline-disk-first again and leave the VM powered off.

Use controlvm ... poweroff only for a hung, disposable test; it can lose guest state. Never delete either clean snapshot, unregister the VM, or alter the stale unregistered win10_dev configuration (its disk is missing).

Harness contract

The checked-in PowerShell adapter is scripts/windows/test-host.ps1. Its actions are Prepare, Status, Run, Collect, Stop, and Reset. The adapter takes identity and credentials only from the host environment:

$env:RVBOX_WINDOWS_VM = 'rvbox-win10-test'
$env:RVBOX_WINDOWS_BASELINE_SNAPSHOT = 'baseline-disk-first'
$env:RVBOX_WINDOWS_GUEST_USER = 'rvboxtest'
$env:RVBOX_WINDOWS_GUEST_PASSWORD_FILE = 'C:\secure\rvbox-win10-test.password'

The implementation plan also uses the equivalent RVBOX_TEST_* names for controllers that run the lifecycle over SSH:

export RVBOX_TEST_VBOX_HOST=helium-remote
export RVBOX_TEST_VBOX_VM=rvbox-win10-test
export RVBOX_TEST_VBOX_SNAPSHOT=baseline-disk-first
export RVBOX_TEST_GUEST_USER=rvboxtest
export RVBOX_TEST_GUEST_PASSWORD_FILE=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password

The provisioned lane's backend is SSH plus VBoxManage plus Guest Control; it does not require WinRM, OpenSSH inside Windows, or a stable guest IP. Guest commands must pass explicit paths and argument vectors. With this VirtualBox build, --wait-stdout and --wait-stderr are supported but --wait-exit is not; use closeprocess when a process wait cannot complete. For cmd.exe payloads, include --unquoted-args so Windows backslashes and the single /c payload are preserved.

Scope and known limitations

This fixture currently provides one active console user and no standard-user, ambiguous multi-session, Server Core, older-build, or physical hardware variant. Those release-matrix entries remain deferred; their selector and fallback unit tests are still required. The GUI-subsystem Guest Control probe also exposed a completion-path limitation for rvbox.exe; native runtime coverage must use a service-driven/console-compatible runner until that adapter path is completed. Wine and protocol stubs do not count as Windows coverage.

For a complete command sequence and lifecycle examples, see the provisioned lane section in implementation-plan.v1.md and the general testing workflow.