From 11e54fa38bb4a2aae57140ed6c55efecfa4f8726 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:26:37 +0100 Subject: [PATCH 1/3] State Pester test-result behavior with direct actors --- .../actions/Get-PesterTestResults/README.md | 40 ++++++++++--------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/.github/actions/Get-PesterTestResults/README.md b/.github/actions/Get-PesterTestResults/README.md index ce71ca87..e53ba57f 100644 --- a/.github/actions/Get-PesterTestResults/README.md +++ b/.github/actions/Get-PesterTestResults/README.md @@ -1,40 +1,42 @@ # Get-PesterTestResults -A GitHub Action that gathers Pester test results for the PSModule process by analyzing test artifacts from the workflow run. -It validates test execution and results, providing a summary and failing if any tests are unsuccessful. +This GitHub Action collects Pester test results from workflow artifacts for the PSModule process. +The action examines test execution and results. It writes a summary and fails if tests do not pass. -This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the -[Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module. +The [PSModule framework](https://github.com/PSModule) includes this action. +For the recommended setup, use the [Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate PowerShell module management. ## Usage -This action retrieves test artifacts named `*-TestResults`, processes the contained JSON files, and checks for test failures, unexecuted tests, -or missing results. It supports three categories of test suites: Source Code, PSModule, and Module tests. +The action gets artifacts named `*-TestResults` and reads their JSON files. +It finds test failures, tests that did not run, and missing results. +The action supports Source Code, PSModule, and Module test suites. ### Inputs | Input | Description | Required | Default | |-------------------------|-------------------------------------------------------------------------------------------------------------------------------|----------|-----------| -| `SourceCodeTestSuites` | JSON array specifying OS names for Source Code test suites. Example: `[{"OSName": "Windows"}]` | Yes | | -| `PSModuleTestSuites` | JSON array specifying OS names for PSModule test suites. Example: `[{"OSName": "Linux"}]` | Yes | | -| `ModuleTestSuites` | JSON array specifying TestName and OSName for Module test suites. Example: `[{"TestName": "Integration", "OSName": "MacOS"}]` | Yes | | +| `SourceCodeTestSuites` | JSON array that specifies OS names for Source Code test suites. Example: `[{"OSName": "Windows"}]` | Yes | | +| `PSModuleTestSuites` | JSON array that specifies OS names for PSModule test suites. Example: `[{"OSName": "Linux"}]` | Yes | | +| `ModuleTestSuites` | JSON array that specifies TestName and OSName for Module test suites. Example: `[{"TestName": "Integration", "OSName": "MacOS"}]` | Yes | | | `BeforeAllModuleLocalResult` | Workflow result for the `BeforeAll-ModuleLocal` job (`success`, `failure`, `skipped`). | No | `skipped` | | `Debug` | Enable debug output (`true`/`false`). | No | `false` | | `Verbose` | Enable verbose output (`true`/`false`). | No | `false` | -| `Version` | Exact version of the GitHub module to install (e.g., `1.0.0`). | No | Latest | -| `Prerelease` | Allow installing prerelease module versions (`true`/`false`). | No | `false` | +| `Version` | Exact version of the GitHub module to install (for example, `1.0.0`). | No | Latest | +| `Prerelease` | Allow prerelease module versions (`true`/`false`). | No | `false` | | `WorkingDirectory` | Working directory for the script. | No | `.` | ### Secrets -No secrets are required if the action runs in the same repository. The action uses the default `GITHUB_TOKEN` provided by GitHub Actions to access workflow artifacts. +For runs in the same repository, the action needs no additional secrets. +The action uses the default `GITHUB_TOKEN` from GitHub Actions to access workflow artifacts. ### Outputs -This action does not define explicit outputs. Instead: +The action defines no explicit outputs. -- If any tests fail or errors occur, the action exits with a non-zero code, marking the workflow step as failed. -- Detailed results are logged in the workflow run's output. +- If tests fail or errors occur, the action exits with a nonzero code. GitHub Actions marks the workflow step as failed. +- The action writes detailed results to the workflow run log. ### Example @@ -48,9 +50,9 @@ This action does not define explicit outputs. Instead: ``` ### Notes -- **Test Suite Inputs**: Must be valid JSON arrays. +- **Test suite inputs**: The test suite inputs must be valid JSON arrays. - `SourceCodeTestSuites` and `PSModuleTestSuites` require `OSName`. - `ModuleTestSuites` requires both `TestName` and `OSName`. -- **BeforeAll module-local failures**: When `BeforeAllModuleLocalResult` is `failure`, the action exits immediately and reports the setup failure as the root cause. -- **Artifact Names**: The action expects artifacts named `*-TestResults` containing Pester JSON reports. -- **Failure Conditions**: The action fails if tests are unexecuted, explicitly failed, or if result files are missing. +- **BeforeAll module-local failures**: If `BeforeAllModuleLocalResult` is `failure`, the action exits immediately and reports the setup failure as the root cause. +- **Artifact names**: The action expects artifacts named `*-TestResults` with Pester JSON reports. +- **Failure conditions**: The action fails if tests do not run, tests fail, or result files are missing. From cb48ff8308ddb46d98eb3527f0e4dbc4289b705c Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:29:06 +0100 Subject: [PATCH 2/3] Describe coverage results and thresholds directly --- .../actions/Get-PesterCodeCoverage/README.md | 77 ++++++++++--------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/.github/actions/Get-PesterCodeCoverage/README.md b/.github/actions/Get-PesterCodeCoverage/README.md index c2936f41..bca26704 100644 --- a/.github/actions/Get-PesterCodeCoverage/README.md +++ b/.github/actions/Get-PesterCodeCoverage/README.md @@ -1,19 +1,19 @@ # Get-PesterCodeCoverage -A GitHub Action that aggregates Pester code coverage reports and generates a detailed summary with coverage statistics. -Fails the workflow if coverage falls below specified targets. +This GitHub Action collects Pester code coverage reports and writes a summary of coverage statistics. +If coverage is below the specified target, the action fails the workflow. -This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the -[Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module. +The [PSModule framework](https://github.com/PSModule) includes this action. +For the recommended setup, use the [Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate PowerShell module management. ## Features -- Combines multiple code coverage reports from parallel test runs -- Generates Markdown/HTML tables showing missed & executed commands -- Displays analyzed files and coverage statistics -- Generates a generic missed-path report (Markdown + JSON) -- Configurable step summary sections -- Threshold enforcement for minimum code coverage +- Collects code coverage reports from parallel test runs. +- Writes Markdown and HTML tables of missed and executed commands. +- Shows analyzed files and coverage statistics. +- Writes a missed-path report in Markdown and JSON. +- Selects step summary sections from the action input. +- Fails the workflow if coverage is below the target. ## Usage @@ -26,10 +26,10 @@ This GitHub Action is a part of the [PSModule framework](https://github.com/PSMo | `Version` | Version of the GitHub module to install; accepts an exact version or a NuGet version range (for example `[1.2.0, 2.0.0)`) | No | Latest | | `Prerelease` | Allow prerelease versions | No | `false` | | `WorkingDirectory` | Working directory for the action | No | `.` | -| `StepSummary_Mode` | Controls which sections to show in the GitHub step summary. Use 'Full' for all sections, 'None' to disable, or a comma-separated list of 'Missed, Executed, Files'. | No | `Missed, Files` | +| `StepSummary_Mode` | Select the sections in the GitHub step summary. Use 'Full' for all sections, 'None' to disable, or a comma-separated list of 'Missed, Executed, Files'. | No | `Missed, Files` | | `CodeCoveragePercentTarget` | Target code coverage percentage | No | Max target from individual reports | -### Example Workflow +### Example workflow ```yaml - name: Process Code Coverage @@ -43,22 +43,22 @@ This GitHub Action is a part of the [PSModule framework](https://github.com/PSMo | Name | Description | | ---- | ----------- | -| `MissedPathReportPath` | Folder path containing `CodeCoverage-MissedPaths.md` and `CodeCoverage-MissedPaths.json` | +| `MissedPathReportPath` | Path to the folder with `CodeCoverage-MissedPaths.md` and `CodeCoverage-MissedPaths.json` | -### GitHub Step Summary +### GitHub step summary -The action generates a detailed summary visible in the GitHub Actions UI: +The action writes a detailed summary to the GitHub Actions UI: -1. **Coverage Overview Table** - - Coverage percentage vs target - - Analyzed/executed/missed command counts - - Number of files analyzed +1. **Coverage overview table** + - Coverage percentage and target + - Analyzed, executed, and missed command counts + - Number of analyzed files -2. **Expandable Sections** - - **Missed Commands**: HTML table with code snippets - - **Executed Commands**: HTML table with code snippets - - **Analyzed Files**: List of covered files - - **Missed Paths**: Aggregated missed-command counts grouped by file path +2. **Expandable sections** + - **Missed commands**: HTML table with code snippets + - **Executed commands**: HTML table with code snippets + - **Analyzed files**: List of covered files + - **Missed paths**: Missed-command counts for each file path Example summary: @@ -77,10 +77,10 @@ Summary: ## Requirements -1. **Pester 6.1 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 + Earlier steps must create JSON coverage reports named `*-CodeCoverage*.json` + from the Pester 6.1 `CodeCoverage` result object. The action reads `CoveragePercent`, `CoveragePercentTarget`, `CommandsMissed`, `CommandsExecuted`, and `FilesAnalyzed` plus their count properties. @@ -89,18 +89,19 @@ Summary: ## Behavior -1. **Coverage Calculation** - - Combines multiple coverage reports - - Removes duplicate entries - - Calculates aggregate coverage percentage +1. **Coverage calculation** + - Collects multiple coverage reports. + - Removes duplicate entries. + - Calculates the total coverage percentage across all reports. -2. **Threshold Enforcement** - Fails the workflow if coverage is below either: - - Explicitly specified `CodeCoveragePercentTarget` - - Highest target from individual reports (if no target specified) +2. **Threshold enforcement** + If coverage is below the applicable target, the action fails the workflow. + The action uses: + - The explicit `CodeCoveragePercentTarget` value, if the input has a value. + - The highest target from individual reports, if the input has no value. -3. **Output Control** - Configure visibility of sections using `StepSummary_Mode`: +3. **Output control** + Use `StepSummary_Mode` to select the summary sections: ```yaml # Show all sections StepSummary_Mode: Full @@ -114,7 +115,7 @@ Summary: ## Troubleshooting -Enable debugging by setting inputs: +To get debug and verbose output, set these inputs: ```yaml with: Debug: true From 2742b3da509fbdd67caf5c5c5d2c19a8959dd899 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 4 Nov 2026 13:31:59 +0100 Subject: [PATCH 3/3] Use direct neutral prose in the installer README --- .github/actions/Install-PSModule/README.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/.github/actions/Install-PSModule/README.md b/.github/actions/Install-PSModule/README.md index 42092a98..f6c76c11 100644 --- a/.github/actions/Install-PSModule/README.md +++ b/.github/actions/Install-PSModule/README.md @@ -1,10 +1,9 @@ # Install-PSModule -A GitHub Action to install and configure the PSModule helper modules for use in continuous integration and delivery (CI/CD) workflows. This action is -a critical component for setting up a standardized PowerShell environment across repositories using the PSModule framework. +This GitHub Action prepares the PowerShell environment for continuous integration and delivery (CI/CD) workflows. -This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the -[Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module. +The [PSModule framework](https://github.com/PSModule) includes this action. +For the recommended setup, use the [Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate PowerShell module management. ## What this action does @@ -12,8 +11,6 @@ This GitHub Action is a part of the [PSModule framework](https://github.com/PSMo - Copies the latest version of the `Helpers` module into the PowerShell module directory. - Imports the `Helpers` module, ensuring it is available for subsequent steps. -This action helps maintain consistency and reliability across workflows that depend on the PSModule framework. - ## Usage ```yaml @@ -31,11 +28,11 @@ _No secrets required._ ## Outputs -This action does not provide any outputs. +The action defines no outputs. ## Example -Here's a complete workflow example demonstrating how to use the Install-PSModule action: +This example shows the action in a workflow: ```yaml name: CI