PowerShell How-To

Understanding Should Assertions in Pester

"Should" operators have the critical role of comparing a condition with an expected result. Without that functionality, a test of your PowerShell code would be worthless.

• By Adam Bertram
• 10/01/2019

Pester is the de facto standard for writing tests in PowerShell. Pester is a unit testing framework built as a PowerShell module that allows you to ensure the PowerShell code you write meets your expectations.

One of the most prominent features of the Pester testing framework and all other code-testing frameworks is the concept of assertions. In a nutshell, a test consists of two components: the code to check for a condition and the code to compare the result of that condition with an expected result. The code that compares the condition with an expected outcome is called an assertion.

Assertions are the decision-makers. Assertions decide if a test succeeds or fails.

In Pester, the should operator allows the testing framework to perform the test evaluation. The should operator checks a condition against a string to verify whether that condition is true or false. (If you'd like to dive deep into should assertions and all else that is the Pester testing framework, check out The Pester Book.)

Types of Should Assertions
Pester should assertions are roughly categorized into the type of input they can receive.

• Scalar assertions compare single elements to another element. Assertions include Be, BeExactly, BeGreaterThan and BeLessThan.
• List comparisons compare elements in lists and list counts. Assertions include BeIn and HaveCount.
• File comparisons compare the state of a text file. Assertions include FileContentMatch and FileContentMatchExactly.

For a full list of assertions, check out the Pester should assertion page.

How To Use Should Assertions
Should assertions are referenced by piping output from one command or object to the should Pester function followed by the operator name. Under the covers, the should operators are actually PowerShell parameters to the should function.

For example, if you want to test the equality of the sum of 1 plus 1 and compare that to the number 2, you should use the Be operator, which compares an object with another for equality:

describe 'My set of tests' {
    it 'one plus one equals two' {
        1 + 1 | should -Be 2
    }
}

When executed, this test will return a passing test, as shown below:

" Describing My set of tests   [+] one plus one equals two 92ms"

Perhaps you have an array and want to confirm that array has a specific number of elements or that it contains a particular element. You would use the BeIn and HaveCount should operators, as shown below:

describe 'My set of tests' {
    $colors = @('Red','Green')
    it 'the colors array has the color Green in it' {
        'Green' | should -BeIn $colors
    }

    it 'the colors array has three colors in it' {
        $colors | should -HaveCount 3
    }
}

When executed, you'll see the test results below:

Describing My set of tests
  [+] the colors array has the color Green in it 8ms
  [-] the colors array has three colors in it 62ms
    Expected a collection with size 3, but got collection with size 2 @('Red', 'Green').
    8:         $colors | should -HaveCount 3

You'll notice that one test failed because the should operator calculated a count of 2, but it was expecting a count of 3.

Summary
Should operators play a significant part in an overall PowerShell testing strategy. They allow testers the critical job of comparing a condition with an expected result. Without that functionality, a test would be worthless.

Look into the various Pester should operators available to you. Notice what kind of input you have and what you need to compare. If you notice Pester does not provide a should operator you need, you can also build your own custom should operators...but that's an article for another day.