Skip to main content
Version: master

pvtest List

Every pvtest, by scope and category, with implementation status. Keep this in sync with the tree: when a pvtest is added, modified or removed, update the table below (and TODO.md) and mark completed tests ✓.

Test data lives in this repo under pvtest/suites/{local,remote}/. See appengine.md for how to add or update one.

local — local experience tests​

Local experience tests exercise Pantavisor features that operate without any cloud connectivity. These tests cover the ctrl server's unix socket API, container lifecycle, runtime behavior, security policies, and local services.

core​

Core Pantavisor initialization: config loading, config validation, namespace setup.

TestDescriptionDone
local/core/legacy-config-overloadLegacy configuration overload✓
local/core/modern-config-overloadModern configuration overload (Env/Cmdline)✓
local/core/invalid-config-valuesInvalid Configuration Values Handling
local/core/rootfs-namespaceRootfs namespace (mounts, symlinks, etc.)

lifecycle​

Container and revision lifecycle: updates (reboot/non-reboot), rollback, auto-recovery, power-loss safety.

TestDescriptionDone
local/lifecycle/reboot-nonreboot-rollbackReboot, non-reboot and rollback updates✓
local/lifecycle/seq-non-reboot-updatesSequential non-reboot updates✓
local/lifecycle/power-loss-during-updatePower Loss During Update
local/lifecycle/shared-object-restart-policiesShared object update with distinct restart policies
local/lifecycle/auto-recovery-restartAuto-recovery restart on failure
local/lifecycle/auto-recovery-retries-rollbackAuto-recovery retries exhaustion during TESTING triggers rollback
local/lifecycle/auto-recovery-stable-timeoutAuto-recovery stable timeout holds commit
local/lifecycle/auto-recovery-never-stopsAuto-recovery policy never stops container after retries
local/lifecycle/auto-recovery-stabilizeStabilize pattern: container fails N times then becomes stable
local/lifecycle/auto-recovery-always-restartAlways-restart policy on any exit code
local/lifecycle/auto-recovery-group-inheritanceGroup-level auto-recovery policy inherited by containers
local/lifecycle/auto-recovery-container-overrideContainer auto-recovery overrides group (all-or-nothing)
local/lifecycle/auto-recovery-backoff-durationBackoff duration resets retry cycle after exhaustion

runtime​

Container runtime behavior: state JSON handling, groups, storage persistence, exports, remount policies.

TestDescriptionDone
local/runtime/invalid-state-jsonInvalid State JSON
local/runtime/large-state-jsonLarge State JSON (100+ containers)
local/runtime/container-groups-startupContainer Groups and Startup Order
local/runtime/container-storage-persistenceContainer Storage Persistence
local/runtime/config-overlayConfiguration Overlay
local/runtime/resource-constraintsResource Constraints (CPU/Mem)
local/runtime/status-goal-success-failureStatus Goal Success and Failure✓
local/runtime/forward-compat-parseForward compatibility: unknown status_goal/restart_policy values, an unknown extra key, and a prefix-sharing key never reject a revision✓
local/runtime/container-exportsContainer Exports to Host
local/runtime/remount-policiesRemount Policies (PV_REMOUNT_POLICY)
local/runtime/objects-crudObject store put/get/verify (pv-ctrl)✓
local/runtime/steps-rwStep read + local revision put (pv-ctrl)✓
local/runtime/ctrl-empty-object-putBodyless object PUT replies, no hang (pv-ctrl)✓
local/runtime/cgroup-devices-allow-allA container with only lxc.cgroup.devices.allow = a starts on cgroup v2 and the log warns the line is not needed✓
local/runtime/cgroup-v1-devices-refusedA container with only an lxc.cgroup device whitelist is refused on cgroup v2 and the update rolls back✓
local/runtime/cgroup-v1-and-v2-linesA container with lxc.cgroup and lxc.cgroup2 lines starts on cgroup v2 with the lxc.cgroup lines left out✓
local/runtime/cgroup-v2-devices-enforcedContainers with lxc.cgroup2 device and pids lines run on cgroup v2, reach only the listed devices and get pids.max = 64✓
local/runtime/cgroup-v1-only-refusedA container with only lxc.cgroup device and pids lines is refused on cgroup v2 and the update rolls back✓
local/runtime/invalid-signal-handlingInvalid Signal Handling

control​

Tests that target the pv-ctrl unix socket API in a general way. Other categories may also use pv-ctrl, but for a specific subsystem rather than the API surface itself.

TestDescriptionDone
local/control/basic-endpointsBasic Endpoints (Containers, Objects, etc.)✓
local/control/basic-endpoints-curlBasic Endpoints via cURL✓
local/control/status-codesHTTP status-code contract (commands, signals, drivers, buildinfo)✓
local/control/staged-startSTAGED via MOUNTED + lifecycle_goal: stage, API start/stop/start, reject start on plain MOUNTED, unknown lifecycle_goal falls back✓
local/control/cmd-rejectionsCommands are rejected in local mode, with remote control disabled by config and while an update is ongoing
local/control/pvcontrol-responsivenesspvcontrol responds normally during a time-consuming local operation (e.g. object transfer, sequential update)

xconnect​

xconnect service mesh: proxying, identity headers, D-Bus mediation, DRM, and Wayland isolation.

TestDescriptionDone
local/xconnect/unix-socketsUnix Sockets (UDS proxying)
local/xconnect/rest-over-udsREST-over-UDS (Identity headers)
local/xconnect/dbusD-Bus (Policy mediation)
local/xconnect/drmDRM (Graphics node injection)
local/xconnect/waylandWayland (Isolated UI rendering)

security​

Security policies: secure boot, OEM key validation, container roles, object checksum verification, encrypted storage.

TestDescriptionDone
local/security/strict-secure-bootStrict Secure Boot (Unsigned rejection)✓
local/security/container-rolesContainer Roles (mgmt vs nobody access)✓
local/security/oem-securebootOEM Secureboot (OEM key validation)✓
local/security/object-checksumObject Checksum Validation (dm-verity data objects skipped only when the handler is on)✓
local/security/lenient-secure-bootLenient Secure Boot
local/security/encrypted-storageEncrypted Storage (LUKS/dm-crypt)
local/security/secureboot-sig-0x30Secure Boot when signature starts with 0x30

services​

On-device services: garbage collection, SSH, metadata manipulation, tsh daemon, IPAM, and other auxiliary features.

TestDescriptionDone
local/services/console-alertsContainer status changes reach /dev/console as WALL alerts; PV_LOG_CONSOLE_ALERTS=0 set at runtime silences them
local/services/console-alerts-dedupConsole alert skipped when a stdout output shows it
local/services/on-demand-gcOn-Demand Garbage Collection✓
local/services/sync-gcSynchronous Garbage Collection (/storage/gc)✓
local/services/daemonsDaemon list/stop/start (pv-ctrl)✓
local/services/metadata-crudDevice/user metadata CRUD (pv-ctrl)✓
local/services/tsh-daemontsh daemon management & log capture
local/services/ssh-overrideSSH Override
local/services/metadata-manipulationMetadata Manipulation
local/services/ipam-single-poolSingle IPAM pool — container gets IP from pool
local/services/ipam-multi-poolTwo IPAM pools — correct address assignment
local/services/ipam-collisionConflicting pool addresses detected and rejected
local/services/ipam-invalidInvalid IPAM config rejected gracefully
local/services/ipam-lxcbrIPAM with lxcbr bridge networking

logserver​

The log server: protocols and sockets, platform attribution, fd subscriptions, outputs, timestamps, capture switches, per-revision directories and rotation. Its config is read once at boot, so every test sets it in setup.config.env.

TestDescriptionDone
local/logserver/devlogPer-container /dev/log with PV_LOG_AUTO_DEVLOG=1: capture, attribution, src sanitization, socket create/remove on stop/start, dev-log unset/true/false, a name too long for its log socket✓
local/logserver/devlog-overridePer-container dev-log: true/false in run.json with PV_LOG_AUTO_DEVLOG=0✓
local/logserver/ingestEvery protocol on a container's /dev/log and pv-ctrl-log, platform attribution, malformed input dropped without killing the log server✓
local/logserver/fd-lifecyclepv-fd-log console capture across restart/stop/start: no leaked fds, no spin on a closed fd✓
local/logserver/capture-offPV_LOG_CAPTURE=0, PV_LOG_LOGGERS=0, PV_LOG_CAPTURE_DMESG=0✓
local/logserver/capture-revisionPV_LOG_CAPTURE/PV_LOG_CAPTURE_DMESG from OEM config follow non-reboot updates, off then on, log server not restarted✓
local/logserver/filetree-singlefilePV_LOG_LEVEL=2, filetree+singlefile, golang/strftime timestamps, absolute tsec, dmesg and loggers on✓
local/logserver/dmesg-overrun/dev/kmsg ring buffer overrun: dmesg stays subscribed, overrun line once per 10 s window with a count✓
local/logserver/stdoutPV_LOG_LEVEL=6, filetree with stdout.pantavisor, invalid timestamp format, relative tsec, dmesg skipped✓
local/logserver/heartbeatINFO alive: line at the PV_LOG_HEARTBEAT_INTERVAL pace, run-time change through user meta, 0 stops it, no hub: line in local mode✓
local/logserver/nullsinkPV_LOG_SERVER_OUTPUTS=nullsink: every source accepted, nothing written✓
local/logserver/rotation-and-revisionsLog directories across update and rollback, update output, rotation and cleanup under a small PV_LOG_DIR_MAXSIZE✓

remote — remote experience tests​

Remote experience tests require an active Pantacor Hub connection and exercise the device-cloud communication layer: initial claiming, revision delivery, cloud status reporting, and remote services.

core​

Core remote initialization: pantahub.config parsing (encrypted and unencrypted), Hub TLS certificate verification.

TestDescriptionDone
remote/core/encrypted-pantahub-configEncrypted pantahub.config handling✓
remote/core/unencrypted-pantahub-configUnencrypted pantahub.config handling
remote/core/hub-certificate-verificationHub TLS certificate verification✓
remote/core/hub-certificate-denylistA certificate of the Hub chain in the denylist file blocks the Hub connection✓

lifecycle​

Cloud-driven revision lifecycle: simultaneous updates, disk-space handling, cloud rollback status, retry logic.

TestDescriptionDone
remote/lifecycle/simultaneous-updatesSuccessful Multiple Simultaneous Remote Updates✓
remote/lifecycle/insufficient-disk-spaceUpdate with Insufficient Disk Space✓
remote/lifecycle/rollback-cloud-statusTrigger rollback and verify cloud status✓
remote/lifecycle/update-retries-pv-crashUpdate retries when PV crashes✓
remote/lifecycle/update-retries-gc-pressureUpdate retries when PV crashes with GC pressure✓
remote/lifecycle/claim-after-local-updatesClaim after local updates with random artifacts✓
remote/lifecycle/download-cancel-mid-transferOwner cancel from the Hub aborts an update mid-download and keeps the partial object✓
remote/lifecycle/download-resume-on-timeoutObject download resumes via Range after a mid-transfer crash✓
remote/lifecycle/download-progress-continuousDownload progress reported continuously mid-object✓

control​

Tests that target Pantacor Hub communication in a general way. Other categories also use hub communication, but for their specific purpose (revision delivery, log push, etc.).

TestDescriptionDone
remote/control/manual-claimManual Device Claim✓
remote/control/auto-claimAutomatic Device Claim✓
remote/control/cmd-reset-identityWith PV_CONTROL_REMOTE_ALWAYS=0, identity reset is rejected unless on a DONE local revision, wipes the credentials in local mode and after go-remote, then re-claim reprocesses revision 1 under a new Hub id
remote/control/hint-reset-identityWith PV_CONTROL_REMOTE_ALWAYS=0, Hub identity-reset-requested hint on a Hub revision transitions to locals/identity-reset, which stays remote across reboots, wipes the credentials, registers naming the old Hub id as parent, confirms the reset after the autotok re-claim and processes revision 1 under each Hub id
remote/control/hint-reset-identity-go-remoteWith PV_CONTROL_REMOTE_ALWAYS=0, Hub identity-reset-requested hint on a go-remote local revision transitions to locals/identity-reset, which stays remote across reboots, wipes the credentials, registers naming the old Hub id as parent, confirms the reset after the autotok re-claim and processes revision 1 under the new Hub id
remote/control/always-remote-disabledAlways Remote Disabled✓
remote/control/always-remote-enabledAlways Remote Enabled✓
remote/control/pvcontrol-responsivenesspvcontrol responds normally during a Pantahub download or other expensive remote operation

services​

Cloud-integrated services: log push, metadata exchange, and other hub-backed features.

TestDescriptionDone
remote/services/ph-logger-cloud-pushph-logger cloud push✓
remote/services/hub-summaryDEBUG hub: summary at the PH_LOG_SUMMARY_INTERVAL pace with request and failure counts; run-time change through Hub user meta, 0 stops it, back on counts only from the restart✓
remote/control/device-user-metadataDevice/User Metadata Exchange✓