fix(#260): enforce supported Pester version range and improve error handling

- `Invoke-NovaTest`, `Test-NovaBuild`, and `% nova test` now only use Pester versions from `5.7.1` to `5.10.0`, failing with a clear error for unsupported `Pester 6.x`.
- Updated documentation to reflect the new Pester version requirements.

Author: stiwicourage

CHANGELOG.md

@@ -15,6 +15,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Fixed
 
+- `Invoke-NovaTest`, `Test-NovaBuild`, and `% nova test` now resolve and import a supported installed `Pester` version from `5.7.1` through `5.10.0` instead of using an unsupported `Pester 6.x` installation automatically.
+    - Nova test workflows now fail early with a clear dependency error when only unsupported `Pester 6.x` versions are available.
+
 ### Security
 
 ## [3.3.0] - 2026-06-16

README.md

@@ -298,8 +298,9 @@ Notes:
 - if `project.json` sets `Pester.CodeCoverage.CoveragePercentTarget`, `Invoke-NovaTest` fails when the measured coverage percentage is lower than that configured target
 - this repository currently enables coverage with a `99` percent target; the template and packaged example
   `project.json` files ship the same JaCoCo configuration shape with `Enabled=false` and a `90` percent opt-in target
-- make sure `Pester 5.7.1` is available before running `Invoke-NovaTest` or `Test-NovaBuild`
-- the published `NovaModuleTools` manifest also declares `Pester 5.7.1`, so installed end-user workflows can still resolve that dependency automatically
+- make sure a supported `Pester` version from `5.7.1` through `5.10.0` is available before running `Invoke-NovaTest` or `Test-NovaBuild`
+- Nova resolves and imports a compatible installed `Pester 5.x` version for the managed test workflow and does not run tests with `Pester 6.x`
+- the published `NovaModuleTools` manifest declares `Pester` with `ModuleVersion = 5.7.1` and `MaximumVersion = 5.10.0`, so installed end-user workflows can still resolve that supported dependency range automatically
 
 ### Create a package artifact
 
@@ -640,7 +641,7 @@ Responsibilities currently covered by the release pipeline include:
 - publishing to PowerShell Gallery
 - preparing the next prerelease version on `develop`
 
-The workflow now uses `KeepAChangelog` for changelog release moves, creates annotated git tags named directly from the release version, and bootstraps the local PSResourceGet repository store before calling `Publish-NovaModule`. The shared CI installer also installs `Pester 5.7.1` explicitly before it installs prerelease gallery modules so test workflows do not rely on transitive manifest dependency resolution.
+The workflow now uses `KeepAChangelog` for changelog release moves, creates annotated git tags named directly from the release version, and bootstraps the local PSResourceGet repository store before calling `Publish-NovaModule`. The shared CI installer also installs `Pester 5.7.1` explicitly before it installs prerelease gallery modules so test workflows stay on Nova's supported `Pester 5.x` range and do not rely on transitive manifest dependency resolution.
 
 ### Where NovaModuleTools cmdlets fit
 

RELEASE_NOTE.md

@@ -14,6 +14,8 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 
 ### Fixed
 
+- `Invoke-NovaTest`, `Test-NovaBuild`, and `% nova test` now stay on Nova's supported `Pester 5.x` range and stop with a clear error instead of trying to run with an installed `Pester 6.x` version.
+
 ### Security
 
 ## [3.3.0] - 2026-06-16

docs/NovaModuleTools/en-US/Invoke-NovaTest.md

@@ -32,6 +32,8 @@ PS> Invoke-NovaTest [[-TagFilter] <string[]>] [[-ExcludeTagFilter] <string[]>]
 
 `Invoke-NovaTest` reads the Pester configuration from `project.json`, discovers the repository unit-test files, and runs the managed Nova test workflow without rebuilding the project first.
 
+Nova resolves a supported installed `Pester` version from `5.7.1` through `5.10.0` for the managed test workflow and stops with a clear dependency error when only unsupported `Pester 6.x` versions are available.
+
 The unit-test workflow writes NUnit XML to `artifacts/UnitTestResults.xml`.
 
 When `Pester.CodeCoverage.Enabled` is `true`, Nova also writes JaCoCo coverage to `artifacts/coverage.xml` and fails the run when the measured percentage is lower than `Pester.CodeCoverage.CoveragePercentTarget`.

docs/NovaModuleTools/en-US/Test-NovaBuild.md

@@ -31,11 +31,13 @@ PS> Test-NovaBuild [[-TagFilter] <string[]>] [[-ExcludeTagFilter] <string[]>]
 
 `Test-NovaBuild` reads the Pester configuration from `project.json`, discovers the build-validation integration tests for the current project, and runs the managed Nova test workflow against the built-module validation surface.
 
+Nova resolves a supported installed `Pester` version from `5.7.1` through `5.10.0` for the managed test workflow and stops with a clear dependency error when only unsupported `Pester 6.x` versions are available.
+
 This build-validation flow writes NUnit XML to `artifacts/TestResults.xml`.
 
 Unlike `Invoke-NovaTest`, this command does not enforce source-coverage targets. Use `Invoke-NovaTest` for the unit-test and code-coverage workflow, and use `Test-NovaBuild` when you need build-validation integration coverage that reflects the built module path.
 
-If the current project does not contain any `*.Integration.Tests.ps1` files, `Test-NovaBuild` stops with a Nova-native error that explains the expected naming and reminds you to use `Invoke-NovaTest` for unit tests.
+If the current project does not contain any `*.Integration.Tests.ps1` files, `Test-NovaBuild` writes an actionable warning that explains the expected naming and reminds you to use `Invoke-NovaTest` for unit tests.
 
 `-OverrideWarning` lets the nested build-validation flow continue even if the `src/public` layout guard reports zero or multiple top-level functions in a public file.
 
@@ -271,5 +273,5 @@ Returns the Pester result object from the managed build-validation run.
 
 ## RELATED LINKS
 
-[Invoke-NovaTest](Invoke-NovaTest.md)
-[Invoke-NovaBuild](Invoke-NovaBuild.md)
+- [Invoke-NovaTest](./Invoke-NovaTest.md)
+- [Invoke-NovaBuild](./Invoke-NovaBuild.md)

src/private/quality/GetNovaTestWorkflowContext.ps1

@@ -12,12 +12,173 @@ function Get-NovaTestWorkflowOperation {
 }
 
 function Assert-NovaPesterAvailable {
+    [CmdletBinding()]
+    param(
+        [AllowNull()][pscustomobject]$ProjectInfo
+    )
+
+    $moduleSpecification = Get-NovaSupportedPesterModuleSpecification -ProjectInfo $ProjectInfo
+    Import-NovaSupportedPesterModule -ModuleSpecification $moduleSpecification
+    return $moduleSpecification
+}
+
+function Get-NovaSupportedPesterModuleSpecification {
+    [CmdletBinding()]
+    param(
+        [AllowNull()][pscustomobject]$ProjectInfo
+    )
+
+    $moduleRequirement = Get-NovaPesterModuleRequirement -ProjectInfo $ProjectInfo
+    $availableModule = @(Get-AvailableNovaPesterModule -ModuleRequirement $moduleRequirement)
+    if ($availableModule.Count -eq 0) {
+        Stop-NovaOperation -Message (Get-NovaPesterDependencyMessage -ModuleRequirement $moduleRequirement) -ErrorId 'Nova.Dependency.PesterDependencyMissing' -Category ResourceUnavailable -TargetObject 'Pester'
+    }
+
+    $selectedVersion = [version]$availableModule[0].Version
+    return [pscustomobject]@{
+        Name = 'Pester'
+        MinimumVersion = $moduleRequirement.MinimumVersion
+        MaximumVersion = $moduleRequirement.MaximumVersion
+        SelectedVersion = $selectedVersion
+        FullyQualifiedName = @{
+            ModuleName = 'Pester'
+            RequiredVersion = [string]$selectedVersion
+        }
+    }
+}
+
+function Get-NovaSupportedPesterRange {
     [CmdletBinding()]
     param()
 
-    if (-not (Get-Module -Name Pester -ListAvailable)) {
-        Stop-NovaOperation -Message 'The module Pester must be installed to run Nova tests. Install Pester 5.7.1 and try again.' -ErrorId 'Nova.Dependency.PesterDependencyMissing' -Category ResourceUnavailable -TargetObject 'Pester'
+    return [pscustomobject]@{
+        Name = 'Pester'
+        MinimumVersion = [version]'5.7.1'
+        MaximumVersion = [version]'5.10.0'
+    }
+}
+
+function Get-NovaPesterModuleRequirement {
+    [CmdletBinding()]
+    param(
+        [AllowNull()][pscustomobject]$ProjectInfo
+    )
+
+    $supportedRequirement = Get-NovaSupportedPesterRange
+    $manifestSettings = Get-NovaPesterSettingValue -InputObject $ProjectInfo -Name 'Manifest'
+    $requiredModules = @(Get-NovaPesterSettingValue -InputObject $manifestSettings -Name 'RequiredModules')
+    $pesterModule = $requiredModules |
+            Where-Object {(Get-NovaPesterSettingValue -InputObject $_ -Name 'ModuleName') -eq 'Pester'} |
+            Select-Object -First 1
+
+    if ($null -ne $pesterModule) {
+        $manifestRequirement = [pscustomobject]@{
+            Name = 'Pester'
+            MinimumVersion = [version](Get-NovaPesterVersionText -InputObject $pesterModule -Name 'ModuleVersion' -DefaultValue '5.7.1')
+            MaximumVersion = [version](Get-NovaPesterVersionText -InputObject $pesterModule -Name 'MaximumVersion' -DefaultValue '5.10.0')
+        }
+        Assert-NovaPesterModuleRequirementSupported -ModuleRequirement $manifestRequirement -SupportedRequirement $supportedRequirement
     }
+
+    return $supportedRequirement
+}
+
+function Assert-NovaPesterModuleRequirementSupported {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$ModuleRequirement,
+        [Parameter(Mandatory)][pscustomobject]$SupportedRequirement
+    )
+
+    if ($ModuleRequirement.MinimumVersion -eq $SupportedRequirement.MinimumVersion -and $ModuleRequirement.MaximumVersion -eq $SupportedRequirement.MaximumVersion) {
+        return
+    }
+
+    $supportedVersionText = Get-NovaPesterVersionRangeText -ModuleRequirement $SupportedRequirement
+    $declaredVersionText = Get-NovaPesterVersionRangeText -ModuleRequirement $ModuleRequirement
+    Stop-NovaOperation -Message "Nova tests support Pester only from $supportedVersionText. project.json declares Pester from $declaredVersionText. Update project.json to match Nova's supported range and try again." -ErrorId 'Nova.Dependency.UnsupportedPesterVersionRequirement' -Category InvalidData -TargetObject 'project.json'
+}
+
+function Get-NovaPesterVersionText {
+    [CmdletBinding()]
+    param(
+        [AllowNull()][object]$InputObject,
+        [Parameter(Mandatory)][string]$Name,
+        [Parameter(Mandatory)][string]$DefaultValue
+    )
+
+    $value = [string](Get-NovaPesterSettingValue -InputObject $InputObject -Name $Name)
+    if ( [string]::IsNullOrWhiteSpace($value)) {
+        return $DefaultValue
+    }
+
+    return $value
+}
+
+function Get-NovaPesterVersionRangeText {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$ModuleRequirement
+    )
+
+    return "$( $ModuleRequirement.MinimumVersion ) through $( $ModuleRequirement.MaximumVersion )"
+}
+
+function Get-AvailableNovaPesterModule {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$ModuleRequirement
+    )
+
+    return @(
+    Get-Module -Name Pester -ListAvailable |
+            Where-Object {Test-NovaPesterModuleVersionSupported -Version $_.Version -ModuleRequirement $ModuleRequirement} |
+            Sort-Object Version -Descending
+    )
+}
+
+function Test-NovaPesterModuleVersionSupported {
+    [CmdletBinding()]
+    param(
+        [AllowNull()][object]$Version,
+        [Parameter(Mandatory)][pscustomobject]$ModuleRequirement
+    )
+
+    if ($null -eq $Version) {
+        return $false
+    }
+
+    $resolvedVersion = [version]$Version
+    return $resolvedVersion -ge $ModuleRequirement.MinimumVersion -and $resolvedVersion -le $ModuleRequirement.MaximumVersion
+}
+
+function Get-NovaPesterDependencyMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$ModuleRequirement
+    )
+
+    $supportedVersionText = Get-NovaPesterVersionRangeText -ModuleRequirement $ModuleRequirement
+    $installedVersion = @(
+    Get-Module -Name Pester -ListAvailable |
+            Sort-Object Version -Descending |
+            ForEach-Object {[string]$_.Version} |
+            Select-Object -Unique
+    )
+    if ($installedVersion.Count -eq 0) {
+        return "The module Pester must be installed to run Nova tests. Install a supported Pester version from $supportedVersionText and try again."
+    }
+
+    return "Nova tests require Pester from $supportedVersionText. Installed versions: $( $installedVersion -join ', ' ). Install a supported Pester 5.x version and try again."
+}
+
+function Import-NovaSupportedPesterModule {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$ModuleSpecification
+    )
+
+    Import-Module -FullyQualifiedName $ModuleSpecification.FullyQualifiedName -Force -ErrorAction Stop | Out-Null
 }
 
 function Get-NovaTestWorkflowContext {
@@ -27,11 +188,12 @@ function Get-NovaTestWorkflowContext {
         [Parameter(Mandatory)][hashtable]$BoundParameters
     )
 
-    Test-ProjectSchema | Out-Null
-    Assert-NovaPesterAvailable
     $projectInfo = Get-NovaProjectInfo
+    Test-ProjectSchema | Out-Null
+    $pesterModuleSpecification = Assert-NovaPesterAvailable -ProjectInfo $projectInfo
     $workflowProfile = Get-NovaTestWorkflowProfile -TestOption $TestOption
     $pesterConfig = New-PesterConfiguration -Hashtable $projectInfo.Pester
+    Add-Member -InputObject $pesterConfig -MemberType NoteProperty -Name PesterModuleSpecification -Value $pesterModuleSpecification -Force
     $coverageConfiguration = Get-NovaPesterCoverageConfigurationState -ProjectInfo $projectInfo -CoverageEnabled:$workflowProfile.CoverageEnabled
     $pesterConfig.CodeCoverage.Enabled = $coverageConfiguration.Enabled
     $pesterConfig.CodeCoverage.Path = $coverageConfiguration.Path
@@ -62,6 +224,7 @@ function Get-NovaTestWorkflowContext {
         CommandName = $workflowProfile.CommandName
         OverrideWarningRequested = $BoundParameters.ContainsKey('OverrideWarning') -and [bool]$BoundParameters.OverrideWarning
         ProjectInfo = $projectInfo
+        PesterModuleSpecification = $pesterModuleSpecification
         PesterSettings = Get-NovaTestWorkflowPesterConfiguration -ProjectPesterSettings $projectInfo.Pester -CoverageEnabled:$workflowProfile.CoverageEnabled
         PesterConfig = $pesterConfig
         TestResultPath = $testResultPath

src/private/quality/InvokeNovaTestWorkflow.ps1

@@ -153,7 +153,8 @@ function Invoke-NovaPesterWithSuppressedProgress {
         $heartbeatMilliseconds = 2000
     }
 
-    $execution = Get-NovaPesterExecution -Configuration $Configuration
+    $moduleSpecification = Get-NovaPropertyValue -InputObject $Configuration -Name 'PesterModuleSpecification'
+    $execution = Get-NovaPesterExecution -Configuration $Configuration -ModuleSpecification $moduleSpecification
     try {
         Write-NovaTestWorkflowPesterProgress -Execution $execution -ProgressContext $ProgressContext
         while (-not (Wait-NovaPesterExecution -Execution $execution -TimeoutMilliseconds $HeartbeatMilliseconds)) {
@@ -323,13 +324,19 @@ function Write-NovaPesterHostInformationMessage {
 function Get-NovaPesterExecution {
     [CmdletBinding()]
     param(
-        [Parameter(Mandatory)][object]$Configuration
+        [Parameter(Mandatory)][object]$Configuration,
+        [AllowNull()][object]$ModuleSpecification
     )
 
     $powershell = [powershell]::Create()
     $command = @'
-param($Configuration)
-Import-Module Pester -ErrorAction Stop
+param($Configuration, $ModuleSpecification)
+if ($null -ne $ModuleSpecification) {
+    Import-Module -FullyQualifiedName $ModuleSpecification -Force -ErrorAction Stop
+}
+else {
+    Import-Module Pester -ErrorAction Stop
+}
 $previousProgressPreference = $global:ProgressPreference
 $global:ProgressPreference = 'SilentlyContinue'
 try {
@@ -338,7 +345,12 @@ try {
     $global:ProgressPreference = $previousProgressPreference
 }
 '@
-    $null = $powershell.AddScript($command).AddArgument($Configuration)
+    $moduleImportSpecification = $null
+    if ($null -ne $ModuleSpecification) {
+        $moduleImportSpecification = Get-NovaPropertyValue -InputObject $ModuleSpecification -Name 'FullyQualifiedName'
+    }
+
+    $null = $powershell.AddScript($command).AddArgument($Configuration).AddArgument($moduleImportSpecification)
 
     return [pscustomobject]@{
         PowerShell = $powershell

tests/RunQualityLoop.Tests.ps1

@@ -0,0 +1,17 @@
+BeforeAll {
+    $script:repoRoot = Split-Path -Parent $PSScriptRoot
+    $script:runScriptPath = Join-Path $script:repoRoot 'run.ps1'
+}
+
+Describe 'run.ps1 quality loop' {
+    It 'runs Invoke-NovaTest and Test-NovaBuild through fresh child pwsh sessions' {
+        $content = Get-Content -LiteralPath $script:runScriptPath -Raw
+
+        $content.Contains('function Invoke-NovaFreshValidationCommand') | Should -BeTrue
+        $content.Contains('& pwsh -NoLogo -NoProfile -Command $Command') | Should -BeTrue
+        $content.Contains('Invoke-NovaFreshValidationCommand -Command "Import-Module ''$builtModulePath'' -Force -ErrorAction Stop; Invoke-NovaTest"') | Should -BeTrue
+        $content.Contains('Invoke-NovaFreshValidationCommand -Command "Import-Module ''$builtModulePath'' -Force -ErrorAction Stop; Test-NovaBuild"') | Should -BeTrue
+    }
+}
+
+

tests/TestHelpers/PublicCommandIntegration.ps1

@@ -46,3 +46,55 @@ function Invoke-NovaPublicCommandIntegrationInProjectRoot {
 
     return Invoke-NovaPublicCommandIntegrationInLocation -Path $ProjectRoot -ScriptBlock $ScriptBlock
 }
+
+function Invoke-NovaPublicCommandIntegrationInIsolatedSession {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$ProjectRoot,
+        [string]$Path = $ProjectRoot,
+        [Parameter(Mandatory)][scriptblock]$ScriptBlock
+    )
+
+    $runnerPath = Join-Path $TestDrive 'Run-NovaPublicCommandIntegration.ps1'
+    $moduleManifestPath = Join-Path $ProjectRoot 'dist/NovaModuleTools/NovaModuleTools.psd1'
+    $escapedManifestPath = $moduleManifestPath.Replace("'", "''")
+    $escapedLocationPath = $Path.Replace("'", "''")
+    $runnerContent = @"
+function New-NovaPublicCommandIntegrationPesterModule {
+    param(
+        [Parameter(Mandatory)][string]`$BasePath,
+        [Parameter(Mandatory)][string]`$Version
+    )
+
+    `$moduleRoot = Join-Path `$BasePath "Pester/`$Version"
+    `$null = New-Item -ItemType Directory -Path `$moduleRoot -Force
+    Set-Content -LiteralPath (Join-Path `$moduleRoot 'Pester.psm1') -Value '' -Encoding utf8
+    `$manifestContent = @(
+        '@{'
+        "    RootModule = 'Pester.psm1'"
+    "    ModuleVersion = '`$Version'"
+    "    GUID = '`$([guid]::NewGuid().Guid)'"
+        '    FunctionsToExport = @()'
+        '    CmdletsToExport = @()'
+        '    VariablesToExport = @()'
+        '    AliasesToExport = @()'
+        '}'
+    ) -join [Environment]::NewLine
+    Set-Content -LiteralPath (Join-Path `$moduleRoot 'Pester.psd1') -Value `$manifestContent -Encoding utf8
+}
+
+Import-Module '$escapedManifestPath' -Force -ErrorAction Stop
+Set-Location -LiteralPath '$escapedLocationPath'
+& {
+$($ScriptBlock.ToString() )
+}
+"@
+    Set-Content -LiteralPath $runnerPath -Value $runnerContent -Encoding utf8
+
+    $output = & pwsh -NoLogo -NoProfile -File $runnerPath 2>&1
+    return [pscustomobject]@{
+        ExitCode = $LASTEXITCODE
+        Output = @($output)
+    }
+}
+