Assertion Reference (v4/v5)
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.
Common parameters​
Negative Assertions​
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:
$true | Should -Be $true
$true | Should -Not -Be $false
Because​
Lets you to add an optional message to the default test error message to tell the user why the test should pass. Example using Get-Planet from Quick Start:
$mPlanets = Get-Planet -Name M*
$mPlanets.Name + @('Earth') | Should -Be 'Mercury','Mars' -Because 'those are the only two planets starting with M'
# OUTPUT
# Expected @('Mercury', 'Mars'), because those are the only two planets starting with M, but got @('Mercury', 'Mars', 'Earth').
Should Operators​
You can find a list of all operators included in Pester below. You may also use Get-ShouldOperator to list the available operators, their aliases and help inside PowerShell.
You may also create custom operators to support more complex assertions, see Custom Assertions.
Be​
Compares one object with another for equality and throws if the two objects are not the same. This comparison is not case sensitive.
$actual="Actual value"
$actual | Should -Be "actual value" # Test will pass
$actual | Should -Be "not actual value" # Test will fail
Also compares an entire array for equality and throws if the array is not the same.
$array = @(1, 2, 3, 4, 'I am a string', (New-Object psobject -Property @{ IAm = 'An Object' }))
$array | Should -Be $array # Test will pass
$string = 'I am a string'
$array = @(1, 2, 3, 4, $string)
$arrayWithCaps = @(1, 2, 3, 4, $string.ToUpper())
$array | Should -Be $arrayWithCaps # Test will pass
Comparisons will fail if the arrays have the same values, but not the same order.
[int32[]]$array = (1..10)
$arrayoutoforder = (1,10,2,3,4,5,6,7,8,9)
$array | Should -Be $arrayOutOfOrder # Test will fail
BeExactly​
Compares one object with another for equality and throws if the two objects are not the same. This comparison is case sensitive.
$actual="Actual value"
$actual | Should -BeExactly "Actual value" # Test will pass
$actual | Should -BeExactly "actual value" # Test will fail
BeFalse​
Asserts that the value is false, or falsy.
$false | Should -BeFalse
0 | Should -BeFalse
$null | Should -BeFalse
BeGreaterOrEqual​
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.
2 | Should -BeGreaterOrEqual 0
2 | Should -BeGreaterOrEqual 2
BeGreaterThan​
Asserts that a number is greater than an expected value. Uses PowerShell's -gt operator to compare the two values.
$Error.Count | Should -BeGreaterThan 0
[version]'2.3.4.5' | Should -BeGreaterThan ([version]'1.0.0.1')
(Get-Date).AddMinutes(5) | Should -BeGreaterThan (Get-Date)
BeIn​
Asserts that the actual value is present in the array/collection
'b' | Should -BeIn @('a','b','c')
27 | Should -BeIn (1..100)
BeLessOrEqual​
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.
1 | Should -BeLessOrEqual 10
10 | Should -BeLessOrEqual 10
BeLessThan​
Asserts that a number is less than an expected value. Uses PowerShell's -lt operator to compare the two values.
$Error.Count | Should -BeLessThan 1
BeLike​
Asserts that the actual value matches a wildcard pattern using PowerShell's -like operator. This comparison is not case-sensitive.
$actual="Actual value"
$actual | Should -BeLike "actual *" # Test will pass
$actual | Should -BeLike "not actual *" # Test will fail
BeLikeExactly​
Asserts that the actual value matches a wildcard pattern using PowerShell's -clike operator. This comparison is case-sensitive.
$actual="Actual value"
$actual | Should -BeLikeExactly "Actual *" # Test will pass
$actual | Should -BeLikeExactly "actual *" # Test will fail
BeNullOrEmpty​
Checks values for null or empty (strings). The static [String]::IsNullOrEmpty() method is used to do the comparison.
$null | Should -BeNullOrEmpty # Test will pass
@() | Should -BeNullOrEmpty # Test will pass
"" | Should -BeNullOrEmpty # Test will pass
$null | Should -Not -BeNullOrEmpty # Test will fail
BeOfType​
Asserts that the actual value should be an object of a specified type (or a subclass of the specified type) using PowerShell's -is operator:
$actual = Get-Item $env:SystemRoot
$actual | Should -BeOfType System.IO.DirectoryInfo # Test will pass; object is a DirectoryInfo
$actual | Should -BeOfType System.IO.FileSystemInfo # Test will pass; DirectoryInfo base class is FileSystemInfo
$actual | Should -BeOfType System.IO.FileInfo # Test will fail; FileInfo is not a base class of DirectoryInfo
This currently only works for .NET types. For custom type name, added using PSTypeNames, you need to use $MyClass.GetType().Name | Should -Be "MyClassName". See this issue for more information.
BeTrue​
Asserts that the value is true, or truthy.
$true | Should -BeTrue
1 | Should -BeTrue
1,2,3 | Should -BeTrue
Contain​
Asserts that the collection contains value specified using PowerShell's -contains operator.
'a','b','c' | Should -Contain b
1..100 | Should -Contain 42
Exist​
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.
FileContentMatch​
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
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
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
FileContentMatchExactly​
Checks to see if a file contains the specified text. This search is case sensitive and uses regular expressions to match the text.
Set-Content -Path TestDrive:\file.txt -Value 'I am a file.'
'TestDrive:\file.txt' | Should -FileContentMatchExactly 'I am' # Test will pass
'TestDrive:\file.txt' | Should -FileContentMatchExactly 'I Am' # Test will fail
FileContentMatchMultiline​
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."
Set-Content -Path TestDrive:\file.txt -Value $Content -NoNewline
'TestDrive:\file.txt' | Should -FileContentMatchMultiline 'first line\.\r?\nI am' # Test will pass
'TestDrive:\file.txt' | Should -FileContentMatchMultiline '^I am the first.*\n.*second line\.$' # Test will pass.
When using FileContentMatchMultiline operator, ^ and $ represent the beginning and end of the whole file, instead of the beginning and end of a line.
$Content = "I am the first line.`nI am the second line."
Set-Content -Path TestDrive:\file.txt -Value $Content -NoNewline
'TestDrive:\file.txt' | Should -FileContentMatchMultiline '^I am the first line\.$' # Test will fail.
FileContentMatchMultilineExactly​
As opposed to FileContentMatch and FileContentMatchExactly operators, FileContentMatchMultilineExactly 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. This search is case sensitive and uses regular expressions to match the text.
$Content = "I am the first line.`nI am the second line."
Set-Content -Path TestDrive:\file.txt -Value $Content -NoNewline
'TestDrive:\file.txt' | Should -FileContentMatchMultilineExactly 'first line\.\r?\nI am' # Test will pass
'TestDrive:\file.txt' | Should -FileContentMatchMultilineExactly 'first line\.\r?\nI AM' # Test will fail
'TestDrive:\file.txt' | Should -FileContentMatchMultilineExactly '^I am the first.*\n.*second line\.$' # Test will pass.
'TestDrive:\file.txt' | Should -FileContentMatchMultilineExactly '^I AM THE FIRST.*\n.*second line\.$' # Test will fail.
When using FileContentMatchMultilineExactly operator, ^ and $ represent the beginning and end of the whole file, instead of the beginning and end of a line.
$Content = "I am the first line.`nI am the second line."
Set-Content -Path TestDrive:\file.txt -Value $Content -NoNewline
'TestDrive:\file.txt' | Should -FileContentMatchMultilineExactly '^I am the first line\.$' # Test will fail.
HaveCount​
Asserts that a collection has the expected amount of items.
1,2,3 | Should -HaveCount 3
HaveParameter​
An assertion operator -HaveParameter allows you to check function parameters, and their properties like this:
Get-Command "Invoke-WebRequest" | Should -HaveParameter Uri -Mandatory
function f ([String] $Value = 8) { }
Get-Command f | Should -HaveParameter Value -Type String
Get-Command f | Should -Not -HaveParameter Name
Get-Command f | Should -HaveParameter Value -DefaultValue 8
Get-Command f | Should -HaveParameter Value -Not -Mandatory
Invoke​
Checks if a mocked command has been called a certain number of times and throws an exception if it has not. See Mocking for more details.
InvokeVerifiable​
Checks if any verifiable Mock have not been invoked. If so, this will throw an exception. See Mocking for more details.
Match​
Uses a regular expression to compare two objects. This comparison is not case sensitive.
"I am a value" | Should -Match "I Am" # Test will pass
"I am a value" | Should -Match "I am a bad person" # Test will fail
Use [regex]::Escape("pattern") to match the exact text.
"Greg" | Should -Match ".reg" # Test will pass
"Greg" | Should -Match ([regex]::Escape(".reg")) # Test will fail
MatchExactly​
Uses a regular expression to compare two objects. This comparison is case sensitive.
"I am a value" | Should -MatchExactly "I am" # Test will pass
"I am a value" | Should -MatchExactly "I Am" # Test will fail
Throw​
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
The exception message match is a -like
wildcard match,
so the following assertion will pass:
{throw "foo bar baz"} | Should -Throw "*bar*" # Test will pass
Wildcard-characters ?*[] can be escaped using backtick, ex `*.
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
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.
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.