feat(tests): full VHD source intelligence — gallery, ISO, eval download, Gen1/Gen2

Test VM creation now supports four VHD sources in priority order:

  1. GalleryImageName  — marketplace image already on the cluster (recommended)
  2. IsoPath           — local ISO converted to VHDX via Convert-WindowsImage.ps1
  3. DownloadEvalIso   — downloads WS2022 eval ISO from Microsoft then converts
  4. SourceVhdPath     — explicit VHDX/VHD path (sideloaded image)
  5. (none)            — empty VHD, Azure resource layer testing only

New Test-Common.ps1 helpers:
  Get-ConvertWindowsImageScript  downloads Convert-WindowsImage.ps1 from MSLab if
                                  not already cached in $env:TEMP
  Convert-IsoToVhdx              wraps Convert-WindowsImage with Gen1 (MBR/BIOS) and
                                  Gen2 (GPT/UEFI) output; reuses existing VHDX
  Invoke-EvalIsoDownload         downloads WS2022 eval ISO from Microsoft Eval Center;
                                  reuses existing file; accepts -DownloadUrl override

Invoke-HydrationTest.ps1 new params:
  -IsoPath, -DownloadEvalIso, -EvalIsoUrl, -IsoEdition
  -Generation controls both the Hyper-V VM generation AND ISO conversion format

New-ReconnectTestScenario.ps1 new params:
  -IsoPath, -DownloadEvalIso, -EvalIsoUrl, -IsoEdition
  (Reconnect scenario always uses Gen2 for the initial hydration phase)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: kristopherjturner

tests/helpers/Test-Common.ps1

@@ -158,6 +158,173 @@ function Wait-ForAzureResource {
 
 #endregion
 
+#region ── ISO Download and Conversion ───────────────────────────────────────
+
+function Get-ConvertWindowsImageScript {
+    <#
+    .SYNOPSIS
+        Ensures Convert-WindowsImage.ps1 is available locally, downloading it if needed.
+    .DESCRIPTION
+        Convert-WindowsImage.ps1 is a Microsoft tool (maintained in MSLab) that converts
+        a Windows ISO to a bootable VHD/VHDX. This function caches it to avoid repeat downloads.
+    .OUTPUTS
+        [string] Path to Convert-WindowsImage.ps1, or $null on failure.
+    #>
+    param(
+        [string]$LocalPath = "$env:TEMP\Convert-WindowsImage.ps1"
+    )
+
+    if (Test-Path $LocalPath) {
+        Write-TestInfo "Convert-WindowsImage.ps1 cached at: $LocalPath"
+        return $LocalPath
+    }
+
+    $url = 'https://raw.githubusercontent.com/microsoft/MSLab/master/Tools/Convert-WindowsImage.ps1'
+    Write-TestInfo "Downloading Convert-WindowsImage.ps1 from MSLab..."
+    try {
+        $prev = $ProgressPreference; $ProgressPreference = 'SilentlyContinue'
+        Invoke-WebRequest -Uri $url -OutFile $LocalPath -UseBasicParsing -ErrorAction Stop
+        $ProgressPreference = $prev
+        Write-TestInfo "Downloaded to: $LocalPath"
+        return $LocalPath
+    } catch {
+        $ProgressPreference = $prev
+        Write-TestFail "Could not download Convert-WindowsImage.ps1: $_"
+        Write-TestFail "Download manually from: $url"
+        return $null
+    }
+}
+
+function Convert-IsoToVhdx {
+    <#
+    .SYNOPSIS
+        Converts a Windows Server ISO to a bootable VHDX using Convert-WindowsImage.ps1.
+    .DESCRIPTION
+        Gen2 output: GPT/UEFI partition scheme  — attach to Hyper-V Generation 2 VM.
+        Gen1 output: MBR/BIOS partition scheme  — attach to Hyper-V Generation 1 VM.
+        Both produce a Dynamic VHDX. Reuses an existing output file if already present.
+    .OUTPUTS
+        [string] Path to the created VHDX, or $null on failure.
+    #>
+    param(
+        [Parameter(Mandatory)] [string]$IsoPath,
+        [Parameter(Mandatory)] [string]$OutputPath,
+        [ValidateSet(1, 2)]    [int]$Generation    = 2,
+        [string]$Edition   = 'Windows Server 2022 Datacenter',
+        [int64]$SizeBytes   = 60GB,
+        [string]$ConvertScriptPath
+    )
+
+    if (-not (Test-Path $IsoPath)) {
+        Write-TestFail "ISO not found: $IsoPath"
+        return $null
+    }
+
+    if (Test-Path $OutputPath) {
+        $mb = [math]::Round((Get-Item $OutputPath).Length / 1MB)
+        Write-TestInfo "VHDX already exists (${mb} MB) — reusing: $OutputPath"
+        return $OutputPath
+    }
+
+    if (-not $ConvertScriptPath) {
+        $ConvertScriptPath = Get-ConvertWindowsImageScript
+    }
+    if (-not $ConvertScriptPath) { return $null }
+
+    Write-TestInfo "Converting ISO → VHDX (Generation $Generation, $([math]::Round($SizeBytes/1GB)) GB)"
+    Write-TestInfo "  ISO     : $IsoPath"
+    Write-TestInfo "  Output  : $OutputPath"
+    Write-TestInfo "  Edition : $Edition"
+    Write-TestWarn "This may take 5–15 minutes depending on disk speed."
+
+    try {
+        # Dot-source to bring Convert-WindowsImage into scope
+        . $ConvertScriptPath
+
+        $cwParams = @{
+            SourcePath = $IsoPath
+            VHDPath    = $OutputPath
+            VHDFormat  = 'VHDX'
+            Edition    = $Edition
+            SizeBytes  = $SizeBytes
+            VHDType    = 'Dynamic'
+        }
+
+        # Gen1 → MBR/BIOS partition scheme; Gen2 → GPT/UEFI (default)
+        if ($Generation -eq 1) {
+            $cwParams['BCDinVHD'] = 'NativeBoot'
+        }
+
+        Convert-WindowsImage @cwParams
+
+        if (Test-Path $OutputPath) {
+            $mb = [math]::Round((Get-Item $OutputPath).Length / 1MB)
+            Write-TestInfo "VHDX created (${mb} MB): $OutputPath"
+            return $OutputPath
+        }
+
+        Write-TestFail "Convert-WindowsImage completed but output file not found: $OutputPath"
+        return $null
+    } catch {
+        Write-TestFail "ISO-to-VHDX conversion failed: $_"
+        return $null
+    }
+}
+
+function Invoke-EvalIsoDownload {
+    <#
+    .SYNOPSIS
+        Downloads the Windows Server evaluation ISO from Microsoft.
+    .DESCRIPTION
+        Uses the Microsoft Evaluation Center redirect URL. The file is ~5 GB.
+        If the ISO already exists at DestinationPath it is reused without re-downloading.
+
+        Note: Microsoft periodically changes evaluation download URLs. If the default URL
+        fails, visit https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022
+        to get a current direct-download link and pass it via -DownloadUrl.
+    .OUTPUTS
+        [string] Path to the downloaded ISO, or $null on failure.
+    #>
+    param(
+        [string]$DestinationPath = "$env:TEMP\WS2022_eval.iso",
+        # Default URL = Microsoft Eval Center redirect for WS2022 ISO (en-us, x64)
+        [string]$DownloadUrl = 'https://go.microsoft.com/fwlink/p/?LinkID=2195280&clcid=0x409&culture=en-us&country=US'
+    )
+
+    if (Test-Path $DestinationPath) {
+        $mb = [math]::Round((Get-Item $DestinationPath).Length / 1MB)
+        Write-TestInfo "Eval ISO already present (${mb} MB) — reusing: $DestinationPath"
+        return $DestinationPath
+    }
+
+    $dir = Split-Path $DestinationPath
+    if ($dir -and -not (Test-Path $dir)) { New-Item -Path $dir -ItemType Directory -Force | Out-Null }
+
+    Write-TestInfo "Downloading Windows Server 2022 Evaluation ISO (~5 GB)..."
+    Write-TestInfo "URL         : $DownloadUrl"
+    Write-TestInfo "Destination : $DestinationPath"
+    Write-TestWarn "This download may take 10–30 minutes on a typical connection."
+
+    try {
+        $prev = $ProgressPreference; $ProgressPreference = 'SilentlyContinue'
+        Invoke-WebRequest -Uri $DownloadUrl -OutFile $DestinationPath -UseBasicParsing -ErrorAction Stop
+        $ProgressPreference = $prev
+
+        $mb = [math]::Round((Get-Item $DestinationPath).Length / 1MB)
+        Write-TestInfo "Download complete (${mb} MB): $DestinationPath"
+        return $DestinationPath
+    } catch {
+        $ProgressPreference = $prev
+        Write-TestFail "Eval ISO download failed: $_"
+        Write-TestFail "Download manually from:"
+        Write-TestFail "  https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022"
+        Write-TestFail "Then pass the path with: -IsoPath '<path-to-iso>'"
+        return $null
+    }
+}
+
+#endregion
+
 #region ── Gallery Image Resolution ──────────────────────────────────────────
 
 function Get-GalleryImagePath {

tests/hydration/Invoke-HydrationTest.ps1

@@ -46,44 +46,66 @@
 
 .PARAMETER GalleryImageName
     Name of an Azure Local gallery (marketplace) image already downloaded to this cluster.
-    The script resolves its local VHDX path automatically and uses it as the test VM disk.
-    Takes precedence over -SourceVhdPath when both are provided.
-
-    List available images:
-        az stack-hci-vm image list --resource-group <rg> --output table
+    Resolves to the local VHDX automatically — recommended for realistic full-OS testing.
+    List available images: az stack-hci-vm image list -g <rg> --output table
 
 .PARAMETER SourceVhdPath
-    Full path to an existing Windows Server VHDX to use as the test VM disk.
-    Use this if -GalleryImageName resolution fails, or to specify an exact file.
-    If neither -GalleryImageName nor -SourceVhdPath is set, an empty VHD is created.
+    Explicit local path to a VHDX/VHD to copy into the test VM folder.
+    Use when -GalleryImageName resolution fails or you have a custom template.
+
+.PARAMETER IsoPath
+    Path to a Windows Server ISO on the cluster node. The script converts it to a
+    bootable VHDX using Convert-WindowsImage.ps1 (downloaded automatically from MSLab).
+    Use with -Generation to produce Gen1 (MBR/BIOS) or Gen2 (GPT/UEFI) output.
+
+.PARAMETER DownloadEvalIso
+    Download the Windows Server 2022 Evaluation ISO from Microsoft automatically,
+    then convert it to VHDX. Requires ~5 GB download + conversion time.
+    Override the download URL with -EvalIsoUrl if the default link has changed.
+
+.PARAMETER EvalIsoUrl
+    Override the default Microsoft evaluation ISO download URL.
+    Visit https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022
+    to get a current direct-download link if the default has expired.
+
+.PARAMETER IsoEdition
+    Windows Server edition to install when converting from ISO.
+    Default: 'Windows Server 2022 Datacenter'
+    Common values:
+      'Windows Server 2022 Standard'
+      'Windows Server 2022 Standard (Desktop Experience)'
+      'Windows Server 2022 Datacenter'
+      'Windows Server 2022 Datacenter (Desktop Experience)'
 
 .PARAMETER SkipSetup
     Skip the New-HydrationTestVM step. Use when the VM already exists.
 
 .EXAMPLE
-    # Azure resource layer test (empty VHD):
-    .\Invoke-HydrationTest.ps1 `
-        -ResourceGroup   'rg-azlocal-test' `
-        -CustomLocation  '/subscriptions/.../customlocations/cl-test' `
-        -StoragePathId   '/subscriptions/.../storageContainers/UserStorage1' `
-        -StorageRootPath 'C:\ClusterStorage\Volume1' `
-        -SubnetId        'lnet-test-vlan10' `
-        -Location        'eastus'
+    # Azure resource layer test only (empty VHD, no OS needed):
+    .\Invoke-HydrationTest.ps1 -ResourceGroup 'rg-test' -CustomLocation '...' `
+        -StoragePathId '...' -StorageRootPath 'C:\ClusterStorage\csv-01' `
+        -SubnetId 'lnet-test' -Location 'eastus'
+
+.EXAMPLE
+    # Use a marketplace image already on the cluster (recommended):
+    .\Invoke-HydrationTest.ps1 ... -GalleryImageName 'windows-server-2022-datacenter'
 
 .EXAMPLE
-    # Full end-to-end test with real Windows Server VHD:
-    .\Invoke-HydrationTest.ps1 `
-        -ResourceGroup   'rg-azlocal-test' `
-        -CustomLocation  '/subscriptions/.../customlocations/cl-test' `
-        -StoragePathId   '/subscriptions/.../storageContainers/UserStorage1' `
-        -StorageRootPath 'C:\ClusterStorage\Volume1' `
-        -SubnetId        'lnet-test-vlan10' `
-        -Location        'eastus' `
-        -SourceVhdPath   'C:\ClusterStorage\csv-01\ISOs\WS2022_template.vhdx'
+    # Use an ISO already on cluster storage:
+    .\Invoke-HydrationTest.ps1 ... -IsoPath 'C:\ClusterStorage\csv-01\ISOs\WS2022.iso'
+
+.EXAMPLE
+    # Download eval ISO automatically and convert (Gen2):
+    .\Invoke-HydrationTest.ps1 ... -DownloadEvalIso
+
+.EXAMPLE
+    # Download eval ISO and test Gen1 hydration path:
+    .\Invoke-HydrationTest.ps1 ... -DownloadEvalIso -Generation 1
 
 .NOTES
-    Run on one of the Azure Local cluster nodes.
+    Run on one of the Azure Local cluster nodes as Administrator.
     Azure CLI must be authenticated (az login).
+    VHD source priority: GalleryImageName > IsoPath/DownloadEvalIso > SourceVhdPath > empty VHD.
 #>
 [CmdletBinding(SupportsShouldProcess)]
 param(
@@ -121,6 +143,18 @@ param(
     [Parameter()]
     [string]$SourceVhdPath,
 
+    [Parameter()]
+    [string]$IsoPath,
+
+    [Parameter()]
+    [switch]$DownloadEvalIso,
+
+    [Parameter()]
+    [string]$EvalIsoUrl,
+
+    [Parameter()]
+    [string]$IsoEdition = 'Windows Server 2022 Datacenter',
+
     [Parameter()]
     [switch]$SkipClusterCheck,
 
@@ -144,19 +178,63 @@ function Record-Pass([string]$msg) { $script:passed++; Write-TestPass $msg }
 function Record-Fail([string]$msg) { $script:failed++; $script:failures.Add($msg); Write-TestFail $msg }
 
 #region ── Resolve VHD Source ─────────────────────────────────────────────────
+# Priority: GalleryImageName > IsoPath/DownloadEvalIso > SourceVhdPath > empty VHD
+
+if (-not $SkipSetup) {
+
+    if ($GalleryImageName) {
+        # ── Option 1: Marketplace / gallery image already on the cluster
+        $resolvedPath = Get-GalleryImagePath `
+            -ImageName       $GalleryImageName `
+            -ResourceGroup   $ResourceGroup `
+            -StorageRootPath $StorageRootPath
+        if ($resolvedPath) {
+            $SourceVhdPath = $resolvedPath
+            Write-Host "  [VHD] Gallery image : $GalleryImageName" -ForegroundColor Cyan
+            Write-Host "        Local path    : $SourceVhdPath"    -ForegroundColor Cyan
+        } else {
+            Write-Host "  [WARN] Gallery image '$GalleryImageName' not resolved — check next option or use -SourceVhdPath." -ForegroundColor Yellow
+        }
+    }
+
+    if (-not $SourceVhdPath -and ($IsoPath -or $DownloadEvalIso)) {
+        # ── Option 2: ISO → convert to VHDX
+        $iso = $IsoPath
+
+        if ($DownloadEvalIso -and -not $iso) {
+            $isoFile      = Join-Path $env:TEMP 'WS2022_eval.iso'
+            $dlParams     = @{ DestinationPath = $isoFile }
+            if ($EvalIsoUrl) { $dlParams['DownloadUrl'] = $EvalIsoUrl }
+            $iso = Invoke-EvalIsoDownload @dlParams
+        }
+
+        if ($iso) {
+            $genTag  = "gen$Generation"
+            $vhdxOut = Join-Path $env:TEMP "ws2022-test-${genTag}.vhdx"
+            $cvParams = @{
+                IsoPath    = $iso
+                OutputPath = $vhdxOut
+                Generation = $Generation
+                Edition    = $IsoEdition
+            }
+            $converted = Convert-IsoToVhdx @cvParams
+            if ($converted) {
+                $SourceVhdPath = $converted
+                Write-Host "  [VHD] Converted ISO : Gen$Generation VHDX" -ForegroundColor Cyan
+                Write-Host "        Path          : $SourceVhdPath"       -ForegroundColor Cyan
+            } else {
+                Write-Host "  [WARN] ISO conversion failed — falling back to empty VHD." -ForegroundColor Yellow
+            }
+        }
+    }
 
-# Gallery image takes precedence; fall back to explicit SourceVhdPath; then empty VHD
-if ($GalleryImageName -and -not $SkipSetup) {
-    $resolvedPath = Get-GalleryImagePath `
-        -ImageName       $GalleryImageName `
-        -ResourceGroup   $ResourceGroup `
-        -StorageRootPath $StorageRootPath
-    if ($resolvedPath) {
-        $SourceVhdPath = $resolvedPath
-        Write-Host "  Using gallery image: $GalleryImageName" -ForegroundColor Cyan
-        Write-Host "  Local path         : $SourceVhdPath"    -ForegroundColor Cyan
+    if ($SourceVhdPath) {
+        # ── Option 3: Explicit path already set (from above or passed directly)
+        Write-Host "  [VHD] Source VHDX   : $SourceVhdPath" -ForegroundColor Cyan
     } else {
-        Write-Host "  [WARN] Could not resolve gallery image '$GalleryImageName' — falling back to empty VHD." -ForegroundColor Yellow
+        # ── Option 4: Empty VHD — Azure resource layer testing only
+        Write-Host "  [VHD] Mode: empty VHD (no OS) — Azure resource registration only." -ForegroundColor Yellow
+        Write-Host "        Supply -GalleryImageName, -IsoPath, -DownloadEvalIso, or -SourceVhdPath for full OS testing." -ForegroundColor Yellow
     }
 }