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, 128 insertions, 0 deletions

diff --git a/tests/pve/_lib.sh b/tests/pve/_lib.sh
new file mode 100755
index 0000000..10a4242
--- /dev/null
+++ b/tests/pve/_lib.sh
@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# tests/pve/_lib.sh — source-only helpers for the PVE e2e harness.
+#
+# Public surface:
+#   pve_load_env [path]      load tests/pve/.env (or argument) and validate
+#   pve_require_reachable    fail unless `ssh $PVE_SSH_TARGET true` works
+#   pve_ssh "cmd..."         run a command on the PVE host
+#   pve_qm   args...         shorthand for `pve_ssh qm args...`
+#   pve_scp src dst          copy a local file to the PVE host
+#   pve_template_phase       echo: missing | running | stopped | template
+#   hdr "title"              print a section header to stderr
+#
+# Refuses direct execution.
+
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+  echo "ERR: tests/pve/_lib.sh is source-only; do not execute it." >&2
+  exit 1
+fi
+
+set -euo pipefail
+
+PVE_LIB_REQUIRED_VARS=(
+  PVE_SSH_TARGET
+  PVE_NODE
+  PVE_STORAGE
+  PVE_BRIDGE
+  PVE_IMAGE_DIR
+  VYOS_ISO_PATH
+  VYOS_TEMPLATE_VMID
+  VYOS_TEMPLATE_NAME
+  VYOS_E2E_VMID
+  VYOS_E2E_VM_NAME
+  VYOS_E2E_IP
+  VYOS_E2E_CIDR
+  VYOS_E2E_GATEWAY
+  VYDEVICE_APIKEY
+)
+
+pve_load_env() {
+  local env_file="${1:-}"
+  if [[ -z "$env_file" ]]; then
+    env_file="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/.env"
+  fi
+  if [[ ! -f "$env_file" ]]; then
+    echo "ERR: missing env file: $env_file" >&2
+    echo "     copy tests/pve/.env.example to tests/pve/.env and fill it in." >&2
+    return 1
+  fi
+  set -a
+  # shellcheck disable=SC1090
+  source "$env_file"
+  set +a
+
+  local missing=()
+  local v
+  for v in "${PVE_LIB_REQUIRED_VARS[@]}"; do
+    if [[ -z "${!v:-}" ]]; then
+      missing+=("$v")
+    fi
+  done
+  if (( ${#missing[@]} > 0 )); then
+    echo "ERR: env file $env_file is missing values for: ${missing[*]}" >&2
+    return 1
+  fi
+}
+
+pve_ssh() {
+  # ssh joins remaining args with spaces and hands the result to the
+  # remote login shell, so any unquoted `;`, `&`, `|`, `$`, glob, etc.
+  # would be re-interpreted there. When the caller passes a single
+  # argument we treat it as a verbatim remote script. When several are
+  # passed we shell-escape each one with `printf %q` so the remote
+  # shell sees exactly one argv per local argv.
+  if (( $# == 1 )); then
+    ssh -o BatchMode=yes -o ConnectTimeout=10 "$PVE_SSH_TARGET" "$1"
+  else
+    local cmd
+    # shellcheck disable=SC2059
+    cmd="$(printf '%q ' "$@")"
+    ssh -o BatchMode=yes -o ConnectTimeout=10 "$PVE_SSH_TARGET" "$cmd"
+  fi
+}
+
+pve_qm() {
+  pve_ssh qm "$@"
+}
+
+pve_scp() {
+  local src="$1" dst="$2"
+  scp -o BatchMode=yes -o ConnectTimeout=10 "$src" "$PVE_SSH_TARGET:$dst"
+}
+
+pve_require_reachable() {
+  if ! pve_ssh true >/dev/null 2>&1; then
+    echo "ERR: cannot ssh to PVE host '$PVE_SSH_TARGET'." >&2
+    echo "     check ~/.ssh/config, your key, and that the host is up." >&2
+    return 1
+  fi
+}
+
+# Echo one of:
+#   missing   — VMID not registered in PVE
+#   running   — VM exists and is running
+#   stopped   — VM exists, not a template, currently stopped
+#   template  — VM exists and is flagged as a template
+pve_template_phase() {
+  local vmid="$1"
+  if ! pve_qm status "$vmid" >/dev/null 2>&1; then
+    echo missing
+    return
+  fi
+  if pve_qm config "$vmid" | grep -q '^template: 1'; then
+    echo template
+    return
+  fi
+  # `qm status <vmid>` prints e.g. "status: running"
+  local s
+  s="$(pve_qm status "$vmid" | awk '{print $2}')"
+  if [[ "$s" == "running" ]]; then
+    echo running
+  else
+    echo stopped
+  fi
+}
+
+hdr() {
+  printf '\n=== %s ===\n' "$*" >&2
+}