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.

3 files changed, 167 insertions, 0 deletions

diff --git a/tests/e2e/__init__.py b/tests/e2e/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/tests/e2e/__init__.py
diff --git a/tests/e2e/conftest.py b/tests/e2e/conftest.py
new file mode 100644
index 0000000..893afce
--- /dev/null
+++ b/tests/e2e/conftest.py
@@ -0,0 +1,96 @@
+"""Shared fixtures for pyvyos live end-to-end tests.
+
+These tests run only when PYVYOS_E2E=1 is set in the environment.
+They expect a VyOS HTTPS API reachable at VYDEVICE_HOSTNAME with the
+key in VYDEVICE_APIKEY. The harness under tests/pve/ provides one
+way to stand up such a VM on a local Proxmox host, but any VyOS
+instance you can reach works.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+
+import pytest
+
+from pyvyos import VyDevice
+
+
+E2E_ENABLED = os.environ.get("PYVYOS_E2E") == "1"
+
+
+def _env_bool(name: str, default: str = "false") -> bool:
+    return os.environ.get(name, default).lower() in {"1", "true", "yes"}
+
+
+@pytest.fixture(scope="session")
+def device() -> VyDevice:
+    """A VyDevice pointed at the live VyOS under test.
+
+    Session-scoped because the device is stateless on the client side
+    and reusing it keeps the suite fast.
+    """
+    missing = [
+        v for v in ("VYDEVICE_HOSTNAME", "VYDEVICE_APIKEY") if not os.environ.get(v)
+    ]
+    if missing:
+        pytest.fail(
+            f"missing required environment variables: {missing}. "
+            "See tests/pve/.env.example for the full set."
+        )
+
+    return VyDevice(
+        hostname=os.environ["VYDEVICE_HOSTNAME"],
+        apikey=os.environ["VYDEVICE_APIKEY"],
+        protocol=os.environ.get("VYDEVICE_PROTOCOL", "https"),
+        port=int(os.environ.get("VYDEVICE_PORT", "443")),
+        verify=_env_bool("VYDEVICE_VERIFY_SSL"),
+        timeout=10,
+    )
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _wait_for_api(device: VyDevice) -> None:
+    """Block the suite until the HTTPS API answers, or fail loudly.
+
+    A freshly cloned VM may need a moment after `qm start` before the
+    HTTPS service binds. We retry a cheap read for up to two minutes.
+    """
+    if not E2E_ENABLED:
+        return
+
+    deadline = time.time() + 120
+    last_error: str | None = None
+    while time.time() < deadline:
+        try:
+            response = device.show(path=["system", "image"])
+            if not response.error:
+                return
+            last_error = response.error
+        except Exception as exc:  # noqa: BLE001 — broad on purpose, we retry
+            last_error = repr(exc)
+        time.sleep(3)
+
+    pytest.fail(
+        f"VyOS HTTPS API at {os.environ.get('VYDEVICE_HOSTNAME')} did not become "
+        f"ready within 120s. Last error: {last_error}"
+    )
+
+
+def pytest_collection_modifyitems(config, items) -> None:
+    """Skip only e2e tests unless PYVYOS_E2E=1.
+
+    This conftest is auto-discovered by pytest at the session level,
+    so the hook sees every collected item in the run. Filter by path
+    to avoid skipping the unit suite under tests/modules/.
+    """
+    if E2E_ENABLED:
+        return
+    skip = pytest.mark.skip(
+        reason="set PYVYOS_E2E=1 to run live VyOS end-to-end tests"
+    )
+    e2e_dir = os.path.join("tests", "e2e") + os.sep
+    for item in items:
+        if e2e_dir in str(item.fspath):
+            item.add_marker(skip)
diff --git a/tests/e2e/test_vydevice_live.py b/tests/e2e/test_vydevice_live.py
new file mode 100644
index 0000000..7eaadd4
--- /dev/null
+++ b/tests/e2e/test_vydevice_live.py
@@ -0,0 +1,71 @@
+"""Live VyOS smoke tests for pyvyos.
+
+These are intentionally a small, opinionated subset of the SDK:
+just enough to prove that payloads round-trip against a real VyOS
+HTTPS API. Destructive operations (reboot/poweroff/image-add/
+image-delete/reset/config-file-load) live in a separate file when
+they exist; not in scope for v0.4.x.
+"""
+
+from __future__ import annotations
+
+import random
+
+from pyvyos import ApiResponse, VyDevice
+
+
+def _ok(response: ApiResponse) -> None:
+    assert response.status == 200, f"status={response.status} error={response.error!r}"
+    assert not response.error, f"unexpected error: {response.error!r}"
+
+
+def _dummy_name() -> str:
+    """VyOS requires dummy interfaces to match `dumN`.
+
+    Pick a high random N to avoid collision with anything an operator
+    may have created manually.
+    """
+    return f"dum{random.randint(900, 9999)}"
+
+
+def test_show_system_image(device: VyDevice) -> None:
+    response = device.show(path=["system", "image"])
+    _ok(response)
+    assert response.result is not None
+
+
+def test_retrieve_show_config_system(device: VyDevice) -> None:
+    response = device.retrieve_show_config(path=["system"])
+    _ok(response)
+    assert isinstance(response.result, dict)
+
+
+def test_configure_set_read_delete_dummy_iface(device: VyDevice) -> None:
+    name = _dummy_name()
+    address = "192.0.2.10/32"
+    iface_path = ["interfaces", "dummy", name]
+
+    try:
+        set_response = device.configure_set(path=iface_path + ["address", address])
+        _ok(set_response)
+
+        read_response = device.retrieve_return_values(path=iface_path + ["address"])
+        _ok(read_response)
+        # retrieve_return_values returns a list of stringified values.
+        assert address in str(read_response.result), read_response.result
+    finally:
+        cleanup = device.configure_delete(path=iface_path)
+        _ok(cleanup)
+
+
+def test_configure_multiple_op_batch(device: VyDevice) -> None:
+    name = _dummy_name()
+    iface_path = ["interfaces", "dummy", name]
+
+    response = device.configure_multiple_op(
+        op_path=[
+            {"op": "set", "path": iface_path + ["address", "192.0.2.11/32"]},
+            {"op": "delete", "path": iface_path},
+        ]
+    )
+    _ok(response)