Skip to main content
Version: v6

Should-Throw

This page was generated

Contributions are welcome in Pester-repo.

SYNOPSIS​

Asserts that a script block throws an exception.

SYNTAX​

Should-Throw [[-ExceptionMessage] <string>] [[-FullyQualifiedErrorId] <string>]
 [[-ExceptionType] <type>] [[-Because] <string>] -ScriptBlock <scriptblock>
 [-AllowNonTerminatingError]

DESCRIPTION​

This assertion executes the script block and expects it to throw. Optional filters let you match the exception type, message, or FullyQualifiedErrorId, and -AllowNonTerminatingError accepts non-terminating errors.

EXAMPLES​

EXAMPLE 1​

{ throw 'error' } | Should-Throw
{ throw 'error' } | Should-Throw -ExceptionMessage 'error'
{ throw 'wildcard character []' } | Should-Throw -ExceptionMessage '*character `[`]'
{ throw 'error' } | Should-Throw -ExceptionType 'System.Management.Automation.RuntimeException'
{ throw 'error' } | Should-Throw -FullyQualifiedErrorId 'RuntimeException'
{ throw 'error' } | Should-Throw -FullyQualifiedErrorId '*Exception'
{ throw 'error' } | Should-Throw -AllowNonTerminatingError

All of these assertions will pass.

EXAMPLE 2​

$err = { throw 'error' } | Should-Throw
$err.Exception.Message | Should-BeLike '*err*'

The error record is returned from the assertion and can be used in further assertions.

PARAMETERS​

-AllowNonTerminatingError​

If set, the assertion will pass if a non-terminating error is thrown.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Because​

The reason why the input should be the expected value.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 3
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ExceptionMessage​

The message that the exception should contain. -like wildcards are supported.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ExceptionType​

The type of exception that should be thrown.

Type: System.Type
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 2
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-FullyQualifiedErrorId​

The FullyQualifiedErrorId that the exception should contain. -like wildcards are supported.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ScriptBlock​

The script block that should throw an exception.

Type: System.Management.Automation.ScriptBlock
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: true
  ValueFromPipeline: true
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters​

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

INPUTS​

System.Management.Automation.ScriptBlock​

OUTPUTS​

NOTES​

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.

VERSION​

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