diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index 905af73..6861aa3 100644 --- a/instructions/repository-specific.instructions.md +++ b/instructions/repository-specific.instructions.md @@ -234,7 +234,11 @@ versions — and installed via **PSDepend** when `./build.ps1 -Bootstrap` runs: ## Testing -Tests live in `tests/` and use **Pester 5+** syntax. +Tests live in `tests/` and run on **Pester 6.0.0** (pinned exactly in `requirements.psd1`; +see psake/PowerShellBuild#17 for the targeting decision). Write assertions with the classic +`Should -Be` syntax — valid in both Pester 5 and 6 — rather than the Pester 6-only `Should-*` +assertion family, so tests remain backportable. The shipped module's own Pester compatibility +floor (5.0.0 in `Test-PSBuildPester`) is a separate contract and is unchanged. - Always build the module before running Pester directly — running against source can produce incorrect results. Prefer `./build.ps1 -Task Test` over a raw `Invoke-Pester` call. @@ -280,6 +284,9 @@ don't replace them. - **Script analysis**: PSScriptAnalyzer config is `PowerShellBuild/ScriptAnalyzerSettings.psd1`. Default severity threshold for build failure is `Error`. Warnings are reported but don't fail the build. +- **Changelog scope**: `CHANGELOG.md` documents user-facing changes to the shipped module + only. Repository-internal changes — development dependencies, CI workflows, this repo's own + build scripts, or the test suite — do not get changelog entries. - **Spell-checker ignores**: inline comments — `# spell-checker:ignore MAML PSGALLERY`. ## How Consumers Use This Module diff --git a/requirements.psd1 b/requirements.psd1 index 7b6fd47..dbe7029 100755 --- a/requirements.psd1 +++ b/requirements.psd1 @@ -4,7 +4,7 @@ } BuildHelpers = '2.0.16' Pester = @{ - Version = '5.8.0' + Version = '6.0.0' Parameters = @{ SkipPublisherCheck = $true } diff --git a/tests/Help.tests.ps1 b/tests/Help.tests.ps1 index 974e60a..acceecf 100755 --- a/tests/Help.tests.ps1 +++ b/tests/Help.tests.ps1 @@ -44,6 +44,8 @@ Describe "Test help for <_.Name>" -ForEach $commands { $commandParameters = global:FilterOutCommonParams -Params $command.ParameterSets.Parameters $commandParameterNames = $commandParameters.Name $helpLinks = $commandHelp.relatedLinks.navigationLink.uri + $helpParameters = global:FilterOutCommonParams -Params $commandHelp.Parameters.Parameter + $helpParameterNames = $helpParameters.Name } BeforeAll { @@ -77,41 +79,50 @@ Describe "Test help for <_.Name>" -ForEach $commands { ($commandHelp.Examples.Example.Remarks | Select-Object -First 1).Text | Should -Not -BeNullOrEmpty } - It "Help link <_> is valid" -ForEach $helpLinks { - (Invoke-WebRequest -Uri $_ -UseBasicParsing).StatusCode | Should -Be '200' - } - - Context "Parameter <_.Name>" -Foreach $commandParameters { - - BeforeAll { - $parameter = $_ - $parameterName = $parameter.Name - $parameterHelp = $commandHelp.parameters.parameter | Where-Object Name -eq $parameterName - $parameterHelpType = if ($parameterHelp.ParameterValue) { $parameterHelp.ParameterValue.Trim() } - } - - # Should be a description for every parameter - It "Has description" { - $parameterHelp.Description.Text | Should -Not -BeNullOrEmpty - } - - # Required value in Help should match IsMandatory property of parameter - It "Has correct [mandatory] value" { - $codeMandatory = $_.IsMandatory.toString() - $parameterHelp.Required | Should -Be $codeMandatory + # The if guards around the data-driven blocks below skip generation when the + # collection is empty. Pester 5 skipped empty -ForEach silently; Pester 6 fails + # discovery instead, and these guards keep the v5 behavior on both versions. + if ($helpLinks) { + It "Help link <_> is valid" -ForEach $helpLinks { + (Invoke-WebRequest -Uri $_ -UseBasicParsing).StatusCode | Should -Be '200' } + } - # Parameter type in help should match code - It "Has correct parameter type" { - $parameterHelpType | Should -Be $parameter.ParameterType.Name + if ($commandParameters) { + Context "Parameter <_.Name>" -Foreach $commandParameters { + + BeforeAll { + $parameter = $_ + $parameterName = $parameter.Name + $parameterHelp = $commandHelp.parameters.parameter | Where-Object Name -eq $parameterName + $parameterHelpType = if ($parameterHelp.ParameterValue) { $parameterHelp.ParameterValue.Trim() } + } + + # Should be a description for every parameter + It "Has description" { + $parameterHelp.Description.Text | Should -Not -BeNullOrEmpty + } + + # Required value in Help should match IsMandatory property of parameter + It "Has correct [mandatory] value" { + $codeMandatory = $_.IsMandatory.toString() + $parameterHelp.Required | Should -Be $codeMandatory + } + + # Parameter type in help should match code + It "Has correct parameter type" { + $parameterHelpType | Should -Be $parameter.ParameterType.Name + } } } - Context "Test <_> help parameter help for " -Foreach $helpParameterNames { + if ($helpParameterNames) { + Context "Test <_> help parameter help for " -Foreach $helpParameterNames { - # Shouldn't find extra parameters in help. - It "finds help parameter in code: <_>" { - $_ -in $parameterNames | Should -Be $true + # Shouldn't find extra parameters in help. + It "finds help parameter in code: <_>" { + $_ -in $commandParameterNames | Should -Be $true + } } } }