PowerShell TDD: Testing CmdletBinding and OutputType
A while ago, I decided to add PowerShell to my automation toolbox. Since I believe the best way to learn a new language is to do test-driven development and PowerShell has a fantastic module for this, called Pester. The framework is super intuitive, easy to do mocking in, and allows you develop your code design from tests.
However, one thing bugged me. I didn’t seem to be able to write code that tested whether a function had declared CmdletBinding (i.e. was an Advanced Function), or if it had declared OutputType.
# How can I test this?
function MyFunction {
[CmdletBinding(SupportsShouldProcess, ConfirmImpact='High')]
[OutputType('String')]
...
}
Google didn’t have anything useful on this subject so I tried my luck on StackOverflow and mclayton pointed me in the right direction (although, as mclayton puts it: it’s a bit of a mouthful). It turns out that I can use the built-in Abstract Syntax Tree (AST) and specifically the Param block attributes to find out if CmdletBinding is declared.
Testing CmdletBinding
The below function takes a command as input and looks for a CmdletBinding param block attribute.
function Test-CmdletBinding {
[OutputType([Bool])]
[CmdletBinding()]
param (
# Parameter help description
[Parameter(Mandatory)]
[System.Management.Automation.CommandInfo]
$Command
)
$attribute = $command.ScriptBlock.Ast.Body.ParamBlock.Attributes | where-object { $_.TypeName.FullName -eq 'CmdletBinding' };
$null -ne $attribute
}
You can then use the helper function in a Pester test, like this.
It "Should be an advanced function" {
$c = Get-Command -Name MyCommand
Test-CmdletBinding $c | Should -BeTrue
}
Testing CmdletBinding Arguments
That’s great, but what about arguments, like SupportsShouldProcess or ConfirmImpact?
[CmdletBinding(SupportsShouldProcess, ConfirmImpact='High')]
How can I test for those? Well, that’s where we get mouthful bits I guess, but the good news is that it’s doable. Here’s a helper function that can test those scenarios. It takes a command, an argument name, and an optional argument value and returns true if the command meets those conditions.
function Test-CmdletBindingArgument {
[CmdletBinding()]
[OutputType([Bool])]
param (
# Parameter help description
[Parameter(Mandatory)]
[System.Management.Automation.CommandInfo]
$Command,
[Parameter(Mandatory)]
[string]
$ArgumentName,
[Parameter()]
[string]
$ArgumentValue
)
$attribute = $command.ScriptBlock.Ast.Body.ParamBlock.Attributes | where-object { $_.TypeName.FullName -eq 'CmdletBinding' };
if ($attribute) {
$argument = $attribute.NamedArguments | where-object { $_.ArgumentName -eq $ArgumentName };
if ($null -eq $argument) {
# The attribute does not have the argument, return false
$false
} elseif ($argument.ExpressionOmitted) {
$ArgumentValue -eq '' -or $ArgumentValue -eq $true
} elseif ($argument.Argument.Extent.Text -eq '$true') {
$ArgumentValue -eq '' -or $ArgumentValue -eq $true
} elseif ($argument.Argument.Extent.Text -eq '$false') {
$ArgumentValue -eq $false
} else {
$ArgumentValue -eq $argument.Argument.Value
}
} else {
# No such attribute exists on the command, return false
$false
}
}
The code handles both implicit and explicit values, e.g.
[CmdletBinding(SomeAttribute)]
[CmdletBinding(SomeAttribute=$true)] # same as having the attribute declared
[CmdletBinding(SomeAttribute=$false)] # same as not having the attribute declared
[CmdletBinding(SomeAttribute='Some Value')]
Here are a couple of examples of Pester tests using the helper function.
It "Should have CmdletBinding with ConfirmImpact set to High" {
$c = Get-Command -Name MyCommand
Test-CmdletBindingArgument $c -ArgumentName 'ConfirmImpact' -ArgumentValue 'High' | Should -BeTrue
}
It "Should have SupportShouldProcess declared" {
$c = Get-Command -Name MyCommand
Test-CmdletBindingArgument $c -ArgumentName 'SupportShouldProcess' | Should -BeTrue
}
Testing OutputType
Testing OutputType requires a slightly different approach. Since the OutputType attribute declares a type we have to access it through the positional arguments (instead of named arguments that were used for CmdletBinding).
Here’s a helper function to verify that a given command has declared a given type as its output type.
function Test-OutputType {
[OutputType([Bool])]
[CmdletBinding()]
param (
# Parameter help description
[Parameter(Mandatory)]
[System.Management.Automation.CommandInfo]
$Command,
[Parameter(Mandatory)]
[string]
$TypeName
)
$attribute = $command.ScriptBlock.Ast.Body.ParamBlock.Attributes | where-object { $_.TypeName.FullName -eq 'OutputType' };
if ($attribute) {
$argument = $attribute.PositionalArguments | where-object {
if ($_.StaticType.Name -eq 'String') {
$_.Value -eq $TypeName
} elseif ($_.StaticType.Name -eq 'Type') {
$_.TypeName.Name -eq $TypeName
} else {
$false
}
}
if ($argument) {
$true
} else {
$false
}
} else {
$false
}
}
Note that a type can be declared as a string or as a type, but the helper function handles both cases:
[OutputType([Bool])]
[OutputType('System.Bool')]
And here’s an example of how it can be used within a Pester test.
It "Should have Output type Bool" {
$c = Get-Command -Name MyCommand
Test-TDDOutputType $c -TypeName 'Bool' | Should -BeTrue
}
Introducing TDDUtils
I have created a PowerShell module called TDDUtils, which contains the above functions (although named with a TDD prefix) as well as more general versions that allows you to test other attributes than CmdletBinding and OutputType.
You can install it from an Administrator PowerShell with the below command.
Install-Module TDDUtils
I plan to add more useful functions to that module as I go on with my PowerShell TDD journey, and if you want to contribute or just give me some suggestions, feel free to contact me on Twitter.