|
1 | 1 | # Test-PSModule |
2 | 2 |
|
3 | | -Tests PowerShell module repos using PSModule framework rules. |
4 | | - |
5 | | -This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the |
6 | | -[Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module. |
7 | | - |
8 | | -## Specifications and practices |
9 | | - |
10 | | -Test-PSModule enables: |
11 | | - |
12 | | -- [Test-Driven Development](https://testdriven.io/test-driven-development/) using [Pester](https://pester.dev) via [Invoke-Pester](https://github.com/PSModule/Invoke-Pester). |
13 | | - |
14 | | -## How it works |
15 | | - |
16 | | -- The action runs test on the module repository based on `Settings`: |
17 | | - - `SourceCode` - Tests source code style and standards based on PSModule framework rules. |
18 | | - - `Module` - Tests the module build module style and standards based on PSModule framework rules. |
19 | | - - The module is imported in its own context to avoid conflicts with other modules. |
20 | | -- The action returns the test results as action [outputs](#outputs). |
21 | | -- The following reports are calculated and uploaded as artifacts. This is done to support the action being run in matrix jobs. |
22 | | - - 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) |
23 | | - - 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) |
24 | | - |
25 | | -The action fails if any of the tests fail or it fails to run the tests. |
26 | | -This is mitigated by the `continue-on-error` option in the workflow. |
27 | | - |
28 | | -## How to use it |
29 | | - |
30 | | -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. |
31 | | - |
32 | | -To use the action, create a new file in the `.github/workflows` directory of the module repository and add the following content. |
33 | | -<details> |
34 | | -<summary>Workflow suggestion - before module is built</summary> |
35 | | - |
36 | | -```yaml |
37 | | -name: Test-PSModule |
38 | | - |
39 | | -on: [push] |
40 | | - |
41 | | -jobs: |
42 | | - Test-PSModule: |
43 | | - name: Test-PSModule |
44 | | - runs-on: ubuntu-latest |
45 | | - steps: |
46 | | - - name: Checkout repo |
47 | | - uses: actions/checkout@v4 |
48 | | - |
49 | | - - name: Initialize environment |
50 | | - uses: PSModule/Initialize-PSModule@main |
51 | | - |
52 | | - - name: Test-PSModule |
53 | | - uses: PSModule/Test-PSModule@main |
54 | | - with: |
55 | | - Settings: SourceCode |
56 | | - |
57 | | -``` |
58 | | -</details> |
59 | | - |
60 | | -<details> |
61 | | -<summary>Workflow suggestion - after module is built</summary> |
62 | | - |
63 | | -```yaml |
64 | | -name: Test-PSModule |
65 | | - |
66 | | -on: [push] |
67 | | - |
68 | | -jobs: |
69 | | - Test-PSModule: |
70 | | - name: Test-PSModule |
71 | | - runs-on: ubuntu-latest |
72 | | - steps: |
73 | | - - name: Checkout repo |
74 | | - uses: actions/checkout@v4 |
75 | | - |
76 | | - - name: Initialize environment |
77 | | - uses: PSModule/Initialize-PSModule@main |
78 | | - |
79 | | - - name: Test-PSModule |
80 | | - uses: PSModule/Test-PSModule@main |
81 | | - with: |
82 | | - Settings: Module |
83 | | - |
84 | | -``` |
85 | | -</details> |
86 | | - |
87 | | -## Usage |
88 | | - |
89 | | -### Inputs |
90 | | - |
91 | | -| Name | Description | Required | Default | |
92 | | -| ---- | ----------- | -------- | ------- | |
93 | | -| `Name` | The name of the module to test. The name of the repository is used if not specified. | `false` | | |
94 | | -| `Settings` | The type of tests to run. Can be either `Module` or `SourceCode`. | `true` | | |
95 | | -| `Debug` | Enable debug output. | `false` | `'false'` | |
96 | | -| `Verbose` | Enable verbose output. | `false` | `'false'` | |
97 | | -| `Version` | Specifies the version of the GitHub module to be installed. The value must be an exact version. | `false` | | |
98 | | -| `Prerelease` | Allow prerelease versions if available. | `false` | `'false'` | |
99 | | -| `WorkingDirectory` | The working directory to use for the action. This is the root folder where tests and outputs are expected. | `false` | `'.'` | |
100 | | -| `StepSummary_Mode` | Controls which tests to show in the GitHub step summary. Allows "Full" (all tests), "Failed" (only failed tests), or "None" (disable step summary). | `false` | `Failed` | |
101 | | -| `StepSummary_ShowTestOverview` | Controls whether to show the test overview table in the GitHub step summary. | `false` | `false` | |
102 | | -| `StepSummary_ShowConfiguration` | Controls whether to show the configuration details in the GitHub step summary. | `false` | `false` | |
103 | | -| `Run_ExcludePath` | Directories/files to exclude from the run. | `false` | | |
104 | | -| `Run_ScriptBlock` | ScriptBlocks containing tests to be executed. | `false` | | |
105 | | -| `Run_Container` | ContainerInfo objects containing tests to be executed. | `false` | | |
106 | | -| `Run_TestExtension` | Filter used to identify test files (e.g. `.Tests.ps1`). | `false` | | |
107 | | -| `Run_Exit` | Whether to exit with a non-zero exit code on failure. | `false` | | |
108 | | -| `Run_Throw` | Whether to throw an exception on test failure. | `false` | | |
109 | | -| `Run_SkipRun` | Discovery only, skip actual test run. | `false` | | |
110 | | -| `Run_SkipRemainingOnFailure` | Skips remaining tests after the first failure. Options: `None`, `Run`, `Container`, `Block`. | `false` | | |
111 | | -| `Filter_Tag` | Tags of Describe/Context/It blocks to run. | `false` | | |
112 | | -| `Filter_ExcludeTag` | Tags of Describe/Context/It blocks to exclude. | `false` | | |
113 | | -| `Filter_Line` | Filter by file + scriptblock start line (e.g. `C:\tests\file1.Tests.ps1:37`). | `false` | | |
114 | | -| `Filter_ExcludeLine` | Exclude by file + scriptblock start line. Precedence over `Filter_Line`. | `false` | | |
115 | | -| `Filter_FullName` | Full name of a test with wildcards, joined by dot. E.g. `*.describe Get-Item.test1` | `false` | | |
116 | | -| `CodeCoverage_Enabled` | Enable code coverage. | `false` | | |
117 | | -| `CodeCoverage_OutputFormat` | Format for the coverage report. Possible values: `JaCoCo`, `CoverageGutters`, `Cobertura`. | `false` | | |
118 | | -| `CodeCoverage_OutputPath` | Where to save the code coverage report (relative to the current dir). | `false` | | |
119 | | -| `CodeCoverage_OutputEncoding` | Encoding of the coverage file. | `false` | | |
120 | | -| `CodeCoverage_Path` | Files/directories to measure coverage on (by default, reuses `Path` from the general settings). | `false` | | |
121 | | -| `CodeCoverage_ExcludeTests` | Exclude tests themselves from coverage. | `false` | | |
122 | | -| `CodeCoverage_RecursePaths` | Recurse through coverage directories. | `false` | | |
123 | | -| `CodeCoverage_CoveragePercentTarget` | Desired minimum coverage percentage. | `false` | | |
124 | | -| `CodeCoverage_UseBreakpoints` | **Experimental**: When `false`, use a Profiler-based tracer instead of breakpoints. | `false` | | |
125 | | -| `CodeCoverage_SingleHitBreakpoints` | Remove breakpoints after first hit. | `false` | | |
126 | | -| `TestResult_Enabled` | Enable test-result output (e.g. NUnitXml, JUnitXml). | `false` | | |
127 | | -| `TestResult_OutputFormat` | Possible values: `NUnitXml`, `NUnit2.5`, `NUnit3`, `JUnitXml`. | `false` | | |
128 | | -| `TestResult_OutputPath` | Where to save the test-result report (relative path). | `false` | | |
129 | | -| `TestResult_OutputEncoding` | Encoding of the test-result file. | `false` | | |
130 | | -| `Should_ErrorAction` | Controls if `Should` throws on error. Use `Stop` to throw, or `Continue` to fail at the end. | `false` | | |
131 | | -| `Debug_ShowFullErrors` | Show Pester internal stack on errors. (Deprecated – overrides `Output.StackTraceVerbosity` to `Full`). | `false` | | |
132 | | -| `Debug_WriteDebugMessages` | Write debug messages to screen. | `false` | | |
133 | | -| `Debug_WriteDebugMessagesFrom` | Filter debug messages by source. Wildcards allowed. | `false` | | |
134 | | -| `Debug_ShowNavigationMarkers` | Write paths after every block/test for easy navigation in Visual Studio Code. | `false` | | |
135 | | -| `Debug_ReturnRawResultObject` | Returns an unfiltered result object, for development only. | `false` | | |
136 | | -| `Output_Verbosity` | Verbosity: `None`, `Normal`, `Detailed`, `Diagnostic`. | `false` | | |
137 | | -| `Output_StackTraceVerbosity` | Stacktrace detail: `None`, `FirstLine`, `Filtered`, `Full`. | `false` | | |
138 | | -| `Output_CIFormat` | CI format of error output: `None`, `Auto`, `AzureDevops`, `GithubActions`. | `false` | | |
139 | | -| `Output_CILogLevel` | CI log level: `Error` or `Warning`. | `false` | | |
140 | | -| `Output_RenderMode` | How to render console output: `Auto`, `Ansi`, `ConsoleColor`, `Plaintext`. | `false` | | |
141 | | -| `TestDrive_Enabled` | Enable `TestDrive`. | `false` | | |
142 | | -| `TestRegistry_Enabled` | Enable `TestRegistry`. | `false` | | |
143 | | - |
144 | | -### Outputs |
145 | | - |
146 | | -| Output | Description | |
147 | | -|-------------------------|--------------------------------------| |
148 | | -| `Outcome` | Outcome of the test run. | |
149 | | -| `Conclusion` | Conclusion status of test execution. | |
150 | | -| `Executed` | Indicates if tests were executed. | |
151 | | -| `Result` | Overall result (`Passed`, `Failed`). | |
152 | | -| `FailedCount` | Number of failed tests. | |
153 | | -| `FailedBlocksCount` | Number of failed blocks. | |
154 | | -| `FailedContainersCount` | Number of failed containers. | |
155 | | -| `PassedCount` | Number of passed tests. | |
156 | | -| `SkippedCount` | Number of skipped tests. | |
157 | | -| `InconclusiveCount` | Number of inconclusive tests. | |
158 | | -| `NotRunCount` | Number of tests not run. | |
159 | | -| `TotalCount` | Total tests executed. | |
160 | | - |
161 | | -## PSModule tests |
162 | | - |
163 | | -### SourceCode tests |
164 | | - |
165 | | -The [PSModule - SourceCode tests](./scripts/tests/SourceCode/PSModule/PSModule.Tests.ps1) verifies the following coding practices that the framework enforces: |
166 | | - |
167 | | -| ID | Category | Description | |
168 | | -|---------------------|---------------------|--------------------------------------------------------------------------------------------| |
169 | | -| NumberOfProcessors | General | Should use `[System.Environment]::ProcessorCount` instead of `$env:NUMBER_OF_PROCESSORS`. | |
170 | | -| Verbose | General | Should not contain `-Verbose` unless it is explicitly disabled with `:$false`. | |
171 | | -| OutNull | General | Should use `$null = ...` instead of piping output to `Out-Null`. | |
172 | | -| NoTernary | General | Should not use ternary operations to maintain compatibility with PowerShell 5.1 and below. | |
173 | | -| LowercaseKeywords | General | All PowerShell keywords should be written in lowercase. | |
174 | | -| FunctionCount | Functions (Generic) | Each script file should contain exactly one function or filter. | |
175 | | -| FunctionName | Functions (Generic) | Script filenames should match the name of the function or filter they contain. | |
176 | | -| CmdletBinding | Functions (Generic) | Functions should include the `[CmdletBinding()]` attribute. | |
177 | | -| ParamBlock | Functions (Generic) | Functions should have a parameter block (`param()`). | |
178 | | -| FunctionTest | Functions (Public) | All public functions/filters should have corresponding tests. | |
179 | | - |
180 | | -### Module tests |
181 | | - |
182 | | -The [PSModule - Module tests](./scripts/tests/Module/PSModule/PSModule.Tests.ps1) verifies the following coding practices that the framework enforces: |
183 | | - |
184 | | -| Name | Description | |
185 | | -| ------ | ----------- | |
186 | | -| Module Manifest exists | Verifies that a module manifest file is present. | |
187 | | -| Module Manifest is valid | Verifies that the module manifest file is valid. | |
| 3 | +This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). |
0 commit comments