Pester 6 - Drop stale v4/v5 references and take the version out of names (#10520)

Author: andreasjordan

.devcontainer/Dockerfile

@@ -23,9 +23,9 @@ RUN echo "export HISTFILE=/commandhistory/.bash_history" >> "/root/.bashrc" \
 SHELL ["/opt/microsoft/powershell/7/pwsh", "-c"]
 RUN Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
 
-# Install Pester, has to be 4.4.3 because 4.4.2 has bug in Unix machines
+# Install Pester, pinned to the version the test suite runs on
 SHELL ["/opt/microsoft/powershell/7/pwsh", "-c"]
-RUN $ErrorActionPreference='Stop'; Install-Module -Name Pester -Force -SkipPublisherCheck -MaximumVersion 4.4.3;
+RUN $ErrorActionPreference='Stop'; Install-Module -Name Pester -Force -SkipPublisherCheck -RequiredVersion 6.0.0;
 
 # Install PSScriptAnalyzer
 SHELL ["/opt/microsoft/powershell/7/pwsh", "-c"]

.github/prompts/prompt.md

@@ -344,7 +344,7 @@ Describe "Get-DesiredRunnerPools demand-driven sizing" {
 
 Describe "Get-PoolJobDemandFromJobs" {
     BeforeAll {
-        # Defined in BeforeAll, not the Describe body: Pester 5 runs the Describe body
+        # Defined in BeforeAll, not the Describe body: Pester runs the Describe body
         # during discovery, so a function declared there does not exist when the It
         # blocks execute. This matches the helper idiom in the top-level BeforeAll.
         function New-TestJob {

.github/runners/tests/runner-policy.Tests.ps1

@@ -21,7 +21,7 @@ msbuild.binlog
 # Local constant file
 tests/constants.local.ps1
 
-# Local coverage file produced by pester5
+# Local coverage file produced by Pester
 coverage.xml
 
 # For those that want to use Docker images for testing

.gitignore

@@ -93,8 +93,8 @@ function Invoke-ManualPester {
     Every test file has to carry this requirement in its first line:
     #Requires -Module @{ ModuleName="Pester"; ModuleVersion="5.0" }
 
-    A file without it is reported and skipped rather than run, because dbatools no longer has
-    Pester 4 tests and a missing header is a mistake in the test file.
+    A file without it is reported and skipped rather than run, because a missing header is a
+    mistake in the test file and not a request for a different runtime.
 #>
     [CmdletBinding()]
     param (
@@ -171,9 +171,9 @@ function Invoke-ManualPester {
             return (Get-ChildItem @splatCommandFile | Select-Object -First 1).FullName
         }
 
-        # Every test file has to declare the Pester 5 requirement. dbatools has no Pester 4 tests
-        # left, so a file without the header is a mistake in the file and not a request for an
-        # older runtime - it is reported instead of being run with something else.
+        # Every test file has to declare the minimum Pester version it needs. A file without the
+        # header is a mistake in the file and not a request for a different runtime - it is
+        # reported instead of being run with something else.
         function Test-PesterTestHeader($testFilePath) {
             $testFileContent = Get-Content -Path $testFilePath -Raw
             return $testFileContent -match "#Requires\s+-Module\s+@\{\s+ModuleName=`"Pester`";\s+ModuleVersion=`"5\."
@@ -198,10 +198,12 @@ function Invoke-ManualPester {
 
         $invokeFormatterVersion = (Get-Command Invoke-Formatter -ErrorAction SilentlyContinue).Version
         $HasScriptAnalyzer = $null -ne $invokeFormatterVersion
-        # Pester 5 introduced the configuration object this function builds, and every test file in
-        # the repository requires it. The CI pins 6.0.0 in tests\appveyor.prep.ps1.
-        $MinimumPesterVersion = [Version] "5.0.0.0"
-        $MaximumPesterVersion = [Version] "7.0.0.0"
+        # The suite runs on Pester 6, which the CI pins to 6.0.0 in tests\appveyor.prep.ps1. A local
+        # run is gated to the same major version so a local pass means the same thing CI does.
+        # Three components, not four: Pester reports itself as 6.0.0, and [Version] treats an absent
+        # revision as -1, so "6.0.0" would compare as lower than "6.0.0.0" and reject the pinned build.
+        $MinimumPesterVersion = [Version] "6.0.0"
+        $MaximumPesterVersion = [Version] "7.0.0"
         $PesterVersion = (Get-Command Invoke-Pester -ErrorAction SilentlyContinue).Version
         $HasPester = $null -ne $PesterVersion
         $ScriptAnalyzerCorrectVersion = "1.18.2"
@@ -365,7 +367,7 @@ function Invoke-ManualPester {
 
         foreach ($f in $AllTestsWithinScenario) {
             if (-not (Test-PesterTestHeader -testFilePath $f.FullName)) {
-                Write-Warning "$($f.Name) does not declare the mandatory Pester 5 header, skipping it. See tests\CLAUDE.md."
+                Write-Warning "$($f.Name) does not declare the mandatory Pester header, skipping it. See tests\CLAUDE.md."
                 continue
             }
 
@@ -394,40 +396,40 @@ function Invoke-ManualPester {
             }
 
             Write-DetailedMessage "Running tests $($f.Name)"
-            $pester5Config = New-PesterConfiguration
-            $pester5Config.Run.Path = $f.FullName
-            $pester5Config.Run.PassThru = $true
-            $pester5Config.Output.Verbosity = $Show
+            $pesterConfig = New-PesterConfiguration
+            $pesterConfig.Run.Path = $f.FullName
+            $pesterConfig.Run.PassThru = $true
+            $pesterConfig.Output.Verbosity = $Show
             if ($Coverage) {
                 if ($CoverFiles.Count -eq 0) {
                     Write-Warning "Cannot measure coverage for $($f.Name), no command file found for it"
                 } else {
-                    $pester5Config.CodeCoverage.Enabled = $true
+                    $pesterConfig.CodeCoverage.Enabled = $true
                     Write-DetailedMessage "We're going to target these files for coverage:"
                     foreach ($cf in $CoverFiles) {
                         Write-DetailedMessage "$cf"
                     }
-                    $pester5Config.CodeCoverage.Path = $CoverFiles
+                    $pesterConfig.CodeCoverage.Path = $CoverFiles
                 }
             }
             if (!($testInt)) {
-                $pester5Config.Filter.ExcludeTag = "IntegrationTests"
+                $pesterConfig.Filter.ExcludeTag = "IntegrationTests"
             }
-            $pester5Result = Invoke-Pester -Configuration $pester5Config
+            $pesterResult = Invoke-Pester -Configuration $pesterConfig
 
             $runSummary += [PSCustomObject]@{
                 TestFileName    = $f.Name
-                Result          = $pester5Result.Result
-                TotalCount      = $pester5Result.TotalCount
-                PassedCount     = $pester5Result.PassedCount
-                FailedCount     = $pester5Result.FailedCount
-                SkippedCount    = $pester5Result.SkippedCount
-                DurationSeconds = [int]$pester5Result.Duration.TotalSeconds
-                Failed          = $pester5Result.Failed
+                Result          = $pesterResult.Result
+                TotalCount      = $pesterResult.TotalCount
+                PassedCount     = $pesterResult.PassedCount
+                FailedCount     = $pesterResult.FailedCount
+                SkippedCount    = $pesterResult.SkippedCount
+                DurationSeconds = [int]$pesterResult.Duration.TotalSeconds
+                Failed          = $pesterResult.Failed
             }
 
             if ($PassThru) {
-                $pester5Result
+                $pesterResult
             }
 
             if ($ScriptAnalyzer) {

private/testing/Invoke-ManualPester.ps1

@@ -285,7 +285,7 @@ A `BeforeDiscovery` block inside the `Describe` is the tidier home for the same
 
 Pester reads a test file twice. First it **discovers** the tests: it runs the file top to bottom, evaluates every `Describe`, `Context` and `It` *header*, and builds the tree. Only then does it **run** the tests: the `BeforeAll`, `BeforeEach`, `It` and `AfterAll` *bodies*.
 
-Anything a header needs - `-Skip:`, `-ForEach`, the test name - has to exist at discovery time. Anything a body needs has to exist at run time. The two do not share variables, and this is the single biggest source of confusion left over from Pester v4.
+Anything a header needs - `-Skip:`, `-ForEach`, the test name - has to exist at discovery time. Anything a body needs has to exist at run time. The two do not share variables, and this is the single biggest source of confusion when writing a test file.
 
 `BeforeDiscovery` is the block for discovery-time code. It keeps that code out of the `Describe` body while still running early enough:
 

tests/CLAUDE.md

@@ -57,13 +57,11 @@ Describe $CommandName -Tag IntegrationTests {
 
     Context "Validating Database Input" {
         BeforeAll {
-            # The command does not respect -WarningAction SilentlyContinue inside of this pester test - still don't know why, retest with pester 5
-            $systemWarnVar = $null
-            Invoke-DbaDbCorruption -SqlInstance $TestConfig.InstanceSingle -Database "master" -WarningVariable systemWarnVar 3> $null
+            Invoke-DbaDbCorruption -SqlInstance $TestConfig.InstanceSingle -Database "master" -WarningAction SilentlyContinue
         }
 
         It "Should not allow you to corrupt system databases." {
-            $systemWarnVar -match "may not corrupt system databases" | Should -Be $true
+            $WarnVar | Should -Match "may not corrupt system databases"
         }
 
         It "Should fail if more than one database is specified" {

tests/Invoke-DbaDbCorruption.Tests.ps1

@@ -61,6 +61,10 @@ $global:dbatools_dotsourcemodule = $true
 # imports the psm1 to be able to use internal functions in tests
 Import-Module "$ModuleBase\dbatools.psm1" -Force
 
+# The one place this script names a Pester version. It has to match tests\appveyor.prep.ps1, which
+# is what actually installs the module on the build worker.
+$PesterRequiredVersion = "6.0.0"
+
 function Split-ArrayInParts($array, [int]$parts) {
     #splits an array in "equal" parts
     $size = $array.Length / $parts
@@ -179,7 +183,7 @@ function Get-ComprehensiveErrorMessage {
     $debugInfo = @()
 
     try {
-        # Pester 5 error extraction with multiple fallbacks
+        # Pester error extraction with multiple fallbacks
         if ($TestResult.ErrorRecord -and $TestResult.ErrorRecord.Count -gt 0) {
             foreach ($errorRec in $TestResult.ErrorRecord) {
                 if ($errorRec.Exception) {
@@ -244,7 +248,7 @@ function Get-ComprehensiveErrorMessage {
             $errorMessages += "StdErr: $($TestResult.StandardError)"
         }
 
-        # Check Block.ErrorRecord for container-level errors (common in Pester 5)
+        # Check Block.ErrorRecord for container-level errors
         if ($TestResult.Block -and $TestResult.Block.ErrorRecord) {
             foreach ($blockError in $TestResult.Block.ErrorRecord) {
                 if ($blockError.Exception) {
@@ -325,7 +329,6 @@ function Export-TestFailureSummary {
 
     $failedTests = @()
 
-    # Pester 5 format
     $failedTests = $PesterRun.Tests | Where-Object { $PSItem.Passed -eq $false } | ForEach-Object {
         # Extract line number from stack trace
         $lineNumber = $null
@@ -357,17 +360,17 @@ function Export-TestFailureSummary {
     if ($failedTests.Count -gt 0) {
         $summary = @{
             TestFile      = $TestFile.Name
-            PesterVersion = "5"
+            PesterVersion = $PesterRequiredVersion
             TotalTests    = $PesterRun.TotalCount
             PassedTests   = $PesterRun.PassedCount
             FailedTests   = $PesterRun.FailedCount
             Duration      = $PesterRun.Duration.TotalMilliseconds
             Failures      = $failedTests
         }
 
-        $summaryFile = "$ModuleBase\TestFailureSummary_Pester5_${Counter}.json"
+        $summaryFile = "$ModuleBase\TestFailureSummary_${Counter}.json"
         $summary | ConvertTo-Json -Depth 10 | Out-File $summaryFile -Encoding UTF8
-        Push-AppveyorArtifact $summaryFile -FileName "TestFailureSummary_Pester5_${Counter}.json"
+        Push-AppveyorArtifact $summaryFile -FileName "TestFailureSummary_${Counter}.json"
     }
 }
 
@@ -386,8 +389,7 @@ if (-not $Finalize) {
 
     # Remove any previously loaded pester module
     Remove-Module -Name Pester -ErrorAction SilentlyContinue
-    # Import Pester 6 release candidate
-    Import-Module -Name Pester -RequiredVersion 6.0.0
+    Import-Module -Name Pester -RequiredVersion $PesterRequiredVersion
     Write-Host -Object "appveyor.pester: Running with Pester Version $((Get-Command Invoke-Pester -ErrorAction SilentlyContinue).Version)" -ForegroundColor DarkGreen
 
     # invoking a single invoke-pester consumes too much memory, let's go file by file
@@ -449,18 +451,18 @@ if (-not $Finalize) {
         foreach ($f in $AllTestsWithinScenario) {
             $Counter += 1
 
-            $pester5Config = New-PesterConfiguration
-            $pester5Config.Run.Path = $f.FullName
-            $pester5config.Run.PassThru = $true
-            $pester5config.Output.Verbosity = "None"
+            $pesterConfig = New-PesterConfiguration
+            $pesterConfig.Run.Path = $f.FullName
+            $pesterConfig.Run.PassThru = $true
+            $pesterConfig.Output.Verbosity = "None"
 
             #opt-in
             if ($IncludeCoverage) {
                 $CoverFiles = Get-CoverageIndications -Path $f -ModuleBase $ModuleBase
-                $pester5Config.CodeCoverage.Enabled = $true
-                $pester5Config.CodeCoverage.Path = $CoverFiles
-                $pester5Config.CodeCoverage.OutputFormat = "JaCoCo"
-                $pester5Config.CodeCoverage.OutputPath = "$ModuleBase\Pester5Coverage$PSVersion$Counter.xml"
+                $pesterConfig.CodeCoverage.Enabled = $true
+                $pesterConfig.CodeCoverage.Path = $CoverFiles
+                $pesterConfig.CodeCoverage.OutputFormat = "JaCoCo"
+                $pesterConfig.CodeCoverage.OutputPath = "$ModuleBase\PesterCoverage$PSVersion$Counter.xml"
             }
 
             $trialNo = 1
@@ -481,9 +483,9 @@ if (-not $Finalize) {
                 } catch {
                     Write-Host -Object "appveyor.pester: could not write the heartbeat. $($PSItem.Exception.Message)" -ForegroundColor Yellow
                 }
-                $PesterRun = Invoke-Pester -Configuration $pester5config
+                $PesterRun = Invoke-Pester -Configuration $pesterConfig
                 Write-Host -Object "`rCompleted $($f.FullName) in $([int]$PesterRun.Duration.TotalMilliseconds)ms" -ForegroundColor Cyan
-                $PesterRun | Export-Clixml -Path "$ModuleBase\Pester5Results$PSVersion$Counter.xml"
+                $PesterRun | Export-Clixml -Path "$ModuleBase\PesterResults$PSVersion$Counter.xml"
 
                 # Export failure summary for easier retrieval
                 Export-TestFailureSummary -TestFile $f -PesterRun $PesterRun -Counter $Counter -ModuleBase $ModuleBase
@@ -516,7 +518,7 @@ if (-not $Finalize) {
                         Outcome       = "Failed"
                         FailedCount   = $PesterRun.FailedCount
                         Duration      = $PesterRun.Duration.TotalMilliseconds
-                        PesterVersion = "5"
+                        PesterVersion = $PesterRequiredVersion
                     }
                 } else {
                     Update-AppveyorTest -Name $appvTestName -Framework NUnit -FileName $f.FullName -Outcome "Passed" -Duration $PesterRun.Duration.TotalMilliseconds
@@ -527,7 +529,7 @@ if (-not $Finalize) {
                         Attempt       = $trialNo
                         Outcome       = "Passed"
                         Duration      = $PesterRun.Duration.TotalMilliseconds
-                        PesterVersion = "5"
+                        PesterVersion = $PesterRequiredVersion
                     }
                     break
                 }
@@ -591,7 +593,7 @@ if (-not $Finalize) {
     }
 
     # What failed? How many tests did we run ?
-    $results = @(Get-ChildItem -Path "$ModuleBase\Pester5Results*.xml" | Import-Clixml)
+    $results = @(Get-ChildItem -Path "$ModuleBase\PesterResults*.xml" | Import-Clixml)
     $failedcount = $results | Select-Object -ExpandProperty FailedCount | Measure-Object -Sum | Select-Object -ExpandProperty Sum
     $faileditems = $results | Select-Object -ExpandProperty Tests | Where-Object { $PSItem.Passed -notlike $True }
     if ($faileditems) {
@@ -616,7 +618,7 @@ if (-not $Finalize) {
 
         # Save detailed failure information as artifact
         $detailedFailureSummary = @{
-            PesterVersion    = "5"
+            PesterVersion    = $PesterRequiredVersion
             TotalFailedTests = $faileditems.Count
             DetailedFailures = $detailedFailures | ForEach-Object {
                 @{
@@ -631,9 +633,9 @@ if (-not $Finalize) {
             }
         }
 
-        $detailedFailureFile = "$ModuleBase\DetailedTestFailures_Pester5.json"
+        $detailedFailureFile = "$ModuleBase\DetailedTestFailures.json"
         $detailedFailureSummary | ConvertTo-Json -Depth 10 | Out-File $detailedFailureFile -Encoding UTF8
-        Push-AppveyorArtifact $detailedFailureFile -FileName "DetailedTestFailures_Pester5.json"
+        Push-AppveyorArtifact $detailedFailureFile -FileName "DetailedTestFailures.json"
 
         throw "$failedcount tests failed."
     }

tests/appveyor.pester.ps1

@@ -3,10 +3,12 @@ $sw = [system.diagnostics.stopwatch]::startNew()
 Write-Host -Object "appveyor.post: Sending coverage data" -ForeGroundColor DarkGreen
 $ProjectRoot = $env:APPVEYOR_BUILD_FOLDER
 $ModuleBase = $ProjectRoot
-$pester5CoverageFiles = Get-ChildItem -Path "$ModuleBase\Pester5Coverage*.xml"
-foreach ($coverageFile in $pester5CoverageFiles) {
+$pesterCoverageFiles = Get-ChildItem -Path "$ModuleBase\PesterCoverage*.xml"
+foreach ($coverageFile in $pesterCoverageFiles) {
     Write-Host -Object "appveyor.post: Sending $($coverageFile.FullName)" -ForeGroundColor DarkGreen
     Push-AppveyorArtifact $coverageFile.FullName -FileName $coverageFile.Name
+    # The flag still says pester5 on purpose. codecov keys its history off the flag name, so
+    # renaming it starts a new series and loses the trend on the existing dashboards.
     codecov -f $coverageFile.FullName --flag "pester5_$($env:SCENARIO.ToLowerInvariant())" | Out-Null
 }