test(e2e): add universal-core suite + CI

Mirrors pve-python e2e/ shape for the PMG cell. Token-related scenarios
(SC-12/13/42) and ACL scenarios (SC-22/33) omitted because PMG has neither
API tokens nor an ACL endpoint.

Scenarios kept: SC-01 (version), SC-10/11/14 (ticket auth + CSRF),
SC-30/31 (user CRUD), SC-41 (input validation),
SC-50 (int64 uptime/time), SC-51 (nullable).

PMG-specific: every `accessUsers.create_users` requires a `role` field
(PmgRoleEnum) — tests use AUDIT for transient e2e users. Credentials
helper drops the token_header_value field since PMG has no tokens.

Local CI image is `pmg-test:latest` on port 8006. Workflow installs
pytest deps explicitly because the regen drops
`[project.optional-dependencies]` from pyproject.toml.

Author: bencurio

.github/workflows/e2e.yml

@@ -0,0 +1,43 @@
+name: e2e
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pmg:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+          cache: pip
+
+      - name: Install package + test deps
+        run: |
+          pip install -e .
+          pip install 'pytest>=8' 'pytest-timeout>=2.3' 'requests>=2.32'
+
+      - name: Authenticate to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Start PMG test container
+        id: proxmox
+        uses: client-api/proxmox-docker-action@v1
+        with:
+          product: pmg
+          tag: latest
+
+      - name: Run E2E tests
+        run: pytest e2e/ -v --tb=short
+        env:
+          PROXMOX_INSECURE: '1'

.openapi-generator-ignore

@@ -0,0 +1,14 @@
+# OpenAPI Generator Ignore
+# Generated by openapi-generator https://github.com/openapitools/openapi-generator
+#
+# Use this file to prevent files from being overwritten by the generator.
+
+# Hand-written E2E suite — never regenerate.
+e2e/
+e2e/**
+
+# CI workflow we own; generator only manages ci.yml + publish.yml.
+.github/workflows/e2e.yml
+
+# Local docker harness for the E2E suite.
+docker-compose.yml

docker-compose.yml

@@ -0,0 +1,17 @@
+services:
+  pmg-test:
+    image: ghcr.io/client-api/proxmox-docker/pmg-test:latest
+    container_name: pmg-test
+    privileged: true
+    tmpfs:
+      - /tmp
+      - /run
+      - /run/lock
+    ports:
+      - "8006:8006"
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sk -o /dev/null -w '%{http_code}' https://localhost:8006/api2/json/version | grep -qE '^(200|401)$'"]
+      interval: 5s
+      timeout: 5s
+      retries: 24
+      start_period: 10s

e2e/README.md

@@ -0,0 +1,36 @@
+# E2E tests for `clientapi_pmg`
+
+Live-server pytest suite against a real Proxmox Mail Gateway instance.
+
+## Quick start (local)
+
+```bash
+docker compose up -d
+sleep 20
+
+export PROXMOX_URL=https://localhost:8006
+export PROXMOX_USER=root@pam
+export PROXMOX_PASSWORD=proxmox123
+export PROXMOX_INSECURE=1
+
+pip install -e .
+pip install 'pytest>=8' 'pytest-timeout>=2.3' requests
+pytest e2e/ -v
+```
+
+PMG does not have API tokens — `PROXMOX_TOKEN_HEADER_VALUE` is unused.
+
+## Scenario index
+
+PMG-applicable subset (no API tokens → SC-12/13/42 omitted):
+
+| File | Scenarios |
+|---|---|
+| `test_version.py` | SC-01 |
+| `test_auth.py` | SC-10 (ticket login), SC-11 (invalid pw), SC-14 (CSRF on writes) |
+| `test_crud.py` | SC-30, SC-31 (user CRUD) |
+| `test_errors.py` | SC-41 (input validation) |
+| `test_types.py` | SC-50 (int64 uptime/time), SC-51 (nullable) |
+
+Storage CRUD, ISO upload, VM/CT lifecycle, and oneOf discriminator scenarios
+are PVE-specific and live in `pve-python/e2e/`.

e2e/__init__.py

@@ -0,0 +1,35 @@
+"""Shared pytest fixtures for the PMG E2E suite.
+
+PMG uses ticket auth only — no API tokens (SC-12/13/42 don't apply).
+"""
+from __future__ import annotations
+
+from typing import Iterator
+
+import pytest
+
+from clientapi_pmg import Pmg
+from e2e.helpers.clients import issue_ticket
+from e2e.helpers.credentials import Credentials, MissingCredentialError
+from e2e.helpers.fixtures import cleanup_e2e
+
+
+@pytest.fixture(scope="session")
+def creds() -> Credentials:
+    try:
+        return Credentials.from_env()
+    except MissingCredentialError as exc:
+        pytest.skip(str(exc))
+
+
+@pytest.fixture(scope="session")
+def pmg(creds: Credentials) -> Pmg:
+    """PMG client authenticated via ticket (no API tokens on PMG)."""
+    return issue_ticket(creds)
+
+
+@pytest.fixture(scope="session", autouse=True)
+def _session_cleanup(creds: Credentials, pmg: Pmg) -> Iterator[None]:
+    cleanup_e2e(pmg)
+    yield
+    cleanup_e2e(pmg)

e2e/conftest.py

@@ -0,0 +1,20 @@
+"""Capability gates exposed by client-api/proxmox-docker-action."""
+from __future__ import annotations
+
+import os
+
+
+def _truthy(name: str) -> bool:
+    return os.environ.get(name, "").lower() in ("1", "true", "yes")
+
+
+def kvm_available() -> bool:
+    return _truthy("PROXMOX_KVM_AVAILABLE")
+
+
+def cgroupv2_available() -> bool:
+    return _truthy("PROXMOX_CGROUPV2_AVAILABLE")
+
+
+def network_available() -> bool:
+    return os.environ.get("PROXMOX_NO_NETWORK", "") != "1"

e2e/helpers/__init__.py

@@ -0,0 +1,48 @@
+"""Client factories for PMG ticket auth (PMG has no API tokens)."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from clientapi_pmg import Configuration, Pmg
+
+if TYPE_CHECKING:
+    from e2e.helpers.credentials import Credentials
+
+
+def ticket_client(
+    creds: "Credentials",
+    *,
+    ticket: str,
+    csrf: str | None = None,
+) -> Pmg:
+    cfg = Configuration(host=f"{creds.url}/api2/json")
+    cfg.verify_ssl = not creds.insecure
+    cfg.api_key["PMGAuthCookie"] = ticket
+    if csrf is not None:
+        cfg.api_key["CSRFPreventionToken"] = csrf
+    return Pmg(cfg)
+
+
+def issue_ticket(creds: "Credentials", *, password: str | None = None) -> Pmg:
+    from clientapi_pmg.models.access_ticket_create_ticket_request import (
+        AccessTicketCreateTicketRequest,
+    )
+
+    anon = Configuration(host=f"{creds.url}/api2/json")
+    anon.verify_ssl = not creds.insecure
+    bootstrap = Pmg(anon)
+
+    response = bootstrap.accessTicket.create_ticket(
+        AccessTicketCreateTicketRequest(
+            username=creds.user,
+            password=password if password is not None else creds.password,
+        )
+    )
+    data = response.data
+    if data is None or not data.ticket:
+        raise RuntimeError(f"ticket login returned no ticket: {response!r}")
+    return ticket_client(
+        creds,
+        ticket=data.ticket,
+        csrf=data.csrf_prevention_token,
+    )

e2e/helpers/capability_gate.py

@@ -0,0 +1,40 @@
+"""Load PROXMOX_* environment variables exported by client-api/proxmox-docker-action@v1.
+
+PMG has no API tokens, so `PROXMOX_TOKEN_HEADER_VALUE` is optional here.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+class MissingCredentialError(RuntimeError):
+    """Raised when a required PROXMOX_* env var is missing."""
+
+
+@dataclass(frozen=True)
+class Credentials:
+    url: str
+    user: str
+    password: str
+    insecure: bool
+
+    @classmethod
+    def from_env(cls) -> "Credentials":
+        url = _required("PROXMOX_URL")
+        return cls(
+            url=url.rstrip("/"),
+            user=_required("PROXMOX_USER"),
+            password=_required("PROXMOX_PASSWORD"),
+            insecure=os.environ.get("PROXMOX_INSECURE", "").lower() in ("1", "true", "yes"),
+        )
+
+
+def _required(name: str) -> str:
+    value = os.environ.get(name)
+    if not value:
+        raise MissingCredentialError(
+            f"{name} is not set. Run client-api/proxmox-docker-action@v1 in CI "
+            f"or export it manually for local runs."
+        )
+    return value