https://pester.dev/assets/js/4dbe2da9.f0e251d8.js

1"use strict";(self.webpackChunkpester_docs=self.webpackChunkpester_docs||[]).push([["6877"],{9364(e,n,r){r.r(n),r.d(n,{metadata:()=>s,default:()=>h,frontMatter:()=>o,contentTitle:()=>i,toc:()=>d,assets:()=>a});var s=JSON.parse('{"id":"commands/Should-Throw","title":"Should-Throw","description":"Help for Pester command \'Should-Throw\'. Asserts that a script block throws an exception.","source":"@site/docs/commands/Should-Throw.mdx","sourceDirName":"commands","slug":"/commands/Should-Throw","permalink":"/docs/commands/Should-Throw","draft":false,"unlisted":false,"editUrl":null,"tags":[],"version":"current","frontMatter":{"id":"Should-Throw","title":"Should-Throw","description":"Help for Pester command \'Should-Throw\'. Asserts that a script block throws an exception.","keywords":["PowerShell","Pester","Help","Documentation"],"hide_title":false,"hide_table_of_contents":false,"custom_edit_url":null},"sidebar":"commands","previous":{"title":"Should-NotMatchString","permalink":"/docs/commands/Should-NotMatchString"}}'),l=r(1987),t=r(7008);let o={id:"Should-Throw",title:"Should-Throw",description:"Help for Pester command 'Should-Throw'. Asserts that a script block throws an exception.",keywords:["PowerShell","Pester","Help","Documentation"],hide_title:!1,hide_table_of_contents:!1,custom_edit_url:null},i,a={},d=[{value:"SYNOPSIS",id:"synopsis",level:2},{value:"SYNTAX",id:"syntax",level:2},{value:"DESCRIPTION",id:"description",level:2},{value:"EXAMPLES",id:"examples",level:2},{value:"EXAMPLE 1",id:"example-1",level:3},{value:"EXAMPLE 2",id:"example-2",level:3},{value:"PARAMETERS",id:"parameters",level:2},{value:"-AllowNonTerminatingError",id:"-allownonterminatingerror",level:3},{value:"-Because",id:"-because",level:3},{value:"-ExceptionMessage",id:"-exceptionmessage",level:3},{value:"-ExceptionType",id:"-exceptiontype",level:3},{value:"-FullyQualifiedErrorId",id:"-fullyqualifiederrorid",level:3},{value:"-ScriptBlock",id:"-scriptblock",level:3},{value:"CommonParameters",id:"commonparameters",level:3},{value:"INPUTS",id:"inputs",level:2},{value:"System.Management.Automation.ScriptBlock",id:"systemmanagementautomationscriptblock",level:3},{value:"OUTPUTS",id:"outputs",level:2},{value:"NOTES",id:"notes",level:2},{value:"RELATED LINKS",id:"related-links",level:2},{value:"VERSION",id:"version",level:2}];function c(e){let n={a:"a",admonition:"admonition",code:"code",em:"em",h2:"h2",h3:"h3",li:"li",p:"p",pre:"pre",ul:"ul",...(0,t.R)(),...e.components};return(0,l.jsxs)(l.Fragment,{children:[(0,l.jsx)(n.admonition,{title:"This page was generated",type:"info",children:(0,l.jsxs)(n.p,{children:["Contributions are welcome in ",(0,l.jsx)(n.a,{href:"https://github.com/pester/pester",children:"Pester-repo"}),"."]})}),"\n",(0,l.jsx)(n.h2,{id:"synopsis",children:"SYNOPSIS"}),"\n",(0,l.jsx)(n.p,{children:"Asserts that a script block throws an exception."}),"\n",(0,l.jsx)(n.h2,{id:"syntax",children:"SYNTAX"}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-powershell",children:"Should-Throw [[-ExceptionMessage] <string>] [[-FullyQualifiedErrorId] <string>]\n [[-ExceptionType] <type>] -ScriptBlock <scriptblock> [-Because <string>]\n [-AllowNonTerminatingError]\n"})}),"\n",(0,l.jsx)(n.h2,{id:"description",children:"DESCRIPTION"}),"\n",(0,l.jsxs)(n.p,{children:["This assertion executes the script block and expects it to throw.\nOptional filters let you match the exception type, message, or FullyQualifiedErrorId, and ",(0,l.jsx)(n.code,{children:"-AllowNonTerminatingError"})," accepts non-terminating errors."]}),"\n",(0,l.jsx)(n.h2,{id:"examples",children:"EXAMPLES"}),"\n",(0,l.jsx)(n.h3,{id:"example-1",children:"EXAMPLE 1"}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-powershell",children:"{ throw 'error' } | Should-Throw\n{ throw 'error' } | Should-Throw -ExceptionMessage 'error'\n{ throw 'wildcard character []' } | Should-Throw -ExceptionMessage '*character `[`]'\n{ throw 'error' } | Should-Throw -ExceptionType 'System.Management.Automation.RuntimeException'\n{ throw 'error' } | Should-Throw -FullyQualifiedErrorId 'RuntimeException'\n{ throw 'error' } | Should-Throw -FullyQualifiedErrorId '*Exception'\n{ throw 'error' } | Should-Throw -AllowNonTerminatingError\n"})}),"\n",(0,l.jsx)(n.p,{children:"All of these assertions will pass."}),"\n",(0,l.jsx)(n.h3,{id:"example-2",children:"EXAMPLE 2"}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-powershell",children:"$err = { throw 'error' } | Should-Throw\n$err.Exception.Message | Should-BeLike '*err*'\n"})}

1),"\n",(0,l.jsx)(n.p,{children:"The error record is returned from the assertion and can be used in further assertions."}),"\n",(0,l.jsx)(n.h2,{id:"parameters",children:"PARAMETERS"}),"\n",(0,l.jsx)(n.h3,{id:"-allownonterminatingerror",children:"-AllowNonTerminatingError"}),"\n",(0,l.jsx)(n.p,{children:"If set, the assertion will pass if a non-terminating error is thrown."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.Management.Automation.SwitchParameter\nDefaultValue: False\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- Name: (All)\n  Position: Named\n  IsRequired: false\n  ValueFromPipeline: false\n  ValueFromPipelineByPropertyName: false\n  ValueFromRemainingArguments: false\nDontShow: false\nAcceptedValues: []\nHelpMessage: ''\n"})}),"\n",(0,l.jsx)(n.h3,{id:"-because",children:"-Because"}),"\n",(0,l.jsx)(n.p,{children:"The reason why the input should be the expected value."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.String\nDefaultValue: ''\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- Name: (All)\n  Position: Named\n  IsRequired: false\n  ValueFromPipeline: false\n  ValueFromPipelineByPropertyName: false\n  ValueFromRemainingArguments: false\nDontShow: false\nAcceptedValues: []\nHelpMessage: ''\n"})}),"\n",(0,l.jsx)(n.h3,{id:"-exceptionmessage",children:"-ExceptionMessage"}),"\n",(0,l.jsxs)(n.p,{children:["The message that the exception should contain.\n",(0,l.jsx)(n.code,{children:"-like"})," wildcards are supported."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.String\nDefaultValue: ''\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- Name: (All)\n  Position: 0\n  IsRequired: false\n  ValueFromPipeline: false\n  ValueFromPipelineByPropertyName: false\n  ValueFromRemainingArguments: false\nDontShow: false\nAcceptedValues: []\nHelpMessage: ''\n"})}),"\n",(0,l.jsx)(n.h3,{id:"-exceptiontype",children:"-ExceptionType"}),"\n",(0,l.jsx)(n.p,{children:"The type of exception that should be thrown."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.Type\nDefaultValue: ''\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- Name: (All)\n  Position: 2\n  IsRequired: false\n  ValueFromPipeline: false\n  ValueFromPipelineByPropertyName: false\n  ValueFromRemainingArguments: false\nDontShow: false\nAcceptedValues: []\nHelpMessage: ''\n"})}),"\n",(0,l.jsx)(n.h3,{id:"-fullyqualifiederrorid",children:"-FullyQualifiedErrorId"}),"\n",(0,l.jsxs)(n.p,{children:["The FullyQualifiedErrorId that the exception should contain.\n",(0,l.jsx)(n.code,{children:"-like"})," wildcards are supported."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.String\nDefaultValue: ''\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- Name: (All)\n  Position: 1\n  IsRequired: false\n  ValueFromPipeline: false\n  ValueFromPipelineByPropertyName: false\n  ValueFromRemainingArguments: false\nDontShow: false\nAcceptedValues: []\nHelpMessage: ''\n"})}),"\n",(0,l.jsx)(n.h3,{id:"-scriptblock",children:"-ScriptBlock"}),"\n",(0,l.jsx)(n.p,{children:"The script block that should throw an exception."}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.Management.Automation.ScriptBlock\nDefaultValue: ''\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- Name: (All)\n  Position: Named\n  IsRequired: true\n  ValueFromPipeline: true\n  ValueFromPipelineByPropertyName: false\n  ValueFromRemainingArguments: false\nDontShow: false\nAcceptedValues: []\nHelpMessage: ''\n"})}),"\n",(0,l.jsx)(n.h3,{id:"commonparameters",children:"CommonParameters"}),"\n",(0,l.jsxs)(n.p,{children:["This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,\n-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable,\n-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see\n",(0,l.jsx)(n.a,{href:"https://go.microsoft.com/fwlink/?LinkID=113216",children:"about_CommonParameters"}),"."]}),"\n",(0,l.jsx)(n.h2,{id:"inputs",children:"INPUTS"}),"\n",(0,l.jsx)(n.h3,{id:"systemmanagementautomationscriptblock",children:"System.Management.Automation.ScriptBlock"}),"\n",(0,l.jsx)(n.h2,{id:"outputs",children:"OUTPUTS"}),"\n",(0,l.jsx)(n.h2,{id:"notes",children:"NOTES"}),"\n",(0,l.jsxs)(n.p,{children:["Use the ",(0,l.jsx)(n.code,{children:"-ErrorAction"})," parameter to control soft-assertion behavior for this assertion.\n",(0,l.jsx)(n.code,{children:"-ErrorAction Continue"})," records the failure and lets the rest of the test run (a soft assertion), while ",(0,l.jsx)(n.code,{children:"-ErrorAction Stop"})," fails the test immediately, for example to guard a precondition before continuing."]}),"\n",(0,l.jsxs)(n.p,{children:["When ",(0,l.jsx)(n.code,{children:"-ErrorAction"})," is not specified, the behavior comes from ",(0,l.jsx)(n.code,{children:"Should.ErrorAction"})," in the configuration, which defaults to ",(0,l.jsx)(n.code,{children:"Stop"}),".\nSee ",(0,l.jsx)(n.a,{href:"https://pester.dev/docs/assertions/soft-assertions",children:"https://pester.dev/docs/assertions/soft-assertions"})," for more about soft assertions."]}),"\n",(0,l.jsx)(n.h2,{id:"related-links",children:"RELATED LINKS"}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.a,{href:"https://pester.dev/docs/commands/Should-Throw",children:"https://pester.dev/docs/commands/Should-Throw"})}),"\n",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.a,{href:"https://pester.dev/docs/assertions",children:"https://pester.dev/docs/assertions"})}),"\n"]}),"\n",(0,l.jsx)(n.h2,{id:"version",children:"VERSION"}),"\n",(0,l.jsx)(n.p,{children:(0,l.jsxs)(n.em,{children:["This page was generated using comment-based help in ",(0,l.jsx)(n.a,{href:"https://github.com/pester/

1pester",children:"Pester 6.1.0"}),"."]})})]})}function h(e={}){let{wrapper:n}={...(0,t.R)(),...e.components};return n?(0,l.jsx)(n,{...e,children:(0,l.jsx)(c,{...e})}):c(e)}},7008(e,n,r){r.d(n,{R:()=>o,x:()=>i});var s=r(1763);let l={},t=s.createContext(l);function o(e){let n=s.useContext(t);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function i(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:o(e.components),s.createElement(t.Provider,{value:n},e.children)}}}]);