Skip to content

Reusable action readers get direct behavior descriptions #569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Marius Storhaug (MariusStorhaug) wants to merge 3 commits into
base: main
Choose a base branch
from
+65 −65
Open

Reusable action readers get direct behavior descriptions #569

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
11e54fa
State Pester test-result behavior with direct actors
MariusStorhaug Nov 4, 2026
cb48ff8
Describe coverage results and thresholds directly
MariusStorhaug Nov 4, 2026
2742b3d
Use direct neutral prose in the installer README
MariusStorhaug Nov 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 39 additions & 38 deletions .github/actions/Get-PesterCodeCoverage/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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.

Expand All @@ -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
Expand All @@ -114,7 +115,7 @@ Summary:

## Troubleshooting

Enable debugging by setting inputs:
To get debug and verbose output, set these inputs:
```yaml
with:
Debug: true
Expand Down
40 changes: 21 additions & 19 deletions .github/actions/Get-PesterTestResults/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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.
13 changes: 5 additions & 8 deletions .github/actions/Install-PSModule/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,16 @@
# 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

- Removes any existing instances of the `Helpers` module from the PowerShell session.
- 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
Expand All @@ -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
Expand Down
Loading