xen: document guest import system and add tests

Add 3rd-party guest import section to README-xen.md covering
import types, kernel modes, Alpine example, and how to add
custom import handlers.

Add test_xen_guest_bundle.py with 46 pytest tests covering
bbclass structure, import handlers, kernel modes, license
warning, Alpine recipe, and README content.

Signed-off-by: Bruce Ashfield <bruce.ashfield@gmail.com>

1 files changed, 361 insertions, 0 deletions

diff --git a/tests/test_xen_guest_bundle.py b/tests/test_xen_guest_bundle.py
new file mode 100644
index 00000000..2035a5f9
--- /dev/null
+++ b/tests/test_xen_guest_bundle.py
@@ -0,0 +1,361 @@
+# SPDX-FileCopyrightText: Copyright (C) 2025 Bruce Ashfield
+#
+# SPDX-License-Identifier: MIT
+"""
+Tests for xen-guest-bundle.bbclass - Xen guest bundling system.
+
+These tests verify:
+  - bbclass file structure and syntax
+  - Import handler definitions
+  - Parse-time logic (__anonymous)
+  - Alpine example recipe structure
+  - Build tests (slow, require configured build environment)
+
+Run with:
+    pytest tests/test_xen_guest_bundle.py -v
+
+Run build tests (requires configured Yocto build):
+    pytest tests/test_xen_guest_bundle.py -v -m slow --machine qemuarm64
+
+Environment variables:
+    POKY_DIR: Path to poky directory (default: /opt/bruce/poky)
+    BUILD_DIR: Path to build directory (default: $POKY_DIR/build)
+    MACHINE: Target machine (default: qemux86-64)
+"""
+
+import re
+import pytest
+from pathlib import Path
+
+
+# Note: Command line options (--poky-dir, --build-dir, --machine)
+# are defined in conftest.py
+
+
+@pytest.fixture(scope="module")
+def poky_dir(request):
+    """Path to poky directory."""
+    path = Path(request.config.getoption("--poky-dir"))
+    if not path.exists():
+        pytest.skip(f"Poky directory not found: {path}")
+    return path
+
+
+@pytest.fixture(scope="module")
+def meta_virt_dir(poky_dir):
+    """Path to meta-virtualization layer."""
+    path = poky_dir / "meta-virtualization"
+    if not path.exists():
+        pytest.skip(f"meta-virtualization not found: {path}")
+    return path
+
+
+@pytest.fixture(scope="module")
+def bbclass_content(meta_virt_dir):
+    """Content of xen-guest-bundle.bbclass."""
+    path = meta_virt_dir / "classes" / "xen-guest-bundle.bbclass"
+    if not path.exists():
+        pytest.skip(f"bbclass not found: {path}")
+    return path.read_text()
+
+
+@pytest.fixture(scope="module")
+def alpine_recipe_content(meta_virt_dir):
+    """Content of alpine-xen-guest-bundle recipe."""
+    recipes = list((meta_virt_dir / "recipes-extended" / "xen-guest-bundles").glob(
+        "alpine-xen-guest-bundle_*.bb"))
+    if not recipes:
+        pytest.skip("Alpine guest bundle recipe not found")
+    return recipes[0].read_text()
+
+
+# ============================================================================
+# bbclass structure tests
+# ============================================================================
+
+class TestXenGuestBundleClass:
+    """Test xen-guest-bundle.bbclass structure and syntax."""
+
+    def test_class_exists(self, meta_virt_dir):
+        """Test that the bbclass file exists."""
+        path = meta_virt_dir / "classes" / "xen-guest-bundle.bbclass"
+        assert path.exists(), f"bbclass not found: {path}"
+
+    def test_spdx_header(self, bbclass_content):
+        """Test SPDX license header is present."""
+        assert "SPDX-License-Identifier: MIT" in bbclass_content
+
+    def test_default_variables(self, bbclass_content):
+        """Test that expected default variables are defined."""
+        defaults = [
+            "XEN_GUEST_BUNDLES",
+            "XEN_GUEST_IMAGE_FSTYPE",
+            "XEN_GUEST_MEMORY_DEFAULT",
+            "XEN_GUEST_VCPUS_DEFAULT",
+            "XEN_GUEST_VIF_DEFAULT",
+            "XEN_GUEST_EXTRA_DEFAULT",
+            "XEN_GUEST_DISK_DEVICE_DEFAULT",
+        ]
+        for var in defaults:
+            assert var in bbclass_content, f"Default variable {var} not found"
+
+    def test_anonymous_function(self, bbclass_content):
+        """Test that __anonymous() is defined."""
+        assert "python __anonymous()" in bbclass_content
+
+    def test_do_compile_defined(self, bbclass_content):
+        """Test that do_compile is defined."""
+        assert "do_compile()" in bbclass_content
+
+    def test_do_install_defined(self, bbclass_content):
+        """Test that do_install is defined."""
+        assert "do_install()" in bbclass_content
+
+    def test_resolve_bundle_rootfs(self, bbclass_content):
+        """Test rootfs resolver function exists."""
+        assert "resolve_bundle_rootfs()" in bbclass_content
+
+    def test_resolve_bundle_kernel(self, bbclass_content):
+        """Test kernel resolver function exists."""
+        assert "resolve_bundle_kernel()" in bbclass_content
+
+    def test_generate_bundle_config(self, bbclass_content):
+        """Test config generator function exists."""
+        assert "generate_bundle_config()" in bbclass_content
+
+    def test_files_variable(self, bbclass_content):
+        """Test FILES variable is set."""
+        assert "FILES:${PN}" in bbclass_content
+        assert "xen-guest-bundles" in bbclass_content
+
+    def test_insane_skip(self, bbclass_content):
+        """Test INSANE_SKIP for binary images."""
+        assert "INSANE_SKIP" in bbclass_content
+        assert "buildpaths" in bbclass_content
+
+
+# ============================================================================
+# Import system tests
+# ============================================================================
+
+class TestImportSystem:
+    """Test import system for 3rd-party guests."""
+
+    def test_import_default_variables(self, bbclass_content):
+        """Test import-related default variables."""
+        assert "XEN_GUEST_IMAGE_SIZE_DEFAULT" in bbclass_content
+        assert "XEN_GUEST_IMPORT_DEPENDS_rootfs_dir" in bbclass_content
+        assert "XEN_GUEST_IMPORT_DEPENDS_qcow2" in bbclass_content
+        assert "XEN_GUEST_IMPORT_DEPENDS_ext4" in bbclass_content
+        assert "XEN_GUEST_IMPORT_DEPENDS_raw" in bbclass_content
+
+    def test_import_depends_rootfs_dir(self, bbclass_content):
+        """Test rootfs_dir depends on e2fsprogs-native."""
+        match = re.search(
+            r'XEN_GUEST_IMPORT_DEPENDS_rootfs_dir\s*=\s*"([^"]*)"',
+            bbclass_content)
+        assert match, "rootfs_dir depends not found"
+        assert "e2fsprogs-native" in match.group(1)
+
+    def test_import_depends_qcow2(self, bbclass_content):
+        """Test qcow2 depends on qemu-system-native."""
+        match = re.search(
+            r'XEN_GUEST_IMPORT_DEPENDS_qcow2\s*=\s*"([^"]*)"',
+            bbclass_content)
+        assert match, "qcow2 depends not found"
+        assert "qemu-system-native" in match.group(1)
+
+    def test_import_handler_rootfs_dir(self, bbclass_content):
+        """Test rootfs_dir import handler exists."""
+        assert "xen_guest_import_rootfs_dir()" in bbclass_content
+        assert "mkfs.ext4" in bbclass_content
+
+    def test_import_handler_qcow2(self, bbclass_content):
+        """Test qcow2 import handler exists."""
+        assert "xen_guest_import_qcow2()" in bbclass_content
+        assert "qemu-img convert" in bbclass_content
+
+    def test_import_handler_ext4(self, bbclass_content):
+        """Test ext4 import handler exists."""
+        assert "xen_guest_import_ext4()" in bbclass_content
+
+    def test_import_handler_raw(self, bbclass_content):
+        """Test raw import handler exists."""
+        assert "xen_guest_import_raw()" in bbclass_content
+
+    def test_resolve_import_source(self, bbclass_content):
+        """Test import source resolver exists."""
+        assert "resolve_import_source()" in bbclass_content
+        assert "_XEN_GUEST_IMPORT_MAP" in bbclass_content
+
+    def test_static_dispatch_in_do_compile(self, bbclass_content):
+        """Test that import dispatch uses static case statement."""
+        # BitBake needs static function references to include them
+        assert "case \"$import_type\" in" in bbclass_content
+        assert "xen_guest_import_rootfs_dir " in bbclass_content
+        assert "xen_guest_import_qcow2 " in bbclass_content
+
+    def test_fakeroot_for_rootfs_dir(self, bbclass_content):
+        """Test that rootfs_dir type triggers fakeroot."""
+        assert "fakeroot" in bbclass_content
+        assert "rootfs_dir" in bbclass_content
+
+
+# ============================================================================
+# Kernel mode tests
+# ============================================================================
+
+class TestKernelModes:
+    """Test three kernel modes: shared, custom, HVM/none."""
+
+    def test_hvm_mode_documented(self, bbclass_content):
+        """Test HVM mode (kernel=none) is supported."""
+        assert '"none"' in bbclass_content or "'none'" in bbclass_content
+        assert "HVM" in bbclass_content
+
+    def test_kernel_unpackdir_check(self, bbclass_content):
+        """Test kernel resolver checks UNPACKDIR."""
+        assert "UNPACKDIR" in bbclass_content
+
+    def test_config_omits_kernel_for_hvm(self, bbclass_content):
+        """Test generate_bundle_config omits kernel for HVM."""
+        # Should have conditional kernel output
+        assert 'if [ -n "$kernel_basename" ]' in bbclass_content
+
+    def test_shared_kernel_dependency(self, bbclass_content):
+        """Test virtual/kernel dependency for shared kernel."""
+        assert "virtual/kernel:do_deploy" in bbclass_content
+
+
+# ============================================================================
+# License warning tests
+# ============================================================================
+
+class TestLicenseWarning:
+    """Test external guest license warning."""
+
+    def test_external_names_variable(self, bbclass_content):
+        """Test _XEN_GUEST_EXTERNAL_NAMES is set for external guests."""
+        assert "_XEN_GUEST_EXTERNAL_NAMES" in bbclass_content
+
+    def test_license_warn_prefunc(self, bbclass_content):
+        """Test license warning is a prefunc on do_compile."""
+        assert "xen_guest_external_license_warn" in bbclass_content
+        assert "do_compile[prefuncs]" in bbclass_content
+
+    def test_license_warn_content(self, bbclass_content):
+        """Test license warning message content."""
+        assert "rights to redistribute" in bbclass_content
+        assert "license terms" in bbclass_content
+
+    def test_license_warn_is_python(self, bbclass_content):
+        """Test license warning is a python function (runs once at task time)."""
+        assert "python xen_guest_external_license_warn()" in bbclass_content
+
+
+# ============================================================================
+# Alpine recipe tests
+# ============================================================================
+
+class TestAlpineRecipe:
+    """Test alpine-xen-guest-bundle recipe structure."""
+
+    def test_recipe_exists(self, meta_virt_dir):
+        """Test that Alpine recipe exists."""
+        recipes = list((meta_virt_dir / "recipes-extended" / "xen-guest-bundles").glob(
+            "alpine-xen-guest-bundle_*.bb"))
+        assert len(recipes) > 0, "Alpine guest bundle recipe not found"
+
+    def test_inherits_xen_guest_bundle(self, alpine_recipe_content):
+        """Test recipe inherits xen-guest-bundle."""
+        assert "inherit xen-guest-bundle" in alpine_recipe_content
+
+    def test_license(self, alpine_recipe_content):
+        """Test recipe has license."""
+        assert 'LICENSE = "MIT"' in alpine_recipe_content
+        assert "LIC_FILES_CHKSUM" in alpine_recipe_content
+
+    def test_src_uri(self, alpine_recipe_content):
+        """Test SRC_URI fetches Alpine minirootfs."""
+        assert "dl-cdn.alpinelinux.org" in alpine_recipe_content
+        assert "alpine-minirootfs" in alpine_recipe_content
+        assert "subdir=alpine-rootfs" in alpine_recipe_content
+
+    def test_sha256sum(self, alpine_recipe_content):
+        """Test sha256sum is set (not placeholder)."""
+        match = re.search(r'SRC_URI\[sha256sum\]\s*=\s*"([^"]*)"',
+                          alpine_recipe_content)
+        assert match, "sha256sum not found"
+        sha = match.group(1)
+        assert len(sha) == 64, f"sha256sum wrong length: {len(sha)}"
+        assert sha != "x" * 64, "sha256sum is still placeholder"
+
+    def test_guest_bundles(self, alpine_recipe_content):
+        """Test XEN_GUEST_BUNDLES is set."""
+        assert 'XEN_GUEST_BUNDLES = "alpine:autostart:external"' in alpine_recipe_content
+
+    def test_import_source_type(self, alpine_recipe_content):
+        """Test import source type is rootfs_dir."""
+        assert 'XEN_GUEST_SOURCE_TYPE[alpine] = "rootfs_dir"' in alpine_recipe_content
+
+    def test_import_source_file(self, alpine_recipe_content):
+        """Test import source file matches SRC_URI subdir."""
+        assert 'XEN_GUEST_SOURCE_FILE[alpine] = "alpine-rootfs"' in alpine_recipe_content
+
+    def test_image_size(self, alpine_recipe_content):
+        """Test image size is set."""
+        assert 'XEN_GUEST_IMAGE_SIZE[alpine]' in alpine_recipe_content
+
+    def test_guest_memory(self, alpine_recipe_content):
+        """Test guest memory is set."""
+        assert 'XEN_GUEST_MEMORY[alpine]' in alpine_recipe_content
+
+    def test_guest_extra(self, alpine_recipe_content):
+        """Test guest extra args include console."""
+        assert 'XEN_GUEST_EXTRA[alpine]' in alpine_recipe_content
+        assert "console=hvc0" in alpine_recipe_content
+
+    def test_multiarch_support(self, alpine_recipe_content):
+        """Test recipe supports multiple architectures."""
+        assert "ALPINE_ARCH" in alpine_recipe_content
+        assert "aarch64" in alpine_recipe_content
+        assert "x86_64" in alpine_recipe_content
+
+
+# ============================================================================
+# README tests
+# ============================================================================
+
+class TestReadme:
+    """Test README-xen.md documentation."""
+
+    @pytest.fixture(scope="class")
+    def readme_content(self, meta_virt_dir):
+        path = meta_virt_dir / "recipes-extended" / "images" / "README-xen.md"
+        if not path.exists():
+            pytest.skip("README-xen.md not found")
+        return path.read_text()
+
+    def test_import_section_exists(self, readme_content):
+        """Test 3rd-party import section exists."""
+        assert "3rd-party guest import" in readme_content
+
+    def test_import_types_documented(self, readme_content):
+        """Test import types are documented."""
+        assert "rootfs_dir" in readme_content
+        assert "qcow2" in readme_content
+
+    def test_kernel_modes_documented(self, readme_content):
+        """Test kernel modes are documented."""
+        assert "none" in readme_content
+        assert "Shared host kernel" in readme_content or "shared" in readme_content.lower()
+
+    def test_alpine_example(self, readme_content):
+        """Test Alpine example is in README."""
+        assert "alpine" in readme_content.lower()
+        assert "XEN_GUEST_SOURCE_TYPE" in readme_content
+
+    def test_custom_handler_docs(self, readme_content):
+        """Test custom handler instructions."""
+        assert "xen_guest_import_" in readme_content
+        assert "XEN_GUEST_IMPORT_DEPENDS_" in readme_content