proxmox-e2e-tests

End-to-end integration tests for Proxmox products (PVE, PBS, ...), written in Perl. This repository contains the test content; the test engine that provisions instances and runs these tests lives in the sibling repository proxmox-test-tools (see its README.md).

How a test is run

proxmox-test-runner (from proxmox-test-tools) executes each test case as a shell command and injects a per-test JSON config describing the available test instances. The path to that JSON is exported as the CONFIG_PATH environment variable. The Proxmox::Test::* framework reads it for you.

Layout

Proxmox/Test/        the helper framework (see below)
tests/               test cases (*.pl) and their manifests (*testcases.ron)
tests/sdn/           SDN/EVPN test cases
hw-validation-tests/ hardware-validation tests (run locally on a PVE host)
plans/               setup plans (consumed by proxmox-test-instance)
scripts/             auxiliary setup scripts (LDAP, FRR, S3, ...)
files/               static assets (e.g. glauth config)

The framework

Class hierarchy:

Proxmox::Test::Instance          SSH access (run_command), get_ip/nodename/root_password
  +- Proxmox::Test::ProxmoxInstance   API client(), wait_for_task[_ok], get_fingerprint
       +- Proxmox::Test::PVEInstance  port 8006, PVEAuthCookie, get_disk_by_serial, new_local
       +- Proxmox::Test::PBSInstance  port 8007, PBSAuthCookie

• Proxmox::Test::Helper reads $CONFIG_PATH (asserting its schema_version) and returns typed instance handles: get_pve_instance($name), get_pbs_instance($name), get_instance($name), get_pve_instances().
• $instance->client() returns a PVE::APIClient::LWP; call ->get/->post/->put/->delete($path, \%params).
• $instance->wait_for_task($upid [, $quiet, $timeout]) polls a task until it finishes and returns its exit status string ('OK' or 'WARNINGS: N' on success). wait_for_task_ok($upid [, $timeout]) dies unless the task succeeded; prefer it for the common assert-success case.
• $instance->run_command($cmd) runs a command over a reused SSH master connection.
• Proxmox::Test::Util exports poll_until(\&cb, timeout => N, interval => N, description => "...") and retry(\&cb, attempts => N). Use these instead of fixed sleeps when waiting for asynchronous state.

The Testcase DSL

Proxmox::Test::Testcase composes multi-step scenarios with per-step cleanup that runs in reverse order even on failure:

Proxmox::Test::Testcase->new('my_scenario')
    ->with([{}])                       # dataset(s) to parameterize over
    ->step('create resource',
        sub { ... create ... },        # the step
        sub { ... delete ... },        # its cleanup (LIFO, runs on failure too)
    )
    ->step('verify', sub { ... })
    ->run();

Writing a new test

1. Create tests/<name>.pl:

   #!/usr/bin/perl
   use strict;
   use warnings;
   use Test::More;
   
   use lib '.';
   use Proxmox::Test::Helper qw(get_pve_instance);
   use Proxmox::Test::Util qw(poll_until);
   
   my $pve = get_pve_instance('pve1');
   
   # ... exercise the API and assert real effects, not just HTTP success ...
   my $res = $pve->client()->get('/version', {});
   ok($res->{version}, 'node reports a version');
   
   done_testing();
   

   Guidelines:

   • Assert observable effects (GET the resource back, check fields), not just that a POST/PUT returned.
   • Clean up created resources (eval-guarded deletes, an END {} block, or the Testcase DSL's cleanup closures) so the test does not leak state if it is run without rollback between tests.
   • Use poll_until/wait_for_task_ok for asynchronous waits; avoid blind sleep.
   • Negative checks use eval { ... }; ok($@, "..."); never fail("...") if !$@ (that emits no assertion on the expected path).

2. Register it in the relevant *testcases.ron (consumed by proxmox-test-runner):

   Testcase(
       name: "my_test",
       run: "./tests/my_test.pl",
       timeout: 60,
       instances: [ "pve1" ],   // names that must exist in the inventory
       tag: "basic",            // optional, used with the runner's --tags
   ),
   

3. Ensure the instances it needs exist in the setup plan under plans/.

Running

The run_*.sh wrappers drive proxmox-test-instance + proxmox-test-runner end to end for common scenarios. To iterate against an already-provisioned inventory, point the runner at it directly:

proxmox-test-runner run inventory.ron tests/testcases.ron --tags basic