Refactor README.md for clarity and detail on testing framework and outputs

Author: MariusStorhaug

README.md

@@ -1,39 +1,34 @@
 # Test-PSModule
 
-Test PowerShell modules with Pester and PSScriptAnalyzer.
+Tests PowerShell module repos using PSModule framework rules.
 
-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.
+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.
 
 ## Specifications and practices
 
 Test-PSModule enables:
 
-- [Test-Driven Development](https://testdriven.io/test-driven-development/) using [Pester](https://pester.dev) and [PSScriptAnalyzer](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules)
+- [Test-Driven Development](https://testdriven.io/test-driven-development/) using [Pester](https://pester.dev) via [Invoke-Pester](https://github.com/PSModule/Invoke-Pester).
 
 ## How it works
 
-The action runs the following the Pester test framework:
-- [PSScriptAnalyzer tests](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/rules/readme?view=ps-modules)
-- [PSModule framework tests](#psmodule-tests)
-- If `Settings` is set to `Module`:
-  - The module manifest is tested using [Test-ModuleManifest](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/test-modulemanifest).
-  - The module is imported.
-  - Custom module tests from the `tests` directory in the module repository are run.
-  - CodeCoverage is calculated.
-- If `Settings` is set to `SourceCode`:
-  - The source code is tested with:
-    - `PSScriptAnalyzer` for best practices, using custom settings.
-    - `PSModule.SourceCode` for other PSModule standards.
-- The action returns a `passed` output that is `true` if all tests pass, else `false`.
-- The following reports are calculated and uploaded as artifacts:
-  - Test suite results.
-  - Code coverage results.
+- The action runs test on the module repository based on `Settings`:
+  - `SourceCode` - Tests source code style and standards based on PSModule framework rules.
+  - `Module` - Tests the module build module style and standards based on PSModule framework rules.
+    - The module is imported in its own context to avoid conflicts with other modules.
+- The action returns the test results as action [outputs](#outputs).
+- The following reports are calculated and uploaded as artifacts. This is done to support the action being run in matrix jobs.
+  - Test suite results. In [Process-PSModule](https://github.com/PSModule/Process-PSModule) this is evaluated in a later job by [Get-PesterTestResults](https://github.com/PSModule/Get-PesterTestResults)
+  - Code coverage results. In [Process-PSModule](https://github.com/PSModule/Process-PSModule) this is evaluated in a later job by [Get-PesterCodeCoverage](https://github.com/PSModule/Get-PesterCodeCoverage)
 
 The action fails if any of the tests fail or it fails to run the tests.
 This is mitigated by the `continue-on-error` option in the workflow.
 
 ## How to use it
 
+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.
+
 To use the action, create a new file in the `.github/workflows` directory of the module repository and add the following content.
 <details>
 <summary>Workflow suggestion - before module is built</summary>
@@ -146,23 +141,42 @@ jobs:
 | `TestDrive_Enabled`                  | Enable `TestDrive`.                                                                                                                                 |          |
 | `TestRegistry_Enabled`               | Enable `TestRegistry`.                                                                                                                              |          |
 
-
 ### Outputs
 
-| Name | Description | Possible values |
-| ---- | ----------- | --------------- |
-| `passed` | If the tests passed. | `true`, `false` |
+| Output        | Description                          |
+|---------------|--------------------------------------|
+| `Outcome`     | Outcome of the test run.             |
+| `Conclusion`  | Conclusion status of test execution. |
+| `Executed`    | Indicates if tests were executed.    |
+| `Result`      | Overall result (`Passed`, `Failed`). |
+| `FailedCount` | Number of failed tests.              |
+| `PassedCount` | Number of passed tests.              |
+| `TotalCount`  | Total tests executed.                |
 
 ## PSModule tests
 
-The [PSModule framework tests](https://github.com/PSModule/Test-PSModule/blob/main/scripts/tests/PSModule/PSModule.Tests.ps1) verifies the following coding practices that the framework enforces:
+### SourceCode tests
+
+The [PSModule - SourceCode tests](./scripts/tests/SourceCode/PSModule/PSModule.Tests.ps1) verifies the following coding practices that the framework enforces:
+
+| ID                  | Category            | Description                                                                                |
+|---------------------|---------------------|--------------------------------------------------------------------------------------------|
+| NumberOfProcessors  | General             | Should use `[System.Environment]::ProcessorCount` instead of `$env:NUMBER_OF_PROCESSORS`.  |
+| Verbose             | General             | Should not contain `-Verbose` unless it is explicitly disabled with `:$false`.             |
+| OutNull             | General             | Should use `$null = ...` instead of piping output to `Out-Null`.                           |
+| NoTernary           | General             | Should not use ternary operations to maintain compatibility with PowerShell 5.1 and below. |
+| LowercaseKeywords   | General             | All PowerShell keywords should be written in lowercase.                                    |
+| FunctionCount       | Functions (Generic) | Each script file should contain exactly one function or filter.                            |
+| FunctionName        | Functions (Generic) | Script filenames should match the name of the function or filter they contain.             |
+| CmdletBinding       | Functions (Generic) | Functions should include the `[CmdletBinding()]` attribute.                                |
+| ParamBlock          | Functions (Generic) | Functions should have a parameter block (`param()`).                                       |
+| FunctionTest        | Functions (Public)  | All public functions/filters should have corresponding tests.                              |
 
-- Script filename and function/filter name should match.
+### Module tests
 
-## Tools
+The [PSModule - Module tests](./scripts/tests/Module/PSModule/PSModule.Tests.ps1) verifies the following coding practices that the framework enforces:
 
-- Pester | [Docs](https://www.pester.dev) | [GitHub](https://github.com/Pester/Pester) | [PS Gallery](https://www.powershellgallery.com/packages/Pester/)
-- PSScriptAnalyzer [Docs](https://learn.microsoft.com/en-us/powershell/utility-modules/psscriptanalyzer/overview?view=ps-modules) | [GitHub](https://github.com/PowerShell/PSScriptAnalyzer) | [PS Gallery](https://www.powershellgallery.com/packages/PSScriptAnalyzer/)
-- PSResourceGet | [Docs](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.psresourceget/?view=powershellget-3.x) | [GitHub](https://github.com/PowerShell/PSResourceGet) | [PS Gallery](https://www.powershellgallery.com/packages/Microsoft.PowerShell.PSResourceGet/)
-- [Test-ModuleManifest | Microsoft Learn](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/test-modulemanifest)
-- [PowerShellGet | Microsoft Learn](https://learn.microsoft.com/en-us/powershell/module/PowerShellGet/test-scriptfileinfo)
+| Name | Description |
+| ------ | ----------- |
+| Module Manifest exists | Verifies that a module manifest file is present. |
+| Module Manifest is valid | Verifies that the module manifest file is valid. |