Upgrade Process-PSModule to Pester 6.1 (#519)

## Implemented in Process-PSModule

- Enforce the Pester `[6.1.0,7.0.0)` range in reusable framework test
runs.
- Align module-local workflow inputs with the current Invoke-Pester
contract: `Version`/`Prerelease` select Pester, while
`GitHubVersion`/`GitHubPrerelease` select the GitHub module. Pester
prerelease remains at the action default.
- Keep the six Test-PSModule container/test files inside the action
implementation at `.github/actions/Test-PSModule/src/tests`, because
they are context-dependent framework suites executed against the
compiled module or source tree. Discovery remains
`$PSScriptRoot/tests/$settings`.
- Add a framework CI contract test that validates Pester 6.1
configuration properties:
  - `Run.Shuffle`
  - `Run.ShuffleSeed`
  - `Run.Parallel`
  - `Run.ParallelThrottleLimit`
  - `Debug.ShowStartMarkers`
- Align coverage input documentation with Pester 6.1: supported formats
are JaCoCo and Cobertura, and profiler-based tracing is documented
correctly.
- Update Pester 6.1 authoring and coverage-report guidance.

## Pester 6.1 runtime audit

A local Pester 6.1 probe generated a passing test result and coverage
report, and the Get-PesterCodeCoverage action processed that JSON
successfully. The coverage result shape remains compatible:
`CoveragePercent`, `CoveragePercentTarget`, `CommandsMissed`,
`CommandsExecuted`, `FilesAnalyzed`, and all count properties are
present and consumed correctly.

The Pester result still exposes `Containers`; each container retains
`Data`, `Blocks`, and aggregate result/count properties. The existing
container files therefore remain compatible with the
compiled-module/source-tree execution model.

## Contract findings and required upstream follow-up

The current `PSModule/Invoke-Pester` v5.1.0 action does not expose these
Pester configuration properties as action inputs, so this repository
deliberately does not add incompatible passthrough mappings:

- `Run_Shuffle`
- `Run_ShuffleSeed`
- `Run_Parallel`
- `Run_ParallelThrottleLimit`
- `Debug_ShowStartMarkers`

The coordinated `PSModule/Invoke-Pester` follow-up must add each input
to `action.yml`, forward each `PSMODULE_INVOKE_PESTER_INPUT_*`
environment variable, map them into the generated `PesterConfiguration`,
and publish a version/tag that Process-PSModule can pin.
Process-PSModule can then expose the corresponding reusable-action
inputs and pass them through.

## Test and fixture boundaries confirmed

- Module-local tests assume the built module is already loaded:
`Test-ModuleLocal.yml` imports the artifact in its prescript before
invoking Pester.
- Framework module tests import the module explicitly in their own test
scopes; no implicit preload was introduced.
- PSD1 files in the repository test fixture (`src/data/Config.psd1` and
`src/data/Settings.psd1`) are not implicitly loaded and are currently
unused. Any future PSD1 dataset test must call
`Import-PowerShellDataFile` explicitly or load it from supported setup.
- `Expose-TestData` passes only explicit caller-provided fixtures as
environment variables to setup, teardown, and tests.
- Module linting remains a separate `Invoke-ScriptAnalyzer` job and
artifact path; it is not folded into Pester execution.

## Validation

- Pester 6.1 configuration contract validated locally.
- Pester 6.1 result/container and coverage shapes inspected locally.
- Get-PesterCodeCoverage executed against a generated Pester 6.1
coverage JSON fixture and passed.
- Restored Test-PSModule scripts parsed successfully.
- Test-PSModule path resolution validated from a consumer repository
root.
- Changed PowerShell parsed successfully.
- `git diff --check` passed.

Commits: `337533c`, `ad2961e`, `8c3366f`, `0423d6a`

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.github/actions/Get-PesterCodeCoverage/README.md

@@ -77,8 +77,12 @@ Summary:
 
 ## Requirements
 
-1. **Pester Code Coverage Reports**
+1. **Pester 6.1 Code Coverage Reports**
+
    Preceding steps must generate JSON coverage reports named `*-CodeCoverage*.json`
+   from the Pester 6.1 `CodeCoverage` result object. The action consumes
+   `CoveragePercent`, `CoveragePercentTarget`, `CommandsMissed`,
+   `CommandsExecuted`, and `FilesAnalyzed` plus their count properties.
 
 2. **GitHub CLI**
    The action uses `gh run download` to fetch artifacts from the current workflow run

.github/actions/Test-PSModule/action.yml

@@ -85,7 +85,7 @@ inputs:
     required: false
   CodeCoverage_OutputFormat:
     description: |
-      Format to use for code coverage report. Possible values: JaCoCo, CoverageGutters, Cobertura
+      Format to use for code coverage report. Possible values in Pester 6.1: JaCoCo or Cobertura.
     required: false
   CodeCoverage_OutputPath:
     description: |
@@ -113,7 +113,7 @@ inputs:
     required: false
   CodeCoverage_UseBreakpoints:
     description: |
-      EXPERIMENTAL: When false, use Profiler based tracer to do CodeCoverage instead of using breakpoints.
+      When false, use the profiler-based tracer instead of breakpoints for code coverage.
     required: false
   CodeCoverage_SingleHitBreakpoints:
     description: |
@@ -288,6 +288,7 @@ runs:
       with:
         Debug: ${{ inputs.Debug }}
         Verbose: ${{ inputs.Verbose }}
+        Version: '[6.1.0,7.0.0)'
         GitHubVersion: ${{ inputs.Version }}
         GitHubPrerelease: ${{ inputs.Prerelease }}
         WorkingDirectory: ${{ inputs.WorkingDirectory }}

.github/actions/Test-PSModule/src/tests/Module/PSModule/PSModule.Tests.ps1

@@ -43,7 +43,7 @@ if ($hasClassExporter) {
 
 
 # Run-phase setup — recompute from $Path so that It/Context blocks can use these variables.
-# Pester v5 Discovery and Run are separate executions. The script-scope variables above drive
+# Pester 6 Discovery and Run are separate executions. The script-scope variables above drive
 # -Skip and -ForEach during Discovery. This BeforeAll recomputes the same values for the Run
 # phase, where It blocks actually execute. The duplication is intentional and required.
 BeforeAll {

.github/workflows/Test-Actions.yml

@@ -34,13 +34,33 @@ jobs:
       - name: Install test dependencies
         shell: pwsh
         run: |
-          Install-PSResource -Name Pester -Version '[5.7.1,6.0.0)' -Repository PSGallery -TrustRepository
+          Install-PSResource -Name Pester -Version '[6.1.0,7.0.0)' -Repository PSGallery -TrustRepository
           Install-PSResource -Name PSSemVer -Repository PSGallery -TrustRepository
           Install-PSResource -Name GitHub -Version '[0.43.1,0.44.0)' -Repository PSGallery -TrustRepository
 
       - name: Run action unit tests
         shell: pwsh
         run: |
+          $configuration = New-PesterConfiguration
+          $configuration.Run.Shuffle = $true
+          $configuration.Run.ShuffleSeed = 42
+          $configuration.Run.Parallel = $true
+          $configuration.Run.ParallelThrottleLimit = 2
+          $configuration.Debug.ShowStartMarkers = $true
+
+          $expectedOptions = @{
+              'Run.Shuffle' = $configuration.Run.Shuffle.Value
+              'Run.ShuffleSeed' = $configuration.Run.ShuffleSeed.Value -eq 42
+              'Run.Parallel' = $configuration.Run.Parallel.Value
+              'Run.ParallelThrottleLimit' = $configuration.Run.ParallelThrottleLimit.Value -eq 2
+              'Debug.ShowStartMarkers' = $configuration.Debug.ShowStartMarkers.Value
+          }
+          foreach ($option in $expectedOptions.GetEnumerator()) {
+              if (-not $option.Value) {
+                  throw "Pester 6.1 configuration option [$($option.Key)] was not applied."
+              }
+          }
+
           $testPaths = Get-ChildItem -Path '.github/actions' -Directory |
               ForEach-Object { Join-Path -Path $_.FullName -ChildPath 'tests' } |
               Where-Object { Test-Path -Path $_ }

.github/workflows/Test-ModuleLocal.yml

@@ -72,9 +72,10 @@ jobs:
         uses: PSModule/Invoke-Pester@4ff33199141fdf22568990b6107fe3148ae93a1c # v5.1.0
         with:
           Debug: ${{ fromJson(inputs.Settings).Debug }}
-          Prerelease: ${{ fromJson(inputs.Settings).Prerelease }}
           Verbose: ${{ fromJson(inputs.Settings).Verbose }}
-          Version: ${{ fromJson(inputs.Settings).Version }}
+          Version: '[6.1.0,7.0.0)'
+          GitHubVersion: ${{ fromJson(inputs.Settings).Version }}
+          GitHubPrerelease: ${{ fromJson(inputs.Settings).Prerelease }}
           TestResult_TestSuiteName: ${{ matrix.TestName }}-${{ matrix.OSName }}
           TestResult_Enabled: true
           CodeCoverage_Enabled: true

docs/content/guides/writing-module-tests.md

@@ -11,15 +11,24 @@ been built and imported.
 
 ## Pester version
 
-Module test files declare a Pester **6.x** requirement at the top of each `*.Tests.ps1`:
+Module test files declare a Pester **6.1.x** requirement at the top of each `*.Tests.ps1`:
 
 ```powershell
-#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.0.0'; MaximumVersion = '6.*' }
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.1.0'; MaximumVersion = '6.*' }
 ```
 
-This is a convention module authors add, not something the pipeline injects. The
-[Invoke-Pester](https://github.com/PSModule/Invoke-Pester) action installs a matching `6.x`, so minor and patch updates
-flow in automatically while a new major stays a deliberate, reviewed change.
+This is a convention module authors add. Process-PSModule pins its reusable
+[Invoke-Pester](https://github.com/PSModule/Invoke-Pester) action runs to the
+`[6.1.0,7.0.0)` range, so patch updates flow in automatically while a new
+major stays a deliberate, reviewed change.
+
+Pester 6.1 adds opt-in controls for shuffled and parallel file execution
+(`Run.Shuffle`, `Run.ShuffleSeed`, `Run.Parallel`, and
+`Run.ParallelThrottleLimit`) and diagnostic start markers
+(`Debug.ShowStartMarkers`). These controls are available when invoking Pester
+directly with `New-PesterConfiguration`. Process-PSModule's reusable action will
+expose them after the coordinated `PSModule/Invoke-Pester` action adds matching
+inputs; the current v5.1.0 action contract does not accept them.
 
 ## Test discovery
 

docs/content/reference/powershell-module-standard.md

@@ -319,7 +319,7 @@ Process-PSModule derives `TestName` from the file's basename before the first do
 Each `*.Tests.ps1` file must declare the Pester 6 requirement:
 
 ```powershell
-#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.0.0'; MaximumVersion = '6.*' }
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.1.0'; MaximumVersion = '6.*' }
 ```
 
 Tests run against the built module artifact installed locally, across a multi-OS matrix (Linux, macOS, Windows). The full suite must also remain runnable locally without mandatory cloud resources, special access, or secrets that cannot be mocked.