feat(image test): run LISA test suites locally via 'image test'

Previously LISA-type suites were rejected by 'azldev image test' and only
served as metadata for external orchestration. This adds a local runner
that generates a LISA runbook from a suite's configured test cases, boots
the image in a QEMU VM, and runs the tests.

- Extend LisaConfig with a framework git source, test-cases, pip
  pre-install/extras, and extra-args; validate that the framework ref is a
  full commit SHA and that test-cases is non-empty.
- Generate a qemu-platform runbook that inlines the image path and an
  ephemeral admin key, with keep_environment=no so VMs are torn down.
- Auto-generate and clean up an ephemeral admin SSH key pair per run.
- Require the image to be qcow2 (reject other formats) before booting.
- Regenerate CLI docs, JSON schema, and scenario snapshots.

Author: liunan-ms

docs/user/reference/cli/azldev_image_test.md

@@ -11,6 +11,7 @@ Test suite names must be simple identifiers (no path separators, traversal segme
 | Description | `description` | string | No | Human-readable description of the test suite |
 | Type | `type` | string | Yes | Test framework to use: `"pytest"` or `"lisa"`. |
 | Pytest | `pytest` | table | When `type = "pytest"` | Pytest-specific configuration (see below) |
+| Lisa | `lisa` | table | Optional (required to run locally) | LISA-specific configuration (see below). May be omitted for metadata-only suites; required to run the suite locally via `azldev image test`. |
 
 Test suites are referenced by images through the [`[images.<name>.tests]`](images.md#image-tests) subtable. Each image can reference one or more test suites by name.
 
@@ -48,7 +49,34 @@ The following placeholders may appear in `extra-args` and are substituted at run
 | `{capabilities}` | Comma-separated list of capability names enabled on the image |
 
 
-## Examples
+## LISA Suite Config
+
+The `[test-suites.<name>.lisa]` subtable is optional. A `type = "lisa"` suite without it is a metadata-only suite (usable by external orchestration but not runnable locally). To run the suite locally via `azldev image test`, the `[test-suites.<name>.lisa]` subtable must be provided.
+
+When run locally, `azldev` executes the suite as follows: it clones the LISA framework at a pinned commit, creates (or reuses) a Python virtual environment and installs the framework into it, generates a runbook from the configured `test-cases`, and boots the image in a QEMU VM to run those cases. VMs are torn down after the run.
+
+The image under test must already be in **qcow2** format; other formats are rejected. Each run generates and later removes an ephemeral admin SSH key pair for VM access.
+
+| Field | TOML Key | Type | Required | Description |
+|-------|----------|------|----------|-------------|
+| Framework | `framework` | table | Yes | Git source for the LISA framework (see below). |
+| Test cases | `test-cases` | array of strings | Yes | LISA test case names to run. They are joined with `\|` into the criteria of the generated runbook. Must be non-empty. |
+| Pip pre-install | `pip-pre-install` | array of strings | No | Pip packages installed into the venv *before* the framework, to override framework version pins that conflict with the local environment (e.g., a system-matching `libvirt-python`). |
+| Pip extras | `pip-extras` | array of strings | No | Pip extras installed from the framework package, appended as `pip install -e ".[extra1,extra2]"`. |
+| Extra args | `extra-args` | array of strings | No | Additional arguments passed to the `lisa` CLI verbatim, after placeholder substitution. See [Placeholders](#placeholders). The generated runbook is always passed via `-r`. |
+
+### Framework git source
+
+The `[test-suites.<name>.lisa.framework]` subtable pins the LISA framework repository.
+
+| Field | TOML Key | Type | Required | Description |
+|-------|----------|------|----------|-------------|
+| Git URL | `git-url` | string | Yes | URL of the LISA framework git repository. |
+| Ref | `ref` | string | Yes | Full 40-character hex commit SHA to check out. Branch names and tags are rejected. |
+
+The framework checkout is keyed by ref, so updating `ref` clones the new revision. If a pinned ref cannot be checked out in an existing checkout (e.g., it was updated to a newer commit), `azldev` re-clones the repository automatically.
+
+
 
 ### Basic pytest suite
 
@@ -100,14 +128,24 @@ type = "pytest"
 test-paths = ["/opt/preinstalled-tests/test_*.py"]
 ```
 
-### LISA suite (external)
+### LISA suite
 
-LISA test suites are metadata-only — they are not executed by `azldev` but are used by external orchestration systems.
+LISA suites are executed locally by `azldev`, which generates a runbook from `test-cases` and boots the image in a QEMU VM. The image must be in qcow2 format.
 
 ```toml
 [test-suites.vm-integration]
 description = "VM integration tests using LISA"
 type = "lisa"
+
+[test-suites.vm-integration.lisa]
+test-cases = ["verify_cpu_count", "verify_grub"]
+# Optional: override a framework version pin and pass extra CLI args to LISA.
+pip-pre-install = ["libvirt-python==9.0.0"]
+extra-args = ["-v"]
+
+[test-suites.vm-integration.lisa.framework]
+git-url = "https://github.com/microsoft/lisa.git"
+ref = "abcdef0123456789abcdef0123456789abcdef01"  # full 40-char commit SHA
 ```
 
 ### Referencing test suites from an image

docs/user/reference/config/test-suites.md

@@ -0,0 +1,107 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package image
+
+import (
+	"fmt"
+	"strings"
+
+	"gopkg.in/yaml.v3"
+)
+
+// The following structs model the subset of a LISA runbook that azldev generates. The
+// YAML field names are dictated by LISA's runbook schema (snake_case), which we do not
+// control.
+//
+
+type lisaRunbook struct {
+	Name     string         `yaml:"name"`
+	Include  []lisaInclude  `yaml:"include"`
+	Testcase []lisaTestcase `yaml:"testcase"`
+	Notifier []lisaNotifier `yaml:"notifier"`
+	Platform []lisaPlatform `yaml:"platform"`
+}
+
+type lisaInclude struct {
+	Path string `yaml:"path"`
+}
+
+type lisaTestcase struct {
+	Criteria lisaCriteria `yaml:"criteria"`
+}
+
+type lisaCriteria struct {
+	Name string `yaml:"name"`
+}
+
+type lisaNotifier struct {
+	Type string `yaml:"type"`
+}
+
+//nolint:tagliatelle // External schema (LISA runbook) dictates the field names.
+type lisaPlatform struct {
+	Type                string              `yaml:"type"`
+	AdminPrivateKeyFile string              `yaml:"admin_private_key_file"`
+	KeepEnvironment     string              `yaml:"keep_environment"`
+	Qemu                lisaPlatformQemu    `yaml:"qemu"`
+	Requirement         lisaPlatformReqRoot `yaml:"requirement"`
+}
+
+//nolint:tagliatelle // External schema (LISA runbook) dictates the field names.
+type lisaPlatformQemu struct {
+	NetworkBootTimeout int `yaml:"network_boot_timeout"`
+}
+
+type lisaPlatformReqRoot struct {
+	Qemu lisaPlatformReqQemu `yaml:"qemu"`
+}
+
+type lisaPlatformReqQemu struct {
+	Qcow2 string `yaml:"qcow2"`
+}
+
+const (
+	// runbookTierIncludePath is the path (relative to the generated runbook) to the shared
+	// tier definitions in the LISA tree. LISA resolves includes relative to the runbook file's
+	// directory, so this resolves correctly only when the generated runbook is written at the
+	// framework repo root (see writeGeneratedRunbook).
+	runbookTierIncludePath = "lisa/microsoft/runbook/tiers/tier.yml"
+	// runbookBootTimeoutSeconds is the QEMU network boot timeout used in the generated runbook.
+	runbookBootTimeoutSeconds = 300
+)
+
+// generateRunbookYAML builds a LISA runbook that runs the given test cases on a QEMU VM
+// booted from imagePath, authenticating with adminKeyPath. All values (image path, admin
+// key path) are inlined as concrete values. keep_environment is "no" so LISA tears down the
+// VM environment after the run.
+func generateRunbookYAML(suiteName string, testCases []string, imagePath, adminKeyPath string) ([]byte, error) {
+	runbook := lisaRunbook{
+		Name:    suiteName,
+		Include: []lisaInclude{{Path: runbookTierIncludePath}},
+		Testcase: []lisaTestcase{
+			{Criteria: lisaCriteria{Name: strings.Join(testCases, "|")}},
+		},
+		Notifier: []lisaNotifier{{Type: "html"}},
+		Platform: []lisaPlatform{
+			{
+				Type:                "qemu",
+				AdminPrivateKeyFile: adminKeyPath,
+				KeepEnvironment:     "no",
+				Qemu:                lisaPlatformQemu{NetworkBootTimeout: runbookBootTimeoutSeconds},
+				Requirement: lisaPlatformReqRoot{
+					Qemu: lisaPlatformReqQemu{
+						Qcow2: imagePath,
+					},
+				},
+			},
+		},
+	}
+
+	data, err := yaml.Marshal(&runbook)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal generated LISA runbook:\n%w", err)
+	}
+
+	return data, nil
+}

internal/app/azldev/cmds/image/lisarunbook.go

@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package image
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gopkg.in/yaml.v3"
+)
+
+func TestGenerateRunbookYAML(t *testing.T) {
+	data, err := generateRunbookYAML(
+		"lisa-qemu",
+		[]string{"verify_cpu_count", "verify_grub"},
+		"/abs/image.qcow2",
+		"/home/user/.ssh/id_rsa",
+	)
+	require.NoError(t, err)
+
+	var runbook lisaRunbook
+	require.NoError(t, yaml.Unmarshal(data, &runbook))
+
+	assert.Equal(t, "lisa-qemu", runbook.Name)
+	require.Len(t, runbook.Include, 1)
+	assert.Equal(t, "lisa/microsoft/runbook/tiers/tier.yml", runbook.Include[0].Path)
+
+	require.Len(t, runbook.Testcase, 1)
+	assert.Equal(t, "verify_cpu_count|verify_grub", runbook.Testcase[0].Criteria.Name)
+
+	require.Len(t, runbook.Notifier, 1)
+	assert.Equal(t, "html", runbook.Notifier[0].Type)
+
+	require.Len(t, runbook.Platform, 1)
+	platform := runbook.Platform[0]
+	assert.Equal(t, "qemu", platform.Type)
+	assert.Equal(t, "/home/user/.ssh/id_rsa", platform.AdminPrivateKeyFile)
+	assert.Equal(t, "no", platform.KeepEnvironment)
+	assert.Equal(t, runbookBootTimeoutSeconds, platform.Qemu.NetworkBootTimeout)
+	assert.Equal(t, "/abs/image.qcow2", platform.Requirement.Qemu.Qcow2)
+}
+
+func TestGenerateRunbookYAML_SingleTestCase(t *testing.T) {
+	data, err := generateRunbookYAML("solo", []string{"verify_grub"}, "img", "key")
+	require.NoError(t, err)
+
+	var runbook lisaRunbook
+	require.NoError(t, yaml.Unmarshal(data, &runbook))
+
+	require.Len(t, runbook.Testcase, 1)
+	assert.Equal(t, "verify_grub", runbook.Testcase[0].Criteria.Name)
+}