Add reproducible Python baseline and Guacamole graphics presets

This commit is contained in:
cabbage committed 2026-10-08 06:55:14 +00:00
1 parent 620f882fe2
commit 98a474696b
8 files changed
+380 -35

No files matched your search

+104 -14
View File
@@ -5,8 +5,9 @@ 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-clean-administrator` selected. The native harness targets that snapshot;
Last configuration check: 2026-10-08 UTC. A powered-off clean
`baseline-clean-python-ready` snapshot was captured, restored, and boot-verified.
The native harness targets that snapshot;
the fixture is ready for native runs. A test run must still perform its own identity,
snapshot, readiness, and exclusive-lease checks rather than relying on that
observation.
@@ -23,10 +24,11 @@ observation.
| 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 OS | Windows 10 Pro 22H2, build `19045.6456` verified after the baseline's pending Windows servicing restart; en-US, BIOS boot (original install build `19045.2006`) |
| Guest account | Local `rvboxtest`; split-token local administrator; console session 1 was observed during provisioning |
| Guest Additions | `7.2.16r174877`; readiness requires published Guest Additions version and Windows OS-release properties (this build does not publish a RunLevel property) |
| Last observed state | `poweroff`; current snapshot `baseline-clean-administrator`, the reset target for native runs |
| Last observed state | `running` for interactive access; current snapshot `baseline-clean-python-ready`, the reset target for native runs; verify live state and lease before mutations |
| Baseline Python | Python `3.13.16` amd64 at `C:\Python313`; machine PATH, `py` launcher, bundled pip and venv; no third-party packages |
The two fixture accounts deliberately share one fixed test-only password for
reproducible native runs. The value is provisioned only in the Helium host's
@@ -101,24 +103,30 @@ copy/paste example and explains the native-host lease boundary.
## Snapshots and reset contract
Three clean snapshots exist and must be retained. `baseline-clean-administrator`
Five snapshots are retained. `baseline-clean-python-ready`
is the only reset target: it contains no `RVBoxClient` SCM service, RVBox tray
Run-key registration, RVBox state, logs, or staged binaries; it also has the
fixture-only built-in `Administrator` account enabled for high-token Guest
Control installation.
Control installation, plus Python, pip, and venv for repeatable interactive tests.
It is a powered-off descendant of `baseline-clean-administrator`, captured after
the first Python snapshot's pending Windows servicing restart completed; the
original parent and both older diagnostic snapshots remain unchanged.
| 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`; retained diagnostic snapshot |
| `baseline-clean-administrator` | `ba5ce5f1-77e3-44b0-8d91-534becce27ff` | `baseline-windows10-pro-22h2-administrator-enabled-full-token`; current reset target |
| `baseline-clean-administrator` | `ba5ce5f1-77e3-44b0-8d91-534becce27ff` | `baseline-windows10-pro-22h2-administrator-enabled-full-token`; retained pre-Python parent |
| `baseline-clean-python` | `2d00a8a2-a7cf-4f7b-bee2-80bd71574e89` | Retained initial Python capture, before its first-restore Windows servicing restart completed; diagnostic only |
| `baseline-clean-python-ready` | `dfadee95-156f-43ee-bdab-a10a44be4070` | Clean RVBox fixture; full-token Administrator; Python 3.13.16 amd64, pip and venv; no RVBox installation or pending Windows servicing reboot; current reset target |
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-clean-administrator` if the current state is not the baseline.
3. Start headless and wait for `VMState=running` plus Guest Additions readiness.
2. Restore `baseline-clean-python-ready` if the current state is not the baseline.
3. Start headless and wait for `VMState=running` plus Guest Additions readiness
(bounded 240-second window for cold boots/servicing restarts).
4. Apply the disposable display/sleep keepalive (`monitor-timeout`, standby,
and hibernate timers set to zero) so VirtualBox VRDE cannot expose a
zero-bpp framebuffer after Windows idle timeout. This is recorded as
@@ -126,7 +134,7 @@ stateful run must:
5. Run the bounded test, collect redacted artifacts, and close every Guest
Control process that was opened by the run.
6. Request a graceful guest shutdown and wait for `VMState=poweroff`.
7. Restore `baseline-clean-administrator` again and leave the VM powered off.
7. Restore `baseline-clean-python-ready` again and leave the VM powered off.
Use `controlvm ... poweroff` only for a hung, disposable test; it can lose
guest state. Never delete any clean snapshot, unregister the VM, or alter
@@ -134,11 +142,93 @@ the stale unregistered `win10_dev` configuration (its disk is missing).
## Harness contract
### Python-enabled baseline
Python is part of `baseline-clean-python-ready`, not a per-run installation. Every
normal `test-host prepare`/`reset` restores it together with the clean Windows
fixture. No Python installer, bootstrap script, verification venv, or RVBox
installation is retained in that snapshot. Both accounts can run `python`,
`py -3.13`, and `python -m pip`; create project venvs under the ordinary user's
profile rather than installing packages into the all-users interpreter.
The pinned [Python 3.13.16 Windows amd64 release](https://www.python.org/downloads/release/python-31316/)
installer has SHA-256
`fb4f9f5d438b2396da0086dc70b935c530cb578e37adc6d354f7ad2037fee83b`.
[`provision-python.ps1`](../scripts/windows/provision-python.ps1) verifies that
digest and its Python Software Foundation Authenticode signature before using
the [official unattended installer options](https://docs.python.org/3.13/using/windows.html#installing-without-ui).
It installs the interpreter, standard library, pip, launcher, and machine PATH;
documentation, regression-test data, Tcl/Tk/IDLE, shortcuts, debug binaries,
and symbols are omitted. No third-party packages are preinstalled.
To recreate or validate a replacement baseline from the currently declared
clean fixture (use a new, unique snapshot name; existing snapshots are never
overwritten):
```sh
# Check state/lease first; prepare only when no other run owns the fixture.
scripts/windows/test-host status
scripts/windows/test-host prepare --run-id python-baseline
scripts/windows/test-host provision-python --run-id python-baseline
# Close any interactive desktop connection before shutdown/capture.
test/rdp-access/rdp-access down
scripts/windows/test-host capture-python-baseline \
--run-id python-baseline --snapshot-name baseline-clean-python-next
```
The controller downloads the 28.5 MiB installer over HTTPS **on Helium**,
validates SHA-256, and uses Guest Control to copy it into the VM. It does not
depend on the guest's network route. Completed installers are cached and
partial `.exe.new` files are retained under the owning host-stage run directory
for resumable retries. Direct download is the default. If that route stalls,
explicitly opt into the established, metered host proxy for this one-time
download:
```sh
RVBOX_TEST_PYTHON_DOWNLOAD_PROXY=socks5h://127.0.0.1:1085 \
scripts/windows/test-host provision-python --run-id python-baseline
```
Provisioning verifies the pinned version, SSL/SQLite imports, pip, machine PATH,
and successful venv creation with bundled pip under both Administrator and
`rvboxtest`. Capture additionally refuses an installed RVBox service, normal
installation/state directories, or tray Run-key registration; requires no
logged-on provisioning Administrator and no Windows servicing reboot pending;
deletes only `C:\ProgramData\RVBoxFixture`
bootstrap data; requests graceful shutdown; and takes a **powered-off** snapshot.
It prints the new snapshot name and UUID and releases the lease. It never
forces shutdown just to obtain a baseline and never blindly retries capture.
After successful capture, update the snapshot name/UUID defaults in `test-host`
and their mirrors in this document and `implementation-plan.v1.md` before
running `prepare` again. That fresh restore/boot must recheck `python --version`,
`py -3.13 --version`, pip and a disposable user-owned venv, plus absence of RVBox.
If an installation/capture SSH call is interrupted, inspect the actual guest
process and VM/snapshot state before retrying; do not assume that its mutation
did not occur. Capture preserves every existing baseline. Ordinary test cleanup
must not delete snapshots or any shared host cache.
For lowest-bandwidth interactive access after `prepare`, use:
```sh
test/rdp-access/rdp-access up --bind 0.0.0.0 \
--public-host x1.xcel.me --graphics minimal
```
That requests 800×600/8-bit graphics and saves the selection per gateway
profile. Disconnect/reconnect to apply a profile change; it does not modify
the Windows baseline. See the [gateway quality settings](../test/rdp-access/README.md#network-and-graphics-quality)
for all levels and server-negotiation caveats.
### Native controller
The canonical adapter is the POSIX controller script
[`scripts/windows/test-host`](../scripts/windows/test-host). It runs from the
Linux controller and invokes `VBoxManage` only through SSH on Helium; the
fixture host is Arch Linux and does not provide PowerShell. Its actions are
`status`, `prepare`, `stage`, `install`, `run`, `collect`, `stop`, `reset`, and `recover`.
fixture host is Arch Linux and does not provide PowerShell. Its native-test
actions are `status`, `prepare`, `stage`, `install`, `run`, `logoff`, `collect`,
`inspect`, `logs`, `stop`, `reset`, and `recover`. Baseline maintenance uses
`provision-python` and `capture-python-baseline` as described above.
The legacy [`test-host.ps1`](../scripts/windows/test-host.ps1) is retained only
as a reference for a future Windows-hosted fixture and is not the Helium lane.
@@ -148,8 +238,8 @@ The adapter takes identity and credentials only from its environment:
export RVBOX_TEST_VBOX_HOST=helium-remote
export RVBOX_TEST_VBOX_VM=rvbox-win10-test
export RVBOX_TEST_VBOX_VM_UUID=6cdc114f-71e5-4167-a394-e922e14e6f5c
export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-administrator
export RVBOX_TEST_VBOX_SNAPSHOT_UUID=ba5ce5f1-77e3-44b0-8d91-534becce27ff
export RVBOX_TEST_VBOX_SNAPSHOT=baseline-clean-python-ready
export RVBOX_TEST_VBOX_SNAPSHOT_UUID=dfadee95-156f-43ee-bdab-a10a44be4070
export RVBOX_TEST_GUEST_USER=rvboxtest
export RVBOX_TEST_GUEST_PASSWORD_FILE=/home/cabbage/.local/share/rvbox-secrets/rvbox-win10-test.password
# Defaults to Administrator and the same password file; overrides are optional.