#215 feat: enhance Test-NovaBuild with progress reporting and actionable guidance in WhatIf mode

refactor(Test-NovaBuild): align with terminal-ux-design principles
Fixes #227

Author: stiwicourage

CHANGELOG.md

@@ -29,6 +29,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `New-NovaModulePackage` now shows progress for build validation and artifact creation, ends with the package target plus the next suggested deployment step, and uses a package-plan summary in `-WhatIf` mode.
 - `Publish-NovaModule` now shows progress for build validation, publish, local import, and CI restore phases, ends with the publish target plus a suggested verification step, and uses a publish-plan summary in `-WhatIf` mode.
 - `Set-NovaUpdateNotificationPreference` now ends with a clear success or preview summary, prints the settings file path, suggests `Get-NovaUpdateNotificationPreference` as the next verification step, and gives a more actionable validation error when no enable/disable switch is supplied.
+- `Test-NovaBuild` now shows progress across the main test phases, ends with the result file path plus a coverage summary and next-step hint when tests pass, uses a test-plan summary in `-WhatIf` mode, and fails with more actionable guidance when Pester or coverage checks fail.
 
 ### Deprecated
 

RELEASE_NOTE.md

@@ -25,6 +25,7 @@ This file summarizes the release notes for NovaModuleTools. **UNRELEASED** chang
 - `New-NovaModulePackage` now shows progress for build validation and artifact creation, ends with the package target plus the next suggested deployment step, and uses a package-plan summary in `-WhatIf` mode.
 - `Publish-NovaModule` now shows progress for build validation, publish, local import, and CI restore phases, ends with the publish target plus a suggested verification step, and uses a publish-plan summary in `-WhatIf` mode.
 - `Set-NovaUpdateNotificationPreference` now ends with a clear success or preview summary, prints the settings file path, suggests `Get-NovaUpdateNotificationPreference` as the next verification step, and gives a more actionable validation error when no enable/disable switch is supplied.
+- `Test-NovaBuild` now shows progress across the main test phases, ends with the result file path plus a coverage summary and next-step hint when tests pass, uses a test-plan summary in `-WhatIf` mode, and fails with more actionable guidance when Pester or coverage checks fail.
 
 ### Deprecated
 

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

@@ -40,6 +40,8 @@ With the default
 
 This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShouldProcess`. Use `-WhatIf` to preview the planned test run and XML output path without creating `artifacts/` or invoking Pester.
 
+During a test run, Nova shows progress for the optional pre-test build, test-result preparation, the Pester run, result writing, and code-coverage validation. When tests pass, Nova prints the result file path, a coverage summary when one is available, and a suggested next step. In `-WhatIf` mode, Nova ends with a test-plan summary instead of invoking Pester.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
@@ -48,15 +50,15 @@ This command supports `-WhatIf` and `-Confirm` through PowerShell `SupportsShoul
 PS> Test-NovaBuild
 ```
 
-Runs the Pester tests for the current project.
+Runs the Pester tests for the current project and prints the result file path plus the next suggested command when the run succeeds.
 
 ### EXAMPLE 2
 
 ```text
 PS> Test-NovaBuild -Build
 ```
 
-Builds the project first, then runs the configured Pester test workflow.
+Builds the project first, then runs the configured Pester test workflow with the same completion summary as a normal test run.
 
 ### EXAMPLE 3
 
@@ -88,15 +90,15 @@ Overrides the console output settings for the current test run while keeping col
 PS> Test-NovaBuild -WhatIf
 ```
 
-Previews the planned Pester run without executing tests or writing `artifacts/TestResults.xml`.
+Previews the planned Pester run, prints the planned result file path, and does not execute tests or write `artifacts/TestResults.xml`.
 
 ### EXAMPLE 7
 
 ```text
 PS> Test-NovaBuild -Build -WhatIf
 ```
 
-Previews the build-before-test workflow without rebuilding the project or running Pester.
+Previews the build-before-test workflow, including the planned result file path and configured coverage target, without rebuilding the project or running Pester.
 
 ## PARAMETERS
 
@@ -258,6 +260,8 @@ If `project.json` configures `Pester.CodeCoverage.CoveragePercentTarget`, `Test-
 `Test-NovaBuild` uses `SupportsShouldProcess`, so `Get-Help Test-NovaBuild -Full` surfaces native `-WhatIf` and
 `-Confirm` support.
 
+Use `Ctrl+C` if you need to stop a running test workflow before Pester completes.
+
 ## RELATED LINKS
 
 - [Get-NovaProjectInfo](./Get-NovaProjectInfo.md)

src/private/quality/InvokeNovaTestWorkflow.ps1

@@ -5,34 +5,225 @@ function Invoke-NovaTestWorkflow {
         [switch]$ShouldRun
     )
 
-    if (Test-NovaTestWorkflowBuildRequested -WorkflowContext $WorkflowContext) {
-        $workflowParams = Get-NovaBuildCommandParameterMap -WorkflowParams $WorkflowContext.WorkflowParams -OverrideWarningRequested:(($WorkflowContext.PSObject.Properties.Name -contains 'OverrideWarningRequested') -and $WorkflowContext.OverrideWarningRequested)
-        Invoke-NovaBuild @workflowParams
+    $progressActivity = 'Running Nova test workflow'
+    $whatIfEnabled = Test-NovaWhatIfWorkflowContext -WorkflowContext $WorkflowContext
+    $testResult = $null
+    $shouldRunWorkflow = Test-NovaTestWorkflowShouldRun -WorkflowContext $WorkflowContext -BoundParameters $PSBoundParameters -ShouldRun:$ShouldRun
+
+    try {
+        Invoke-NovaTestWorkflowBuildStep -WorkflowContext $WorkflowContext -Activity $progressActivity -WhatIfEnabled:$whatIfEnabled
+
+        if (-not $shouldRunWorkflow) {
+            Write-NovaTestWorkflowPreviewResult -WorkflowContext $WorkflowContext -WhatIfEnabled:$whatIfEnabled
+            return
+        }
+
+        $testResult = Invoke-NovaTestWorkflowExecution -WorkflowContext $WorkflowContext -Activity $progressActivity
+    } finally {
+        Write-Progress -Activity $progressActivity -Completed
+    }
+
+    Write-NovaTestWorkflowResult -WorkflowContext $WorkflowContext -TestResult $testResult
+}
+
+function Invoke-NovaTestWorkflowBuildStep {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [Parameter(Mandatory)][string]$Activity,
+        [switch]$WhatIfEnabled
+    )
+
+    if (-not (Test-NovaTestWorkflowBuildRequested -WorkflowContext $WorkflowContext)) {
+        return
     }
 
-    if (-not (Test-NovaTestWorkflowShouldRun -WorkflowContext $WorkflowContext -BoundParameters $PSBoundParameters -ShouldRun:$ShouldRun)) {
+    $buildCommandParameters = Get-NovaBuildCommandParameterMap -WorkflowParams (Get-NovaPropertyValue -InputObject $WorkflowContext -Name 'WorkflowParams') -OverrideWarningRequested:(($WorkflowContext.PSObject.Properties.Name -contains 'OverrideWarningRequested') -and $WorkflowContext.OverrideWarningRequested)
+    Invoke-NovaTestWorkflowStep -Activity $Activity -Status (Get-NovaTestWorkflowBuildStatus -WhatIfEnabled:$WhatIfEnabled) -PercentComplete 20 -Action {
+        Invoke-NovaBuild @buildCommandParameters
+    }
+}
+
+function Write-NovaTestWorkflowPreviewResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled
+    )
+
+    if (-not $WhatIfEnabled) {
         return
     }
 
-    Initialize-NovaPesterArtifactDirectory -WorkflowContext $WorkflowContext
+    Write-NovaTestWorkflowResult -WorkflowContext $WorkflowContext -WhatIfEnabled
+}
+
+function Invoke-NovaTestWorkflowExecution {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [Parameter(Mandatory)][string]$Activity
+    )
+
+    Invoke-NovaTestWorkflowStep -Activity $Activity -Status 'Preparing the test result directory' -PercentComplete 40 -Action {
+        Initialize-NovaPesterArtifactDirectory -WorkflowContext $WorkflowContext
+    }
+
     $WorkflowContext.PesterConfig.TestResult.OutputPath = $WorkflowContext.TestResultPath
     $coverageTargetAssertion = Get-NovaCoverageTargetAssertionScriptBlock -WorkflowContext $WorkflowContext
+    $testResult = Invoke-NovaTestWorkflowStep -Activity $Activity -Status 'Running Pester tests' -PercentComplete 70 -Action {
+        Invoke-NovaPesterWithSuppressedProgress -Configuration $WorkflowContext.PesterConfig
+    }
+
+    Invoke-NovaTestWorkflowStep -Activity $Activity -Status 'Writing the test result report' -PercentComplete 85 -Action {
+        & $WorkflowContext.TestResultArtifactWriter.ScriptBlock -TestResult $testResult -OutputPath $WorkflowContext.TestResultPath -ReportWriter $WorkflowContext.TestResultReportWriter.ScriptBlock
+    }
+
+    if ($testResult.Result -ne 'Passed') {
+        Stop-NovaOperation -Message (Get-NovaTestWorkflowFailureMessage -WorkflowContext $WorkflowContext) -ErrorId 'Nova.Workflow.TestRunFailed' -Category InvalidOperation -TargetObject $WorkflowContext.TestResultPath
+    }
+
+    Invoke-NovaTestWorkflowStep -Activity $Activity -Status 'Checking the configured code coverage target' -PercentComplete 95 -Action {
+        & $coverageTargetAssertion -WorkflowContext $WorkflowContext -TestResult $testResult
+    }
+
+    return $testResult
+}
+
+function Invoke-NovaTestWorkflowStep {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][string]$Activity,
+        [Parameter(Mandatory)][string]$Status,
+        [Parameter(Mandatory)][int]$PercentComplete,
+        [Parameter(Mandatory)][scriptblock]$Action
+    )
+
+    Write-Progress -Activity $Activity -Status $Status -PercentComplete $PercentComplete
+    & $Action
+}
+
+function Get-NovaTestWorkflowBuildStatus {
+    [CmdletBinding()]
+    param(
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return 'Previewing the build-before-test workflow'
+    }
+
+    return 'Building the current project state'
+}
+
+function Invoke-NovaPesterWithSuppressedProgress {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][object]$Configuration
+    )
 
     $previousProgressPreference = $global:ProgressPreference
     $global:ProgressPreference = 'SilentlyContinue'
     try {
-        $testResult = Invoke-NovaPester -Configuration $WorkflowContext.PesterConfig
+        return Invoke-NovaPester -Configuration $Configuration
     } finally {
         $global:ProgressPreference = $previousProgressPreference
     }
+}
 
-    & $WorkflowContext.TestResultArtifactWriter.ScriptBlock -TestResult $testResult -OutputPath $WorkflowContext.TestResultPath -ReportWriter $WorkflowContext.TestResultReportWriter.ScriptBlock
+function Get-NovaTestWorkflowFailureMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext
+    )
 
-    if ($testResult.Result -ne 'Passed') {
-        Stop-NovaOperation -Message 'Tests failed' -ErrorId 'Nova.Workflow.TestRunFailed' -Category InvalidOperation -TargetObject $WorkflowContext.TestResultPath
+    return "Pester reported one or more failing tests. Review the output above and the test result file at $( $WorkflowContext.TestResultPath ), then rerun Test-NovaBuild."
+}
+
+function Write-NovaTestWorkflowResult {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [AllowNull()][object]$TestResult,
+        [switch]$WhatIfEnabled
+    )
+
+    Write-Message (Get-NovaTestWorkflowStatusMessage -WorkflowContext $WorkflowContext -WhatIfEnabled:$WhatIfEnabled) -color Green
+    Write-Message "Results file: $( $WorkflowContext.TestResultPath )"
+
+    $coverageMessage = Get-NovaTestWorkflowCoverageMessage -WorkflowContext $WorkflowContext -TestResult $TestResult -WhatIfEnabled:$WhatIfEnabled
+    if (-not [string]::IsNullOrWhiteSpace($coverageMessage)) {
+        Write-Message $coverageMessage
+    }
+
+    foreach ($line in (Get-NovaTestWorkflowNextStepLine -WhatIfEnabled:$WhatIfEnabled)) {
+        Write-Message $line
+    }
+}
+
+function Get-NovaTestWorkflowStatusMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return "Test plan ready for $( $WorkflowContext.ProjectInfo.ProjectName )"
+    }
+
+    return "Pester tests passed for $( $WorkflowContext.ProjectInfo.ProjectName )"
+}
+
+function Get-NovaTestWorkflowCoverageMessage {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)][pscustomobject]$WorkflowContext,
+        [AllowNull()][object]$TestResult,
+        [switch]$WhatIfEnabled
+    )
+
+    $coveragePercentTarget = Get-NovaConfiguredCoveragePercentTarget -WorkflowContext $WorkflowContext
+    if ($WhatIfEnabled) {
+        if ($null -eq $coveragePercentTarget) {
+            return $null
+        }
+
+        return "Configured coverage target: $( Format-NovaCoveragePercentValue -Value ([double]$coveragePercentTarget) )%"
     }
 
-    & $coverageTargetAssertion -WorkflowContext $WorkflowContext -TestResult $testResult
+    $codeCoverage = Get-NovaPropertyValue -InputObject $TestResult -Name 'CodeCoverage'
+    $coveragePercent = Get-NovaPropertyValue -InputObject $codeCoverage -Name 'CoveragePercent'
+    if ($null -eq $coveragePercent -or [string]::IsNullOrWhiteSpace([string]$coveragePercent)) {
+        return $null
+    }
+
+    $formattedCoverage = Format-NovaCoveragePercentValue -Value ([double]$coveragePercent)
+    if ($null -eq $coveragePercentTarget) {
+        return "Measured code coverage: $formattedCoverage%"
+    }
+
+    $formattedTarget = Format-NovaCoveragePercentValue -Value ([double]$coveragePercentTarget)
+    return "Measured code coverage: $formattedCoverage% (target: $formattedTarget%)"
+}
+
+function Get-NovaTestWorkflowNextStepLine {
+    [CmdletBinding()]
+    param(
+        [switch]$WhatIfEnabled
+    )
+
+    if ($WhatIfEnabled) {
+        return @(
+            'Next step:'
+            'Run Test-NovaBuild without -WhatIf when you are ready to execute the test workflow.'
+        )
+    }
+
+    return @(
+        'Next step:'
+        'Publish-NovaModule -Local'
+    )
 }
 
 function Test-NovaTestWorkflowBuildRequested {
@@ -129,7 +320,7 @@ function Get-NovaDefaultCoverageTargetAssertionScriptBlock {
         $codeCoverage = & $propertyReader -InputObject $TestResult -Name 'CodeCoverage'
         $coveragePercent = & $propertyReader -InputObject $codeCoverage -Name 'CoveragePercent'
         if ($null -eq $coveragePercent -or [string]::IsNullOrWhiteSpace([string]$coveragePercent)) {
-            $exception = [System.IO.InvalidDataException]::new("Code coverage target $formattedTarget% is configured, but the Pester result did not include a coverage percentage.")
+            $exception = [System.IO.InvalidDataException]::new("Code coverage target $formattedTarget% is configured, but the Pester result did not include a coverage percentage. Review the coverage settings in project.json and the test result file at $resolvedTargetObject.")
             $errorRecord = [System.Management.Automation.ErrorRecord]::new($exception, 'Nova.Workflow.CodeCoveragePercentMissing', [System.Management.Automation.ErrorCategory]::InvalidData, $resolvedTargetObject)
             throw $errorRecord
         }
@@ -140,7 +331,7 @@ function Get-NovaDefaultCoverageTargetAssertionScriptBlock {
         }
 
         $formattedCoverage = & $percentFormatter -Value $coveragePercent
-        $exception = [System.InvalidOperationException]::new("Code coverage $formattedCoverage% did not meet the configured target $formattedTarget%.")
+        $exception = [System.InvalidOperationException]::new("Code coverage $formattedCoverage% did not meet the configured target $formattedTarget%. Review the failing tests or coverage settings, then rerun Test-NovaBuild.")
         $errorRecord = [System.Management.Automation.ErrorRecord]::new($exception, 'Nova.Workflow.CodeCoverageTargetNotMet', [System.Management.Automation.ErrorCategory]::InvalidOperation, $resolvedTargetObject)
         throw $errorRecord
     }.GetNewClosure()

tests/private/quality/InvokeNovaTestWorkflow.TestSupport.ps1

@@ -10,6 +10,8 @@ function Stop-NovaOperation {
 function Invoke-NovaBuild {}
 function Invoke-NovaPester {param($Configuration)}
 function Get-NovaBuildCommandParameterMap {param($WorkflowParams, [switch]$OverrideWarningRequested) return @{}}
+function Write-Message {param([string]$Text, [string]$color)}
+function Write-Progress {param([string]$Activity, [string]$Status, [int]$PercentComplete, [switch]$Completed)}
 function New-NovaInvokeNovaTestWorkflowContext {
     param(
         [hashtable]$PesterSettings = @{},
@@ -21,7 +23,7 @@ function New-NovaInvokeNovaTestWorkflowContext {
     return [pscustomobject]@{
         BuildRequested = $BuildRequested
         WorkflowParams = $WorkflowParams
-        ProjectInfo = [pscustomobject]@{Pester = $PesterSettings}
+        ProjectInfo = [pscustomobject]@{ProjectName = 'NovaModuleTools'; Pester = $PesterSettings}
         TestResultDirectory = $TestResultDirectory
         TestResultPath = Join-Path $TestResultDirectory 'TestResults.xml'
         PesterConfig = [pscustomobject]@{TestResult = [pscustomobject]@{OutputPath = $null}}