1
- <#
1
+ <#
2
2
. SYNOPSIS
3
- Tests the PowerShell help for the commands in a module.
3
+ Tests the PowerShell help for the commands in a module.
4
4
5
5
. DESCRIPTION
6
- This Pester test verifies that the commands in a module have basic help content.
6
+ This Pester test verifies that the commands in a module have basic help content.
7
7
It works on all command types and both comment-based and XML help.
8
8
9
9
This test verifies that Get-Help is not autogenerating help because it cannot
@@ -21,15 +21,15 @@ When testing attributes of parameters that appear in multiple parameter sets,
21
21
this test uses the parameter that appears in the default parameter set, if one
22
22
is defined.
23
23
24
- You can run this Tests file from any location. For a help test that is located in a module
24
+ You can run this Tests file from any location. For a help test that is located in a module
25
25
directory, use https://github.com/juneb/PesterTDD/InModule.Help.Tests.ps1
26
26
27
27
. PARAMETER ModuleName
28
28
Enter the name of the module to test. You can enter only one name at a time. This
29
29
parameter is mandatory.
30
30
31
31
. PARAMETER RequiredVersion
32
- Enter the version of the module to test. This parameter is optional. If you
32
+ Enter the version of the module to test. This parameter is optional. If you
33
33
omit it, the test runs on the latest version of the module in $env:PSModulePath.
34
34
35
35
. EXAMPLE
@@ -57,13 +57,13 @@ Param
57
57
[ValidateScript ({ Get-Module - ListAvailable - Name $_ })]
58
58
[string ]
59
59
$ModuleName = ' PSScriptAnalyzer' ,
60
-
60
+
61
61
[Parameter (Mandatory = $false )]
62
62
[System.Version ]
63
63
$RequiredVersion
64
64
)
65
65
66
- # Requires -Module @ {ModuleName = ' Pester' ; ModuleVersion = ' 3.4.0' }
66
+ # # Requires -Module @ {ModuleName = ' Pester' ; ModuleVersion = ' 3.4.0' }
67
67
68
68
<#
69
69
. SYNOPSIS
@@ -87,16 +87,16 @@ Enter a CommandInfo object, such as the object that Get-Command returns. You
87
87
can also pipe a CommandInfo object to the function.
88
88
89
89
This parameter takes a CommandInfo object, instead of a command name, so
90
- you can use the parameters of Get-Command to specify the module and version
90
+ you can use the parameters of Get-Command to specify the module and version
91
91
of the command.
92
92
93
93
. EXAMPLE
94
94
PS C:\> Get-ParametersDefaultFirst -Command (Get-Command New-Guid)
95
- This command uses the Command parameter to specify the command to
95
+ This command uses the Command parameter to specify the command to
96
96
Get-ParametersDefaultFirst
97
97
98
98
. EXAMPLE
99
- PS C:\> Get-Command New-Guid | Get-ParametersDefaultFirst
99
+ PS C:\> Get-Command New-Guid | Get-ParametersDefaultFirst
100
100
You can also pipe a CommandInfo object to Get-ParametersDefaultFirst
101
101
102
102
. EXAMPLE
@@ -107,7 +107,7 @@ command runs Get-Command module-qualified name value.
107
107
. EXAMPLE
108
108
PS C:\> $ModuleSpec = @{ModuleName='BetterCredentials';RequiredVersion=4.3}
109
109
PS C:\> Get-Command -FullyQualifiedName $ModuleSpec | Get-ParametersDefaultFirst
110
- This command uses a Microsoft.PowerShell.Commands.ModuleSpecification object to
110
+ This command uses a Microsoft.PowerShell.Commands.ModuleSpecification object to
111
111
specify the module and version. You can also use it to specify the module GUID.
112
112
Then, it pipes the CommandInfo object to Get-ParametersDefaultFirst.
113
113
#>
@@ -119,7 +119,7 @@ function Get-ParametersDefaultFirst {
119
119
[System.Management.Automation.CommandInfo ]
120
120
$Command
121
121
)
122
-
122
+
123
123
BEGIN {
124
124
$Common = ' Debug' , ' ErrorAction' , ' ErrorVariable' , ' InformationAction' , ' InformationVariable' , ' OutBuffer' , ' OutVariable' , ' PipelineVariable' , ' Verbose' , ' WarningAction' , ' WarningVariable'
125
125
$parameters = @ ()
@@ -128,7 +128,7 @@ function Get-ParametersDefaultFirst {
128
128
if ($defaultPSetName = $Command.DefaultParameterSet ) {
129
129
$defaultParameters = ($Command.ParameterSets | Where-Object Name -eq $defaultPSetName ).parameters | Where-Object Name -NotIn $common
130
130
$otherParameters = ($Command.ParameterSets | Where-Object Name -ne $defaultPSetName ).parameters | Where-Object Name -NotIn $common
131
-
131
+
132
132
$parameters = $defaultParameters
133
133
if ($parameters -and $otherParameters ) {
134
134
$otherParameters | ForEach-Object {
@@ -142,8 +142,8 @@ function Get-ParametersDefaultFirst {
142
142
else {
143
143
$parameters = $Command.ParameterSets.Parameters | Where-Object Name -NotIn $common | Sort-Object Name - Unique
144
144
}
145
-
146
-
145
+
146
+
147
147
return $parameters
148
148
}
149
149
END { }
@@ -161,7 +161,7 @@ following properties:
161
161
-- [string] $CommandName
162
162
-- [string] $ModuleName (or PSSnapin name)
163
163
-- [string] $ModuleVersion (or PowerShell Version)
164
-
164
+
165
165
. PARAMETER CommandInfo
166
166
Specifies a Commandinfo object, e.g. (Get-Command Get-Item).
167
167
@@ -191,7 +191,7 @@ function Get-CommandVersion {
191
191
[System.Management.Automation.CommandInfo ]
192
192
$CommandInfo
193
193
)
194
-
194
+
195
195
if ((-not ((($commandModuleName = $CommandInfo.Module.Name ) -and ($commandVersion = $CommandInfo.Module.Version )) -or
196
196
(($commandModuleName = $CommandInfo.PSSnapin ) -and ($commandVersion = $CommandInfo.PSSnapin.Version ))))) {
197
197
Write-Error " For $ ( $CommandInfo.Name ) : Can't find PSSnapin/module name and version"
@@ -215,7 +215,7 @@ Import-Module $ModuleName -RequiredVersion $RequiredVersion -ErrorAction Stop
215
215
$ms = $null
216
216
$commands = $null
217
217
$paramBlackList = @ ()
218
- if ($PSVersionTable.PSVersion -lt [Version ]' 5.0' ) {
218
+ if ($PSVersionTable.PSVersion -lt [Version ]' 5.0.0 ' ) {
219
219
$ms = New-Object - TypeName ' Microsoft.PowerShell.Commands.ModuleSpecification' - ArgumentList $ModuleName
220
220
$commands = Get-Command - Module $ms.Name
221
221
$paramBlackList += ' SaveDscDependency'
@@ -230,79 +230,80 @@ else {
230
230
231
231
foreach ($command in $commands ) {
232
232
$commandName = $command.Name
233
-
233
+
234
234
# Get the module name and version of the command. Used in the Describe name.
235
235
$commandModuleVersion = Get-CommandVersion - CommandInfo $command
236
-
236
+
237
237
# The module-qualified command fails on Microsoft.PowerShell.Archive cmdlets
238
238
$Help = Get-Help $ModuleName \$commandName - ErrorAction SilentlyContinue
239
239
if ($Help.Synopsis -like ' *`[`<CommonParameters`>`]*' ) {
240
240
$Help = Get-Help $commandName - ErrorAction SilentlyContinue
241
241
}
242
-
242
+
243
243
Describe " Test help for $commandName in $ ( $commandModuleVersion.ModuleName ) ($ ( $commandModuleVersion.Version ) )" {
244
-
244
+
245
245
# If help is not found, synopsis in auto-generated help is the syntax diagram
246
246
It " should not be auto-generated" {
247
- $Help.Synopsis | Should Not BeLike ' *`[`<CommonParameters`>`]*'
247
+ # Replace pester BeLike with powershell -like as pester 3.3.9 does not support BeLike
248
+ $Help.Synopsis -like ' *`[`<CommonParameters`>`]*' | Should Be $false
248
249
}
249
-
250
+
250
251
# Should be a description for every function
251
252
It " gets description for $commandName " {
252
253
$Help.Description | Should Not BeNullOrEmpty
253
254
}
254
-
255
+
255
256
# Should be at least one example
256
257
It " gets example code from $commandName " {
257
258
($Help.Examples.Example | Select-Object - First 1 ).Code | Should Not BeNullOrEmpty
258
259
}
259
-
260
+
260
261
# Should be at least one example description
261
262
It " gets example help from $commandName " {
262
263
($Help.Examples.Example.Remarks | Select-Object - First 1 ).Text | Should Not BeNullOrEmpty
263
264
}
264
-
265
+
265
266
Context " Test parameter help for $commandName " {
266
-
267
+
267
268
$Common = ' Debug' , ' ErrorAction' , ' ErrorVariable' , ' InformationAction' , ' InformationVariable' , ' OutBuffer' , ' OutVariable' ,
268
269
' PipelineVariable' , ' Verbose' , ' WarningAction' , ' WarningVariable'
269
-
270
- # Get parameters. When >1 parameter with same name,
270
+
271
+ # Get parameters. When >1 parameter with same name,
271
272
# get parameter from the default parameter set, if any.
272
273
$parameters = Get-ParametersDefaultFirst - Command $command
273
-
274
+
274
275
$parameterNames = $parameters.Name
275
276
$HelpParameterNames = $Help.Parameters.Parameter.Name | Sort-Object - Unique
276
-
277
+
277
278
foreach ($parameter in $parameters ) {
278
279
if ($parameter -in $paramBlackList ) {
279
280
continue
280
281
}
281
282
$parameterName = $parameter.Name
282
283
$parameterHelp = $Help.parameters.parameter | Where-Object Name -EQ $parameterName
283
-
284
+
284
285
# Should be a description for every parameter
285
286
It " gets help for parameter: $parameterName : in $commandName " {
286
- # `$parameterHelp.Description.Text | Should Not BeNullOrEmpty` fails for -Settings paramter
287
+ # `$parameterHelp.Description.Text | Should Not BeNullOrEmpty` fails for -Settings paramter
287
288
# without explicit [string] casting on the Text property
288
289
[string ]::IsNullOrEmpty($parameterHelp.Description.Text ) | Should Be $false
289
290
}
290
-
291
+
291
292
# Required value in Help should match IsMandatory property of parameter
292
293
It " help for $parameterName parameter in $commandName has correct Mandatory value" {
293
294
$codeMandatory = $parameter.IsMandatory.toString ()
294
295
$parameterHelp.Required | Should Be $codeMandatory
295
296
}
296
-
297
+
297
298
# Parameter type in Help should match code
298
299
It " help for $commandName has correct parameter type for $parameterName " {
299
300
$codeType = $parameter.ParameterType.Name
300
301
# To avoid calling Trim method on a null object.
301
302
$helpType = if ($parameterHelp.parameterValue ) { $parameterHelp.parameterValue.Trim () }
302
- $helpType | Should be $codeType
303
+ $helpType | Should be $codeType
303
304
}
304
305
}
305
-
306
+
306
307
foreach ($helpParm in $HelpParameterNames ) {
307
308
if ($helpParm -in $paramBlackList ) {
308
309
continue
0 commit comments