In this post I’m going to cover unit testing PowerShell with Pester.
As your PowerShell scripts become more complicated it can be difficult and time consuming to manually test them. This is especially true when your script relies on external resources like ActiveDirectory or Azure infrastructure. Pester is a framework specifically designed to unit test PowerShell scripts. It enables mocking, assertions and running tests using nunit or Visual Studio test explorer among others.
How to install it
In PowerShell 5.0 and greater you can install the Pester module by running:
Install-Module Pester
If for some reason you are unable to do that you can manually download it from Github and copy it to a folder that is in your $ENV:PSModulePath environment variable or use choclatey.
Invoke-Expression ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))
choco install pester -yTo confirm that the module is loaded run:
Get-Module -ListAvailable
Authoring Tests
I highly recommend using Visual Studio with PowerShell tools installed for your PowerShell projects, this demo will be using it. In VS create a PowerShell Script Project, add a PowerShell test to it using the PowerShell Test template.
The VS test explorer will pick up your PowerShell tests, same it does for other unit tests. Pester has a naming convention to follow for the tests and scripts, the test file should have the same name as the script to test but with .test before the extensions. If you don’t follow the convention the tests will show as greyed out in the VS test explorer.
The structure of a test
At the top of each test file you have to dot source the script file that will be tested.
.\PathTo\ScriptFiletoTest.ps1
In the demo project this is done using logic based on the naming convention. The structure of the actual test looks like this:
The Description section will group your tests together and this is also the name you will see in VS test explorer. Context creates a scope for variables and mocked objects. It will contain the code for your test and at least one assertion or else the test will not run.
Mocking And Assertions
You can mock calls to your own functions as well as calls to PowerShell modules. For example if you want Get-Date to return a specific date in your test you can do this:
Mock Get-Date { New-Object DateTime (2000, 1, 1) }
$date = GetMyOwnDate
It "It Should Be The Year 2000"{
($date).year | Should be "2000"
}If you want to verify that a method is called with specific parameters you can do this:
Mock Myfunction {} -Verifiable -ParameterFilter {$myparam -eq $folder}
...
Assert-VerifiableMocksI have a sample project on GitHub to show some of the functionality of Pester but read the wiki on their GitHub repo to get the full picture .
Some Errors I Encountered And Tips
- The nuget package didn’t work for since nuget doesn’t understand PowerShell projects.
- If your tests doesn’t run and you get a yellow exclamation mark next to the test in text explorer one cause could be that there are no assertions in your test “It” block.
- I also tried mocking some ActiveDirectory calls on a Windows 1o machine. To get the PowerShell modules you have to install Remote Server Administration tools for your client OS.
- If you want to mock the calls inside another module instead of just mocking your calls to those functions follow this guide.
