Storage plugin validation suite
================================

This suite validates a Proxmox VE storage plugin against the capabilities a
plugin is expected to provide. It runs on the PVE node that hosts the storage,
driven by `proxmox-test-runner`, and prints a capability matrix and a single
PASS/FAIL verdict.

Running it
----------

Run it on the PVE node, as root, naming the storage to validate:

    # Quick validation of the host-only capabilities:
    proxmox-test-runner storage-plugin-validation mystore

    # Full validation, including the guest-based tests, saving a report:
    proxmox-test-runner storage-plugin-validation mystore \
        --tags +storage-plugin-guest \
        --backup-fallback-storage local \
        --migration-target-storage local-lvm \
        --report validation.md --report-format markdown

Pass more than one storage id to validate several in one run. See
`proxmox-test-runner --help` for all options.

Options you may need
--------------------

  --backup-fallback-storage ID   A backup-capable storage to dump to when the
                                 storage under test cannot hold backups.
  --migration-target-storage ID  A second images-capable storage to move disks
                                 to, for the migration tests.
  --migration-target-node ID     A second cluster node to migrate a VM to for
                                 the cluster migration tests. Auto-discovered
                                 from the cluster status when omitted. The tests
                                 are skipped on a node that is not clustered.
  --iso-url URL                  An ISO image URL for the content-download test.
  --tags +storage-plugin-guest   Also run the guest-based tests (see below).

Guest-based tests
-----------------

Some capabilities (discard/TRIM, backup restore, snapshot rollback and
migration data integrity, guest-visible online resize) can only be checked
from inside a running guest. Those tests are tagged `storage-plugin-guest` and
left out of a default run, because they are slow and need a bootable guest
image with the QEMU guest agent. Enable them with `--tags +storage-plugin-guest`.
They need either internet access plus `libguestfs-tools` (so a Debian cloud
image can be downloaded and prepared once), or `--qga-image` pointing at your
own agent-equipped image.

Reading the result
------------------

Each capability is reported as one of:

  validated     the capability works
  unsupported   the plugin does not implement this optional capability
  not tested    a prerequisite was missing; fix it (see the row detail) and
                re-run
  FAILED        the capability is broken

The verdict is PASS only when nothing FAILED; it is shown as PASS (incomplete)
when some capabilities were not tested, so a partial run is not mistaken for a
complete one.
