Update documentation to reflect separate BeforeAll/AfterAll job architecture

Co-authored-by: MariusStorhaug <[email protected]>

Author: Copilot

README.md

@@ -41,9 +41,9 @@ Depending on the labels in the pull requests, the workflow will result in differ
   - This produces a json based report that is used to later evaluate the results of the tests.
 - [Test module](./.github/workflows/Test-ModuleLocal.yml)
   - Import and tests the module in parallel (matrix) using Pester tests from the module repository.
-  - Supports setup and teardown scripts:
-    - **BeforeAll.ps1**: Runs before each test execution to set up test environment (e.g., deploy infrastructure, download test data)
-    - **AfterAll.ps1**: Runs after each test execution to clean up test environment (e.g., remove test resources, cleanup databases)
+  - Supports setup and teardown scripts executed via separate dedicated jobs:
+    - **BeforeAll.ps1**: Runs once before all test matrix jobs to set up test environment (e.g., deploy infrastructure, download test data)
+    - **AfterAll.ps1**: Runs once after all test matrix jobs complete to clean up test environment (e.g., remove test resources, cleanup databases)
   - Setup/teardown scripts are automatically detected in test directories and executed with the same environment variables as tests
   - This produces a json based report that is used to later evaluate the results of the tests.
 - [Get test results](./.github/workflows/Get-TestResults.yml)
@@ -267,13 +267,13 @@ The workflow supports automatic execution of setup and teardown scripts for modu
 
 #### BeforeAll.ps1
 - **Location**: Place in your test directories (e.g., `tests/BeforeAll.ps1`)
-- **Purpose**: Runs before each test execution to prepare the test environment
+- **Purpose**: Runs once before all test matrix jobs to prepare the test environment
 - **Use cases**: Deploy test infrastructure, download test data, initialize databases, configure services
 - **Environment**: Has access to the same environment variables as your tests (secrets, GitHub token, etc.)
 
 #### AfterAll.ps1
 - **Location**: Place in your test directories (e.g., `tests/AfterAll.ps1`)
-- **Purpose**: Runs after each test execution to clean up the test environment
+- **Purpose**: Runs once after all test matrix jobs complete to clean up the test environment
 - **Use cases**: Remove test resources, cleanup databases, stop services, upload artifacts
 - **Environment**: Has access to the same environment variables as your tests
 
@@ -301,6 +301,17 @@ Write-Host "Cleanup completed!"
 - Scripts run with PowerShell and have access to PSModuleHelpers
 - If no scripts are found, the workflow continues normally
 
+**Execution Order:**
+The workflow executes setup and teardown scripts using separate dedicated jobs with the following order:
+```
+BeforeAll-ModuleLocal → Test-ModuleLocal (matrix) → AfterAll-ModuleLocal → Get-TestResults/Get-CodeCoverage
+```
+
+- **BeforeAll-ModuleLocal**: Runs once before all test matrix jobs
+- **Test-ModuleLocal**: Runs tests in parallel matrix configuration
+- **AfterAll-ModuleLocal**: Runs once after all test matrix jobs complete (always executes for cleanup, even if tests fail)
+- **Get-TestResults/Get-CodeCoverage**: Process results after cleanup is complete
+
 ### Secrets
 
 The following secrets are used by the workflow. They can be automatically provided (if available) by setting the `secrets: inherit`