Should

This page was generated

Contributions are welcome in Pester-repo.

SYNOPSIS

Should is a keyword that is used to define an assertion inside an It block.

SYNTAX

Be

Should [[-ActualValue] <Object>] [-Be] [-Not] [-ExpectedValue <Object>] [-Because <Object>]
 [<CommonParameters>]

BeExactly

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeExactly]
 [<CommonParameters>]

BeGreaterThan

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeGreaterThan]
 [<CommonParameters>]

BeLessOrEqual

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeLessOrEqual]
 [<CommonParameters>]

BeIn

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeIn]
 [<CommonParameters>]

BeLessThan

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeLessThan]
 [<CommonParameters>]

BeGreaterOrEqual

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeGreaterOrEqual]
 [<CommonParameters>]

BeLike

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeLike]
 [<CommonParameters>]

BeLikeExactly

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-BeLikeExactly]
 [<CommonParameters>]

BeNullOrEmpty

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-BeNullOrEmpty] [<CommonParameters>]

BeOfType

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-BeOfType] [-ExpectedType <Object>]
 [<CommonParameters>]

BeTrue

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-BeTrue] [<CommonParameters>]

BeFalse

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-BeFalse] [<CommonParameters>]

Contain

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-Contain]
 [<CommonParameters>]

Exist

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-Exist] [<CommonParameters>]

FileContentMatch

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-FileContentMatch] [-ExpectedContent <Object>]
 [<CommonParameters>]

FileContentMatchExactly

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-ExpectedContent <Object>]
 [-FileContentMatchExactly] [<CommonParameters>]

FileContentMatchMultiline

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-ExpectedContent <Object>]
 [-FileContentMatchMultiline] [<CommonParameters>]

FileContentMatchMultilineExactly

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-ExpectedContent <Object>]
 [-FileContentMatchMultilineExactly] [<CommonParameters>]

HaveCount

Should [[-ActualValue] <Object>] [-Not] [-ExpectedValue <Object>] [-Because <Object>] [-HaveCount]
 [<CommonParameters>]

HaveParameter

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-HaveParameter] [-ParameterName <Object>]
 [-Type <Object>] [-DefaultValue <Object>] [-Mandatory] [-InParameterSet <Object>] [-HasArgumentCompleter]
 [-Alias <Object>] [<CommonParameters>]

Match

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-Match] [-RegularExpression <Object>]
 [<CommonParameters>]

MatchExactly

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-RegularExpression <Object>] [-MatchExactly]
 [<CommonParameters>]

Throw

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-Throw] [-ExpectedMessage <Object>]
 [-ErrorId <Object>] [-ExceptionType <Object>] [-PassThru] [<CommonParameters>]

InvokeVerifiable

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-InvokeVerifiable] [<CommonParameters>]

Invoke

Should [[-ActualValue] <Object>] [-Not] [-Because <Object>] [-Invoke] [-CommandName <Object>] [-Times <Object>]
 [-ParameterFilter <Object>] [-ExclusiveFilter <Object>] [-ModuleName <Object>] [-Scope <Object>] [-Exactly]
 [-CallerSessionState <Object>] [<CommonParameters>]

DESCRIPTION

Should is a keyword that is used to define an assertion inside an It block. Should provides assertion methods to verify assertions e.g. comparing objects. If assertion is not met the test fails and an exception is thrown.

Should can be used more than once in the It block if more than one assertion need to be verified. Each Should keyword needs to be on a separate line. Test will be passed only when all assertion will be met (logical conjunction).

EXAMPLES

EXAMPLE 1

Describe "d1" {
    It "i1" {
        Mock Get-Command { }
        Get-Command -CommandName abc
        Should -Invoke Get-Command -Times 1 -Exactly
    }
}

Example of creating a mock for Get-Command and asserting that it was called exactly one time.

EXAMPLE 2

$true | Should -BeFalse

Asserting that the input value is false. This would fail the test by throwing an error.

EXAMPLE 3

$a | Should -Be 10

Asserting that the input value defined in $a is equal to 10.

EXAMPLE 4

Should -Invoke Get-Command -Times 1 -Exactly

Asserting that the mocked Get-Command was called exactly one time.

EXAMPLE 5

$user | Should -Not -BeNullOrEmpty

Asserting that the input value from $user is not null or empty.

EXAMPLE 6

$planets.Name | Should -Be $Expected

Asserting that the value of $planets.Name is equal to the value defined in $Expected.

EXAMPLE 7

Context "We want to ensure an exception is thrown when expected" {
    It "Throws the exception" {
        { Get-Application -Name Blarg } | Should -Throw -ExpectedMessage "Application 'Blarg' not found"
    }
}

Asserting that Get-Application -Name Blarg will throw an exception with a specific message.

PARAMETERS

-ActualValue

The actual value that was obtained in the test which should be verified against a expected value.

Type: Object
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-Alias

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Be

Compares one object with another for equality and throws if the two objects are not the same.

Type: SwitchParameter
Parameter Sets: Be
Aliases: EQ

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Because

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeExactly

Compares one object with another for equality and throws if the two objects are not the same. This comparison is case sensitive.

Type: SwitchParameter
Parameter Sets: BeExactly
Aliases: CEQ

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeFalse

Asserts that the value is false, or falsy.

Type: SwitchParameter
Parameter Sets: BeFalse
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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.

Type: SwitchParameter
Parameter Sets: BeGreaterOrEqual
Aliases: GE

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeGreaterThan

Asserts that a number (or other comparable value) is greater than an expected value. Uses PowerShell's -gt operator to compare the two values.

Type: SwitchParameter
Parameter Sets: BeGreaterThan
Aliases: GT

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeIn

Asserts that a collection of values contain a specific value. Uses PowerShell's -contains operator to confirm.

Type: SwitchParameter
Parameter Sets: BeIn
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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.

Type: SwitchParameter
Parameter Sets: BeLessOrEqual
Aliases: LE

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeLessThan

Asserts that a number (or other comparable value) is lower than an expected value. Uses PowerShell's -lt operator to compare the two values.

Type: SwitchParameter
Parameter Sets: BeLessThan
Aliases: LT

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeLike

Asserts that the actual value matches a wildcard pattern using PowerShell's -like operator. This comparison is not case-sensitive.

Type: SwitchParameter
Parameter Sets: BeLike
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeLikeExactly

Asserts that the actual value matches a wildcard pattern using PowerShell's -like operator. This comparison is case-sensitive.

Type: SwitchParameter
Parameter Sets: BeLikeExactly
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeNullOrEmpty

Checks values for null or empty (strings). The static [String]::IsNullOrEmpty() method is used to do the comparison.

Type: SwitchParameter
Parameter Sets: BeNullOrEmpty
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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.

Type: SwitchParameter
Parameter Sets: BeOfType
Aliases: HaveType

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-BeTrue

Asserts that the value is true, or truthy.

Type: SwitchParameter
Parameter Sets: BeTrue
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-CallerSessionState

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-CommandName

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Contain

Asserts that collection contains a specific value. Uses PowerShell's -contains operator to confirm.

Type: SwitchParameter
Parameter Sets: Contain
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-DefaultValue

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ErrorId

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Throw
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Exactly

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: SwitchParameter
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExceptionType

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Throw
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExclusiveFilter

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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.

Type: SwitchParameter
Parameter Sets: Exist
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExpectedContent

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: FileContentMatch, FileContentMatchExactly, FileContentMatchMultiline, FileContentMatchMultilineExactly
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExpectedMessage

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Throw
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExpectedType

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: BeOfType
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ExpectedValue

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Be, BeExactly, BeGreaterThan, BeLessOrEqual, BeIn, BeLessThan, BeGreaterOrEqual, BeLike, BeLikeExactly, Contain, HaveCount
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FileContentMatch

Checks to see if a file contains the specified text. This search is not case sensitive and uses regular expressions.

Type: SwitchParameter
Parameter Sets: FileContentMatch
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FileContentMatchExactly

Checks to see if a file contains the specified text. This search is case sensitive and uses regular expressions to match the text.

Type: SwitchParameter
Parameter Sets: FileContentMatchExactly
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-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.

When using FileContentMatchMultiline operator, '^' and '$' represent the beginning and end of the whole file, instead of the beginning and end of a line

Type: SwitchParameter
Parameter Sets: FileContentMatchMultiline
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-FileContentMatchMultilineExactly

As opposed to FileContentMatch and FileContentMatchExactly operators, FileContentMatchMultilineExactly presents content of the file being tested as one string object, so that the case sensitive expression you are comparing it to can consist of several lines.

When using FileContentMatchMultilineExactly operator, '^' and '$' represent the beginning and end of the whole file, instead of the beginning and end of a line.

Type: SwitchParameter
Parameter Sets: FileContentMatchMultilineExactly
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-HasArgumentCompleter

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: SwitchParameter
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-HaveCount

Asserts that a collection has the expected amount of items.

Type: SwitchParameter
Parameter Sets: HaveCount
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-HaveParameter

Asserts that a command has the expected parameter.

Type: SwitchParameter
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-InParameterSet

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Invoke

Checks if a Mocked command has been called a certain number of times and throws an exception if it has not.

Type: SwitchParameter
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-InvokeVerifiable

Checks if any Verifiable Mock has not been invoked. If so, this will throw an exception.

Type: SwitchParameter
Parameter Sets: InvokeVerifiable
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Mandatory

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: SwitchParameter
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Match

Uses a regular expression to compare two objects. This comparison is not case sensitive.

Type: SwitchParameter
Parameter Sets: Match
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-MatchExactly

Uses a regular expression to compare two objects. This comparison is case sensitive.

Type: SwitchParameter
Parameter Sets: MatchExactly
Aliases: CMATCH

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ModuleName

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Not

Reverse the assertion

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ParameterFilter

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ParameterName

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-PassThru

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: SwitchParameter
Parameter Sets: Throw
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-RegularExpression

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Match, MatchExactly
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Scope

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Throw

Checks if an exception was thrown. Enclose input in a scriptblock.

Type: SwitchParameter
Parameter Sets: Throw
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Times

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: Invoke
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Type

Depends on operator being used. See Get-ShouldOperator -Name <Operator> or https://pester.dev/docs/assertions/ for help.

Type: Object
Parameter Sets: HaveParameter
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

NOTES

RELATED LINKS

https://pester.dev/docs/commands/Should

https://pester.dev/docs/assertions

VERSION

This page was generated using comment-based help in Pester 6.0.0-alpha1.