tests: add live VyOS e2e harness on Proxmox

Adds an opt-in end-to-end harness that runs pyvyos against a real
VyOS HTTPS API on a Proxmox VE host.

  tests/pve/      shell-based VM lifecycle on a remote PVE host:
                  preflight, ensure-template (state-machine over the
                  VMID with manual-install phase 1 and cloud-init
                  phase 2), create/start/stop/destroy, run-e2e.
                  Cloud-init seed ISO is generated on the PVE host
                  itself; nothing local-side beyond ssh is required.
                  .env is gitignored; .env.example documents the
                  full set of variables.

  tests/e2e/      pytest suite that exercises the public methods
                  most likely to regress on a payload change:
                  show, retrieve_show_config, configure_set /
                  retrieve_return_values / configure_delete round
                  trip, and configure_multiple_op batch. Auto-skipped
                  unless PYVYOS_E2E=1.

The cloud-init template now sets 'service https api rest' before
the API key. Without that flag VyOS only exposes /info; the other
HTTPS routes return 404. README and tests/pve/README document the
requirement, both for cloud-init and for the manual-fallback path.

Also fixes a pre-existing footgun in pyproject.toml: the pytest-env
defaults overwrote VYDEVICE_HOSTNAME from the shell, which made
the e2e tests silently aim at the stale 192.168.56.100 fixture
host. The entries now use the 'D:' (default) prefix so live runs
can override from the environment as expected.

Validated against VyOS rolling 2026.05.18-0045: 4 e2e + 57 unit
tests pass.

This commit does not change pyvyos HTTP payloads, request handling,
or response parsing.

1 files changed, 70 insertions, 0 deletions

diff --git a/tests/pve/.env.example b/tests/pve/.env.example
new file mode 100644
index 0000000..428b519
--- /dev/null
+++ b/tests/pve/.env.example
@@ -0,0 +1,70 @@
+# PVE end-to-end harness — sample environment.
+#
+# Copy this file to tests/pve/.env and fill it in.
+# tests/pve/.env is gitignored and never committed.
+#
+# These scripts ssh to a Proxmox VE host you control and create a
+# disposable VyOS VM to run pyvyos against. They do not modify any
+# production state and they do not run in CI.
+
+# --- PVE host access -------------------------------------------------
+# Anything `ssh` accepts: a bare hostname, an alias from ~/.ssh/config,
+# or user@host. The value below is a placeholder; replace it with your
+# own host or alias, e.g. `pve.example.local` or your ~/.ssh/config
+# alias.
+PVE_SSH_TARGET=pve.example.local
+
+# PVE node name as `hostname -s` reports it on the PVE host.
+PVE_NODE=pve
+
+# Storage where VM disks land. Anything `pvesm status` lists.
+PVE_STORAGE=local-lvm
+
+# Bridge the VyOS VM attaches to.
+PVE_BRIDGE=vmbr0
+
+# Directory on the PVE host that holds ISO and qcow2 images.
+# Standard PVE layout.
+PVE_IMAGE_DIR=/var/lib/vz/template/iso
+
+# --- VyOS install ISO ------------------------------------------------
+# Path on the PVE host to the VyOS rolling install ISO. The harness
+# does not download it; place it there yourself (e.g. from
+# https://github.com/vyos/vyos-nightly-build/releases) and pin the
+# filename here. Bump deliberately when you want a fresher build.
+VYOS_ISO_PATH=/var/lib/vz/template/iso/vyos-rolling.iso
+VYOS_IMAGE_URL=https://github.com/vyos/vyos-nightly-build/releases
+
+# --- VyOS template (built once, then reused) -------------------------
+# VMID reserved for the template. Pick a value well outside your
+# normal VM range. Must be free the first time you run ensure-template.
+VYOS_TEMPLATE_VMID=9203
+VYOS_TEMPLATE_NAME=vyos-pyvyos-e2e-template
+
+# --- e2e VM (clone of the template) ----------------------------------
+VYOS_E2E_VMID=9900
+VYOS_E2E_VM_NAME=pyvyos-e2e
+VYOS_E2E_MEMORY=1024
+VYOS_E2E_CORES=1
+
+# Static IP for the e2e VM. Must be free on PVE_BRIDGE.
+VYOS_E2E_IP=192.0.2.10
+VYOS_E2E_CIDR=24
+VYOS_E2E_GATEWAY=192.0.2.1
+
+# Seconds to wait for cloud-init to apply the seed inside the freshly
+# installed VyOS image. 120s is comfortable; lower it if your hardware
+# is fast and you are tired of waiting.
+VYOS_CLOUD_INIT_WAIT_SECONDS=120
+
+# --- VyOS HTTPS API --------------------------------------------------
+# API key baked into the template at template-build time. The clones
+# inherit it. Treat as a lab secret; rotate by rebuilding the template.
+VYDEVICE_APIKEY=pyvyos-e2e-please-change-me
+
+# pyvyos client settings. Derived from the e2e VM above; only override
+# if you change listen-address or port in cloud-init.
+VYDEVICE_HOSTNAME=192.0.2.10
+VYDEVICE_PORT=443
+VYDEVICE_PROTOCOL=https
+VYDEVICE_VERIFY_SSL=false