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.
#
Negative AssertionsWhen 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:
#
Should Operators#
BeCompares one object with another for equality and throws if the two objects are not the same. This comparison is not case sensitive.
Also compares an entire array for equality and throws if the array is not the same.
Comparisons will fail if the arrays have the same values, but not the same order.
#
BeExactlyCompares one object with another for equality and throws if the two objects are not the same. This comparison is case sensitive.
#
BeGreaterThanAsserts that a number is greater than an expected value. Uses PowerShell's -gt operator to compare the two values.
#
BeGreaterOrEqualAsserts 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.
#
BeInAsserts that the actual value is contained by the array/collection
#
BeLessThanAsserts that a number is less than an expected value. Uses PowerShell's -lt operator to compare the two values.
#
BeLessOrEqualAsserts 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.
#
BeLikeAsserts that the actual value matches a wildcard pattern using PowerShell's -like operator. This comparison is not case-sensitive.
#
BeLikeExactlyAsserts that the actual value matches a wildcard pattern using PowerShell's -clike operator. This comparison is case-sensitive.
#
BeOfTypeAsserts that the actual value should be an object of a specified type (or a subclass of the specified type) using PowerShell's -is operator:
#
BeTrueAsserts that the value is true, or truthy.
#
BeFalseAsserts that the value is false, or falsy.
#
HaveCountAsserts that a collection has the expected amount of items.
#
ContainAsserts that the collection contains value specified using PowerShell's -contains operator.
#
ExistDoes 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.
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
.
#
FileContentMatchChecks to see if a file contains the specified text. This search is not case sensitive and uses regular expressions.
Tip: Use [regex]::Escape("pattern")
to match the exact text.
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
.
#
FileContentMatchExactlyChecks to see if a file contains the specified text. This search is case sensitive and uses regular expressions to match the text.
#
FileContentMatchMultilineAs 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.
When using FileContentMatchMultiline operator, ^
and $
represent the beginning and end of the whole file, instead of the beginning and end of a line.
#
MatchUses a regular expression to compare two objects. This comparison is not case sensitive.
Tip: Use [regex]::Escape("pattern")
to match the exact text.
#
MatchExactlyUses a regular expression to compare two objects. This comparison is case sensitive.
#
ThrowChecks if an exception was thrown in the input ScriptBlock. Takes an optional argument to indicate the expected exception message.
Note: The exception message match is a substring match, so the following assertion will pass:
Warning: The input object must be a ScriptBlock, otherwise it is processed outside of the assertion.
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.
#
BeNullOrEmptyChecks values for null or empty (strings). The static [String]::IsNullOrEmpty() method is used to do the comparison.
#
BecauseAdds message to test failure message.
#
HaveParameterAn assertion operator -HaveParameter
allows you to check function parameters, and their properties like this: