1"use strict";(self.webpackChunkpester_docs=self.webpackChunkpester_docs||[]).push([["2347"],{5620(e,n,s){s.r(n),s.d(n,{metadata:()=>t,default:()=>h,frontMatter:()=>a,contentTitle:()=>r,toc:()=>d,assets:()=>o});var t=JSON.parse('{"id":"commands/New-ShouldAssertion","title":"New-ShouldAssertion","description":"Help for Pester command \'New-ShouldAssertion\'. Creates the assertion helper object used to author custom `Should-*` assertions.","source":"@site/docs/commands/New-ShouldAssertion.mdx","sourceDirName":"commands","slug":"/commands/New-ShouldAssertion","permalink":"/docs/commands/New-ShouldAssertion","draft":false,"unlisted":false,"editUrl":null,"tags":[],"version":"current","frontMatter":{"id":"New-ShouldAssertion","title":"New-ShouldAssertion","description":"Help for Pester command \'New-ShouldAssertion\'. Creates the assertion helper object used to author custom `Should-*` assertions.","keywords":["PowerShell","Pester","Help","Documentation"],"hide_title":false,"hide_table_of_contents":false,"custom_edit_url":null},"sidebar":"commands","previous":{"title":"New-PesterContainer","permalink":"/docs/commands/New-PesterContainer"},"next":{"title":"Set-ItResult","permalink":"/docs/commands/Set-ItResult"}}'),l=s(1987),i=s(7008);let a={id:"New-ShouldAssertion",title:"New-ShouldAssertion",description:"Help for Pester command 'New-ShouldAssertion'. Creates the assertion helper object used to author custom `Should-*` assertions.",keywords:["PowerShell","Pester","Help","Documentation"],hide_title:!1,hide_table_of_contents:!1,custom_edit_url:null},r,o={},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:"-Actual",id:"-actual",level:3},{value:"-As",id:"-as",level:3},{value:"-Buffer",id:"-buffer",level:3},{value:"-Caller",id:"-caller",level:3},{value:"CommonParameters",id:"commonparameters",level:3},{value:"INPUTS",id:"inputs",level:2},{value:"OUTPUTS",id:"outputs",level:2},{value:"ShouldAssertion",id:"shouldassertion",level:3},{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,i.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.jsxs)(n.p,{children:["Creates the assertion helper object used to author custom ",(0,l.jsx)(n.code,{children:"Should-*"})," assertions."]}),"\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:"New-ShouldAssertion [-Caller] <PSCmdlet> [[-Actual] <Object>] [[-Buffer] <Object[]>] [-As <string>]\n"})}),"\n",(0,l.jsx)(n.h2,{id:"description",children:"DESCRIPTION"}),"\n",(0,l.jsxs)(n.p,{children:[(0,l.jsx)(n.code,{children:"New-ShouldAssertion"})," returns a small helper object (conventionally stored in ",(0,l.jsx)(n.code,{children:"$assert"}),")\nthat gives a custom assertion the same building blocks the built-in ",(0,l.jsx)(n.code,{children:"Should-*"})," assertions\nuse: pipeline input collection, consistent value formatting, diagnostic input hints, and\nthe shared failure path that powers soft assertions."]}),"\n",(0,l.jsxs)(n.p,{children:["Call it once at the top of your assertion, passing the assertion's own ",(0,l.jsx)(n.code,{children:"$PSCmdlet"}),", its\n",(0,l.jsx)(n.code,{children:"-Actual"})," value and ",(0,l.jsx)(n.code,{children:"$Input"}),", then use the returned object's methods:"]}),"\n",(0,l.jsxs)(n.ul,{children:["\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"Actual()"})," returns the value to assert on, collected from either the pipeline or the\n",(0,l.jsx)(n.code,{children:"-Actual"})," parameter.\nThe ",(0,l.jsx)(n.code,{children:"-As"})," parameter (",(0,l.jsx)(n.code,{children:"Scalar"})," (default), ",(0,l.jsx)(n.code,{children:"ExactType"}),", ",(0,l.jsx)(n.code,{children:"Collection"}),"\nor ",(0,l.jsx)(n.code,{children:"CollectionItems"}),") selects both unrolling and the wording of the input hint."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"Fail(message [, data])"})," reports a failure.\n",(0,l.jsx)(n.code,{children:"message"})," may contain ",(0,l.jsx)(n.code,{children:"<expected>"}),",\n",(0,l.jsx)(n.code,{children:"<actual>"}),", ",(0,l.jsx)(n.code,{children:"<expectedType>"}),", ",(0,l.jsx)(n.code,{children:"<actualType>"}),", ",(0,l.jsx)(n.code,{children:"<because>"})," and any ",(0,l.jsx)(n.code,{children:"<key>"})," present in\n",(0,l.jsx)(n.code,{children:"data"}),".\n",(0,l.jsx)(n.code,{children:"data"})," is a hashtable whose ",(0,l.jsx)(n.code,{children:"Expected"}),", ",(0,l.jsx)(n.code,{children:"Actual"}),", ",(0,l.jsx)(n.code,{children:"Because"})," and ",(0,l.jsx)(n.code,{children:"Hint"})," entries\nare treated specially; all other entries become message tokens.\n",(0,l.jsx)(n.code,{children:"Hint"})," overrides the\ndefault input hint with your own text, appended as ",(0,l.jsx)(n.code,{children:"Hint: <text>"}),".\nWhether this throws\nimmediately or records the failure and continues (a soft assertion) is decided by the\ncaller's ",(0,l.jsx)(n.code,{children:"-ErrorAction"})," or the ",(0,l.jsx)(n.code,{children:"Should.ErrorAction"})," configuration, exactly like the\nbuilt-in assertions."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"Hint()"})," returns the diagnostic input hint (or ",(0,l.jsx)(n.code,{children:"$null"}),"), for assertions that need to\ninspect it before deciding how to fail."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"Format(value)"})," formats a value the same way Pester does in assertion messages."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"EnsureScalar(expected)"})," returns ",(0,l.jsx)(n.code,{children:"expected"})," unchanged, or throws when it is a collection,\nguarding assertions that only make sense against a single value."]}),"\n",(0,l.jsxs)(n.li,{children:[(0,l.jsx)(n.code,{children:"IsCollection(value)"})," returns whether a value is treated as a collection."]}),"\n"]}
1),"\n",(0,l.jsxs)(n.p,{children:["A passing result is implicit: an assertion passes simply by returning without calling ",(0,l.jsx)(n.code,{children:"Fail()"}),".\nThere is nothing to call at the end, and custom assertions still work inside a mock\n",(0,l.jsx)(n.code,{children:"-ParameterFilter"})," automatically."]}),"\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:"function Should-BeAwesome {\n [CmdletBinding()]\n param (\n [Parameter(ValueFromPipeline)] $Actual,\n [Parameter(Position = 0)] $Expected = 'Awesome',\n [string] $Because\n )\n end {\n $assert = New-ShouldAssertion -Caller $PSCmdlet -Actual $Actual -Buffer $Input\n $Actual = $assert.Actual()\n\n if ($Actual -ne $Expected) {\n $assert.Fail(\n 'Expected <expected>,<because> but got <actual>.',\n @{ Expected = $Expected; Because = $Because })\n }\n }\n}\n\n'lame' | Should-BeAwesome\n"})}),"\n",(0,l.jsxs)(n.p,{children:["Defines and uses a custom assertion.\nBecause it goes through the shared failure path, it\nsupports ",(0,l.jsx)(n.code,{children:"-Because"}),", soft assertions via ",(0,l.jsx)(n.code,{children:"-ErrorAction"}),", and mock parameter filters for free."]}),"\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:"# A shared helper backing several of your own assertions. Thread the calling assertion's own\n# $PSCmdlet and $Input into New-ShouldAssertion so pipeline detection, the input hint and the\n# soft/hard -ErrorAction decision all resolve against the real assertion -- no matter how many\n# wrapper layers sit in between.\nfunction Invoke-MyEquals {\n param ([System.Management.Automation.PSCmdlet] $Cmdlet, $Actual, $Buffer, $Expected)\n\n$assert = New-ShouldAssertion -Caller $Cmdlet -Actual $Actual -Buffer $Buffer\n $value = $assert.Actual()\n if ($value -ne $Expected) {\n $assert.Fail('Expected <expected> but got <actual>.', @{ Expected = $Expected })\n }\n}\n\nfunction Should-Equal {\n [CmdletBinding()]\n param ([Parameter(ValueFromPipeline)] $Actual, [Parameter(Position = 0)] $Expected)\n end { Invoke-MyEquals -Cmdlet $PSCmdlet -Actual $Actual -Buffer $Input -Expected $Expected }\n}\n"})}),"\n",(0,l.jsxs)(n.p,{children:["Factors common assertion logic into one helper reused by several ",(0,l.jsx)(n.code,{children:"Should-*"})," assertions.\nNothing\nkeys off the assertion's ",(0,l.jsx)(n.em,{children:"name"}),", so the helper does not need to know which assertion called it;\neverything keys off the single ",(0,l.jsx)(n.code,{children:"$PSCmdlet"})," you pass as ",(0,l.jsx)(n.code,{children:"-Caller"}),".\nPassing the user-facing\nassertion's ",(0,l.jsx)(n.code,{children:"$PSCmdlet"})," and ",(0,l.jsx)(n.code,{children:"$Input"})," down keeps the input hint, pipeline detection and\n",(0,l.jsx)(n.code,{children:"-ErrorAction"})," behaviour identical to an unwrapped assertion, at any wrapping depth."]}),"\n",(0,l.jsx)(n.h2,{id:"parameters",children:"PARAMETERS"}),"\n",(0,l.jsx)(n.h3,{id:"-actual",children:"-Actual"}),"\n",(0,l.jsxs)(n.p,{children:["The assertion's ",(0,l.jsx)(n.code,{children:"-Actual"})," value.\nPass it even when the value usually arrives from the\npipeline; it is ",(0,l.jsx)(n.code,{children:"$null"})," in that case and the pipeline ",(0,l.jsx)(n.code,{children:"$Input"})," is used instead."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.Object\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:"-as",children:"-As"}),"\n",(0,l.jsxs)(n.p,{children:["How the input is collected: ",(0,l.jsx)(n.code,{children:"Scalar"})," (default) and ",(0,l.jsx)(n.code,{children:"ExactType"})," unroll a single piped value,\n",(0,l.jsx)(n.code,{children:"Collection"})," and ",(0,l.jsx)(n.code,{children:"CollectionItems"})," keep it as a collection.\nThe value also selects the\nwording of the diagnostic hint shown when the assertion fails; use ",(0,l.jsx)(n.code,{children:"None"})," for an assertion\nthat compares the whole input structurally (like ",(0,l.jsx)(n.code,{children:"Should-BeEquivalent"}),") and so has no\ninput-shape gotcha to hint about."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.String\nDefaultValue: Scalar\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- N
1ame: (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:"-buffer",children:"-Buffer"}),"\n",(0,l.jsxs)(n.p,{children:["The assertion function's ",(0,l.jsx)(n.code,{children:"$Input"}),".\nHolds the values received from the pipeline.\nPass\n",(0,l.jsx)(n.code,{children:"$Input"})," even when the assertion is usually called with ",(0,l.jsx)(n.code,{children:"-Actual"}),"; it is empty in that case."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.Object[]\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:"-caller",children:"-Caller"}),"\n",(0,l.jsxs)(n.p,{children:["The ",(0,l.jsx)(n.code,{children:"$PSCmdlet"})," of the assertion function.\nUsed to reach the caller's session state (so\nsoft assertions and the mock parameter filter behave correctly) and to recover the\noriginal pipeline input for hints."]}),"\n",(0,l.jsx)(n.pre,{children:(0,l.jsx)(n.code,{className:"language-yaml",children:"Type: System.Management.Automation.PSCmdlet\nDefaultValue: ''\nSupportsWildcards: false\nAliases: []\nParameterSets:\n- Name: (All)\n Position: 0\n IsRequired: true\n ValueFromPipeline: false\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.h2,{id:"outputs",children:"OUTPUTS"}),"\n",(0,l.jsx)(n.h3,{id:"shouldassertion",children:"ShouldAssertion"}),"\n",(0,l.jsx)(n.h2,{id:"notes",children:"NOTES"}),"\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/New-ShouldAssertion",children:"https://pester.dev/docs/commands/New-ShouldAssertion"})}),"\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",(0,l.jsx)(n.li,{children:(0,l.jsx)(n.a,{href:"https://pester.dev/docs/commands/Should-Be",children:"https://pester.dev/docs/commands/Should-Be"})}),"\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/pester",children:"Pester 6.1.0"}),"."]})})]})}function h(e={}){let{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,l.jsx)(n,{...e,children:(0,l.jsx)(c,{...e})}):c(e)}},7008(e,n,s){s.d(n,{R:()=>a,x:()=>r});var t=s(1763);let l={},i=t.createContext(l);function a(e){let n=t.useContext(i);return t.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function r(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(l):e.components||l:a(e.components),t.createElement(i.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.