From aa12d05469d3075789e5dab934333dfa1c6dd01a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 20:24:14 +0000 Subject: [PATCH 1/4] chore: Pin Pester 6.0.0 for the repository test suite Move the repository's own test suite from Pester 5.8.0 to 6.0.0, pinned exactly in requirements.psd1 (psake/PowerShellBuild#17 records the targeting decision). This is a development-dependency change only: the shipped module's Pester compatibility contract (Test-PSBuildPester imports Pester with a 5.0.0 minimum) is unchanged. Pester 6 fails discovery on an empty -ForEach collection instead of silently generating nothing, which broke tests/Help.tests.ps1 for commands whose help has no related links. Guard the three data-driven blocks (help links, command parameters, help parameter names) with discovery-time if checks, preserving the Pester 5 behavior on both versions. Full suite passes under 6.0.0: 301 passed, 0 failed, 15 skipped (Windows-only signing tests). Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_011semwa5HU1BUKKL4RoWjKa --- CHANGELOG.md | 9 +++ .../repository-specific.instructions.md | 6 +- requirements.psd1 | 2 +- tests/Help.tests.ps1 | 67 +++++++++++-------- 4 files changed, 53 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b74bd8f..b27d8e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## Unreleased +### Changed + +- [**#17**](https://github.com/psake/PowerShellBuild/issues/17) The repository's + own test suite now runs on Pester 6.0.0 (pinned in `requirements.psd1`). This + is a development-dependency change only — the shipped module's Pester + compatibility contract is unchanged: `Test-PSBuildPester` still imports Pester + with a 5.0.0 minimum and the manifest still declares Pester 5.x support, so + consumers on Pester 5 are unaffected. + ## [0.8.1] 2026-06-03 ### Fixed diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index 905af73..55370b5 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. 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..77e5cea 100755 --- a/tests/Help.tests.ps1 +++ b/tests/Help.tests.ps1 @@ -77,41 +77,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 $parameterNames | Should -Be $true + } } } } From b27a0994df40dc79fac1eabf76f300c59a2ef015 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 20:52:41 +0000 Subject: [PATCH 2/4] test: Generate help-parameter tests during discovery Address review feedback on #132: the "help parameter in code" Context consumed $helpParameterNames at discovery time, but the variable was only assigned in BeforeAll (run phase), so the block never generated any tests under Pester 5 or 6. Compute $helpParameters and $helpParameterNames in BeforeDiscovery, matching the other data-driven blocks. Also fix the assertion inside it, which referenced the undefined $parameterNames instead of $commandParameterNames - a latent bug that never surfaced because the block never ran. Reactivating the block adds 66 assertions: 367 passed, 0 failed. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_011semwa5HU1BUKKL4RoWjKa --- tests/Help.tests.ps1 | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tests/Help.tests.ps1 b/tests/Help.tests.ps1 index 77e5cea..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 { @@ -119,7 +121,7 @@ Describe "Test help for <_.Name>" -ForEach $commands { # Shouldn't find extra parameters in help. It "finds help parameter in code: <_>" { - $_ -in $parameterNames | Should -Be $true + $_ -in $commandParameterNames | Should -Be $true } } } From 66214c3e5948bf1e533d86e1d3abb59928595a96 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 22:02:58 +0000 Subject: [PATCH 3/4] docs: Drop changelog entry for the dev-only Pester pin The changelog documents user-facing changes to the shipped module; which Pester version this repository's own test suite runs on is a contributor-facing concern and is already covered by the repository instructions and #17. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_011semwa5HU1BUKKL4RoWjKa --- CHANGELOG.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b27d8e8..b74bd8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,15 +7,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/). ## Unreleased -### Changed - -- [**#17**](https://github.com/psake/PowerShellBuild/issues/17) The repository's - own test suite now runs on Pester 6.0.0 (pinned in `requirements.psd1`). This - is a development-dependency change only — the shipped module's Pester - compatibility contract is unchanged: `Test-PSBuildPester` still imports Pester - with a 5.0.0 minimum and the manifest still declares Pester 5.x support, so - consumers on Pester 5 are unaffected. - ## [0.8.1] 2026-06-03 ### Fixed From 85bbd116d9a7566be284a15e318afd4dad1e6e0c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 7 Jul 2026 22:05:58 +0000 Subject: [PATCH 4/4] docs: Codify changelog scope convention in repository instructions CHANGELOG.md documents user-facing changes to the shipped module only; repository-internal changes (dev dependencies, CI, repo build scripts, test suite) get no entry. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_011semwa5HU1BUKKL4RoWjKa --- instructions/repository-specific.instructions.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/instructions/repository-specific.instructions.md b/instructions/repository-specific.instructions.md index 55370b5..6861aa3 100644 --- a/instructions/repository-specific.instructions.md +++ b/instructions/repository-specific.instructions.md @@ -284,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