This is documentation for Pester v4, which is no longer actively maintained.
For up-to-date documentation, see the latest version (v5).
Version: v4
Performing Assertions with Should
⚠️ All information on this page are relevant to Pester v. 4.x. You can read older version of this page - relevant to Pester v. 3.x - here.
Should is a command that provides assertion convenience methods for comparing objects and throwing test failures when test expectations fail. Should is used inside It blocks of a Pester test script.
When reviewing the operators listed below, keep in mind that all of them can be negated by putting the word "Not" between "Should" and the operator. For example:
Asserts that a number (or other comparable value) is greater than or equal to an expected value. Uses PowerShell's -ge operator to compare the two values.
Asserts that a number (or other comparable value) is lower than, or equal to an expected value. Uses PowerShell's -le operator to compare the two values.
Does not perform any comparison but checks if the object calling Exist is present in a PS Provider. The object must have valid path syntax. It essentially must pass a Test-Path call.
$actual=(Dir . )[0].FullName
Remove-Item $actual
$actual | Should -Exist # Test will fail
To test path containing [ ] wildcards, escape each bracket with two back-ticks as such "TestDrive:\``[test``].txt" or use Test-Path -LiteralPath $something | Should -Be $true.
Checks to see if a file contains the specified text. This search is not case sensitive and uses regular expressions.
Set-Content -Path TestDrive:\file.txt -Value 'I am a file'
'TestDrive:\file.txt' | Should -FileContentMatch 'I Am' # Test will pass
'TestDrive:\file.txt' | Should -FileContentMatch '^I.*file$' # Test will pass
'TestDrive:\file.txt' | Should -FileContentMatch 'I Am Not' # Test will fail
Tip: Use [regex]::Escape("pattern") to match the exact text.
Set-Content -Path TestDrive:\file.txt -Value 'I am a file.'
'TestDrive:\file.txt' | Should -FileContentMatch 'I.am.a.file' # Test will pass
'TestDrive:\file.txt' | Should -FileContentMatch ([regex]::Escape('I.am.a.file')) # Test will fail
Warning: Make sure the input is either a quoted string or an Item object. Otherwise PowerShell will try to invoke the
path, likely throwing an error Cannot run a document in the middle of a pipeline.
c:\file.txt | Should -FileContentMatch something # Will throw an error
'c:\file.txt' | Should -FileContentMatch something # Will evaluate correctly
As opposed to FileContentMatch and FileContentMatchExactly operators, FileContentMatchMultiline presents content of the file being tested as one string object, so that the expression you are comparing it to can consist of several lines.
$Content = "I am the first line.`nI am the second line."
Checks if an exception was thrown in the input ScriptBlock. Takes an optional argument to indicate the expected exception message.
{ foo } | Should -Throw # Test will pass
{ $foo = 1 } | Should -Throw # Test will fail
{ foo } | Should -Not -Throw # Test will fail
{ $foo = 1 } | Should -Not -Throw # Test will pass
{ throw "This is a test" } | Should -Throw "This is a test" # Test will pass
{ throw "bar" } | Should -Throw "This is a test" # Test will fail
Note: The exception message match is a substring match, so the following assertion will pass:
{throw "foo bar baz"} | Should -Throw "bar" # Test will pass
Warning: The input object must be a ScriptBlock, otherwise it is processed outside of the assertion.
Get-Process -Name "process" -ErrorAction Stop | Should -Throw # Should pass but fails the test
NOTE:Throw is used to validate terminating errors (i.e. exceptions that were thrown).
If you want to perform validation against non-terminating errors (i.e. Write-Error messages), you can use the technique described here.
NOTE: If you are calling a cmdlet and want to force all errors to be terminating errors so that they can be caught by | -Should -Throw, then append -ErrorAction Stop to the cmdlet parameters as shown in the example above.