Should-Invoke
Contributions are welcome in Pester-repo.
SYNOPSIS
Checks if a Mocked command has been called a certain number of times and throws an exception if it has not.
SYNTAX
Default (Default)
Should-Invoke [-CommandName] <String> [[-Times] <Int32>] [-ParameterFilter <ScriptBlock>]
[-ExclusiveFilter <ScriptBlock>] [-ModuleName <String>] [-Scope <String>] [-Exactly] [-Because <String>]
[<CommonParameters>]
ExclusiveFilter
Should-Invoke -ExclusiveFilter <ScriptBlock> [<CommonParameters>]
Verifiable
Should-Invoke [-Because <String>] [-Verifiable] [<CommonParameters>]
DESCRIPTION
This command verifies that a mocked command has been called a certain number of times. If the call history of the mocked command does not match the parameters passed to Should-Invoke, Should-Invoke will throw an exception.
EXAMPLES
EXAMPLE 1
function Save-Report ($Path, $Content) {
Set-Content -Path $Path -Value $Content
}
Describe 'Save-Report' {
It 'writes the report to disk' {
Mock Set-Content
Save-Report -Path 'report.txt' -Content 'All systems green'
Should-Invoke Set-Content -Times 1 -Exactly
}
}
Asserts that Save-Report wrote to disk by calling the mocked Set-Content exactly once.
The test fails if Set-Content was not called, or was called more than once.
EXAMPLE 2
Mock Set-Content
Save-Report -Path 'report.txt' -Content 'All systems green'
Should-Invoke Set-Content -ParameterFilter { $Path -eq 'report.txt' }
Only the calls where -Path was report.txt are counted.
The assertion passes, because Save-Report wrote to that path.
EXAMPLE 3
function Get-Weather ($City) {
Invoke-RestMethod -Uri "https://api.example.com/weather?city=$City"
}
Mock Invoke-RestMethod
Get-Weather -City 'Oslo'
Should-Invoke Invoke-RestMethod -Times 1 -Exactly -ParameterFilter { $Uri -match 'city=Oslo' }
Asserts that the weather API was queried exactly once, and that the request was made for the city of Oslo.
EXAMPLE 4
Describe 'Save-Report' {
BeforeAll { Mock Set-Content }
It 'writes exactly once per call' {
Save-Report -Path 'a.txt' -Content 'x'
Should-Invoke Set-Content -Times 1 -Exactly -Scope It
}
}
-Scope It counts only the calls made in the current It block, even though the mock is shared by the whole Describe.
EXAMPLE 5
Describe 'Publish-Thing' {
It 'writes from inside the module' {
Mock -ModuleName Toolbox Set-Content
Publish-Thing
Should-Invoke -ModuleName Toolbox Set-Content -Times 1 -Exactly
}
}
When the command under test lives in a module, both Mock and Should-Invoke must use the same -ModuleName so the recorded call is found.
EXAMPLE 6
Mock Remove-Item
Remove-TempFile -Path "$env:TEMP/old.log"
Should-Invoke Remove-Item -ExclusiveFilter { $Path -like "$env:TEMP*" }
-ExclusiveFilter passes only if every recorded call matches the filter.
Here it asserts that Remove-Item was called at least once, and only ever for paths inside the temp folder.
It is a shorthand for pairing a Should-Invoke and a Should-NotInvoke.
PARAMETERS
-CommandName
The mocked command whose call history should be checked.
Type: String
Parameter Sets: Default
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Times
The number of times that the mock must be called to avoid an exception from throwing.
Type: Int32
Parameter Sets: Default
Aliases:
Required: False
Position: 2
Default value: 1
Accept pipeline input: False
Accept wildcard characters: False
-ParameterFilter
An optional filter to qualify which calls should be counted. Only those calls to the mock whose parameters cause this filter to return true will be counted.
Type: ScriptBlock
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: { $True }
Accept pipeline input: False
Accept wildcard characters: False
-ExclusiveFilter
Like ParameterFilter, except when you use ExclusiveFilter, and there were any calls to the mocked command which do not match the filter, an exception will be thrown. This is a convenient way to avoid needing to have two calls to Should-Invoke like this:
Should-Invoke SomeCommand -Times 1 -ParameterFilter { $something -eq $true } Should-Invoke SomeCommand -Times 0 -ParameterFilter { $something -ne $true }
Type: ScriptBlock
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
Type: ScriptBlock
Parameter Sets: ExclusiveFilter
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ModuleName
The module where the mock being checked was injected. This is optional, and must match the ModuleName that was used when setting up the Mock.
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Scope
An optional parameter specifying the Pester scope in which to check for calls to the mocked command. For RSpec style tests, Should-Invoke will find all calls to the mocked command in the current Context block (if present), or the current Describe block (if there is no active Context), by default. Valid values are Describe, Context and It. If you use a scope of Describe or Context, the command will identify all calls to the mocked command in the current Describe / Context block, as well as all child scopes of that block.
Type: String
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-Exactly
If this switch is present, the number specified in Times must match exactly the number of times the mock has been called. Otherwise it must match "at least" the number of times specified. If the value passed to the Times parameter is zero, the Exactly switch is implied.
Type: SwitchParameter
Parameter Sets: Default
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Because
The reason why the mock should be called.
Type: String
Parameter Sets: Default, Verifiable
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Verifiable
Makes sure that all verifiable mocks were called.
Type: SwitchParameter
Parameter Sets: Verifiable
Aliases:
Required: False
Position: Named
Default value: False
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
The parameter filter passed to Should-Invoke does not necessarily have to match the parameter filter (if any) which was used to create the Mock. Should-Invoke will find any entry in the command history which matches its parameter filter, regardless of how the Mock was created. However, if any calls to the mocked command are made which did not match any mock's parameter filter (resulting in the original command being executed instead of a mock), these calls to the original command are not tracked in the call history. In other words, Should-Invoke can only be used to check for calls to the mocked implementation, not to the original.
Use the -ErrorAction parameter to control soft-assertion behavior for this assertion.
-ErrorAction Continue records the failure and lets the rest of the test run (a soft assertion), while -ErrorAction Stop fails the test immediately, for example to guard a precondition before continuing.
When -ErrorAction is not specified, the behavior comes from Should.ErrorAction in the configuration, which defaults to Stop.
See https://pester.dev/docs/assertions/soft-assertions for more about soft assertions.
RELATED LINKS
https://pester.dev/docs/commands/Should-Invoke
https://pester.dev/docs/assertions
VERSION
This page was generated using comment-based help in Pester 6.0.0-rc5.