Treat BeforeAll module-local setup failures as catastrophic (#399)

## Summary
- treat `BeforeAll-ModuleLocal` failure as a hard failure root cause in
test result aggregation
- run `AfterAll-ModuleLocal` cleanup whenever module-local setup ran,
even if setup failed and tests were skipped
- pass `BeforeAll-ModuleLocal` job result into `Get-TestResults` and
fail early with a clear root-cause message
- document the new `BeforeAllModuleLocalResult` input in
`Get-PesterTestResults`

## Links
- Closes #388

---------

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

Author: MariusStorhaug

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

@@ -18,6 +18,7 @@ or missing results. It supports three categories of test suites: Source Code, PS
 | `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      |           |
+| `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    |
@@ -50,5 +51,6 @@ This action does not define explicit outputs. Instead:
 - **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.

.github/actions/Get-PesterTestResults/action.yml

@@ -15,6 +15,10 @@ inputs:
   ModuleTestSuites:
     description: The test suites to run for the module.
     required: true
+  BeforeAllModuleLocalResult:
+    description: The workflow result for the BeforeAll-ModuleLocal job.
+    required: false
+    default: skipped
   Debug:
     description: Enable debug output.
     required: false
@@ -44,6 +48,7 @@ runs:
         PSMODULE_GET_PESTERTESTRESULTS_INPUT_SourceCodeTestSuites: ${{ inputs.SourceCodeTestSuites }}
         PSMODULE_GET_PESTERTESTRESULTS_INPUT_PSModuleTestSuites: ${{ inputs.PSModuleTestSuites }}
         PSMODULE_GET_PESTERTESTRESULTS_INPUT_ModuleTestSuites: ${{ inputs.ModuleTestSuites }}
+        PSMODULE_GET_PESTERTESTRESULTS_INPUT_BeforeAllModuleLocalResult: ${{ inputs.BeforeAllModuleLocalResult }}
       with:
         Name: Get-PesterTestResults
         Debug: ${{ inputs.Debug }}

.github/actions/Get-PesterTestResults/src/main.ps1

@@ -10,6 +10,16 @@ param()
 $owner = $env:GITHUB_REPOSITORY_OWNER
 $repo = $env:GITHUB_REPOSITORY_NAME
 $runId = $env:GITHUB_RUN_ID
+$beforeAllModuleLocalResult = $env:PSMODULE_GET_PESTERTESTRESULTS_INPUT_BeforeAllModuleLocalResult
+
+if ($beforeAllModuleLocalResult -eq 'failure') {
+    Write-GitHubError (
+        'BeforeAll-ModuleLocal failed. Module-local tests were skipped as a safety stop, ' +
+        'and AfterAll-ModuleLocal cleanup was still requested. ' +
+        'See the BeforeAll-ModuleLocal job log for the root cause.'
+    )
+    exit 1
+}
 
 $files = Get-GitHubArtifact -Owner $owner -Repository $repo -WorkflowRunID $runId -Name '*-TestResults' |
     Save-GitHubArtifact -Path 'TestResults' -Force -Expand -PassThru | Get-ChildItem -Recurse -Filter *.json | Sort-Object Name -Unique

.github/workflows/Get-TestResults.yml

@@ -7,6 +7,11 @@ on:
         type: string
         description: The complete settings object including test suites.
         required: true
+      BeforeAllModuleLocalResult:
+        type: string
+        description: The workflow result for the BeforeAll-ModuleLocal job.
+        required: false
+        default: skipped
 
 permissions:
   contents: read # to checkout the repo
@@ -31,6 +36,7 @@ jobs:
           SourceCodeTestSuites: ${{ toJSON(fromJson(inputs.Settings).TestSuites.SourceCode) }}
           PSModuleTestSuites: ${{ toJSON(fromJson(inputs.Settings).TestSuites.PSModule) }}
           ModuleTestSuites: ${{ toJSON(fromJson(inputs.Settings).TestSuites.Module) }}
+          BeforeAllModuleLocalResult: ${{ inputs.BeforeAllModuleLocalResult }}
           Debug: ${{ fromJson(inputs.Settings).Debug }}
           Prerelease: ${{ fromJson(inputs.Settings).Prerelease }}
           Verbose: ${{ fromJson(inputs.Settings).Verbose }}

.github/workflows/workflow.yml

@@ -186,17 +186,18 @@ jobs:
       Settings: ${{ needs.Plan.outputs.Settings }}
 
   # Runs on:
-  # - ✅ Open/Updated PR - Runs teardown scripts after local module tests
-  # - ✅ Merged PR       - Runs teardown scripts after local module tests
-  # - ✅ Abandoned PR    - Runs teardown if tests were started (cleanup)
-  # - ✅ Manual run      - Runs teardown scripts after local module tests
+  # - ✅ Open/Updated PR - Runs teardown scripts after local module setup/tests
+  # - ✅ Merged PR       - Runs teardown scripts after local module setup/tests
+  # - ✅ Abandoned PR    - Runs teardown if local module setup/tests were started (cleanup)
+  # - ✅ Manual run      - Runs teardown scripts after local module setup/tests
   AfterAll-ModuleLocal:
-    if: fromJson(needs.Plan.outputs.Settings).Run.AfterAllModuleLocal && needs.Test-ModuleLocal.result != 'skipped' && always()
+    if: fromJson(needs.Plan.outputs.Settings).Run.AfterAllModuleLocal && needs.BeforeAll-ModuleLocal.result != 'skipped' && always()
     uses: ./.github/workflows/AfterAll-ModuleLocal.yml
     secrets:
       TestData: ${{ secrets.TestData }}
     needs:
       - Plan
+      - BeforeAll-ModuleLocal
       - Test-ModuleLocal
     with:
       Settings: ${{ needs.Plan.outputs.Settings }}
@@ -213,10 +214,12 @@ jobs:
       - Test-SourceCode
       - Lint-SourceCode
       - Test-Module
+      - BeforeAll-ModuleLocal
       - Test-ModuleLocal
     uses: ./.github/workflows/Get-TestResults.yml
     with:
       Settings: ${{ needs.Plan.outputs.Settings }}
+      BeforeAllModuleLocalResult: ${{ needs.BeforeAll-ModuleLocal.result }}
 
   # Runs on:
   # - ✅ Open/Updated PR - Calculates and reports code coverage