Add Should-HaveParameter (#2621)

* Add Should-HaveParameter

* Help

* Fix

Author: nohwnd

src/Module.ps1

@@ -92,6 +92,9 @@ $script:SafeCommands['Set-DynamicParameterVariable'] = $ExecutionContext.Session
     'Should-BeBefore'
     'Should-BeAfter'
 
+    'Should-HaveParameter'
+    'Should-NotHaveParameter'
+
     # export
     'Export-NUnitReport'
     'ConvertTo-NUnitReport'

src/Pester.psd1

@@ -114,6 +114,9 @@
         'Should-BeBefore'
         'Should-BeAfter'
 
+        'Should-HaveParameter'
+        'Should-NotHaveParameter'
+
         # helpers
         'New-MockObject'
         'New-Fixture'

src/functions/assert/Parameter/Should-HaveParameter.ps1

@@ -0,0 +1,77 @@
+function Should-HaveParameter {
+    <#
+    .SYNOPSIS
+    Asserts that a command has the expected parameter.
+
+    .PARAMETER ParameterName
+    The name of the parameter to check. E.g. Uri
+
+    .PARAMETER Type
+    The type of the parameter to check. E.g. [string]
+
+    .PARAMETER DefaultValue
+    The default value of the parameter to check. E.g. "https://example.com"
+
+    .PARAMETER Mandatory
+    Whether the parameter is mandatory or not.
+
+    .PARAMETER InParameterSet
+    The parameter set that the parameter belongs to.
+
+    .PARAMETER HasArgumentCompleter
+    Whether the parameter has an argument completer or not.
+
+    .PARAMETER Alias
+    The alias of the parameter to check.
+
+    .PARAMETER Actual
+    The actual command to check. E.g. Get-Command "Invoke-WebRequest"
+
+    .PARAMETER Because
+    The reason why the input should be the expected value.
+
+    .EXAMPLE
+    ```powershell
+    Get-Command "Invoke-WebRequest" | Should -HaveParameter Uri -Mandatory
+    ```
+
+    This test passes, because it expected the parameter URI to exist and to
+    be mandatory.
+
+
+    .NOTES
+    The attribute [ArgumentCompleter] was added with PSv5. Previously this
+    assertion will not be able to use the -HasArgumentCompleter parameter
+    if the attribute does not exist.
+
+    .LINK
+    https://pester.dev/docs/commands/Should-HaveParameter
+
+    .LINK
+    https://pester.dev/docs/assertions
+    #>
+
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseProcessBlockForPipelineCommand', '')]
+    param(
+        [String] $ParameterName,
+        $Type,
+        [String] $DefaultValue,
+        [Switch] $Mandatory,
+        [String] $InParameterSet,
+        [Switch] $HasArgumentCompleter,
+        [String[]] $Alias,
+        [Parameter(ValueFromPipeline = $true)]
+        $Actual,
+        [String] $Because
+    )
+
+    $collectedInput = Collect-Input -ParameterInput $Actual -PipelineInput $local:Input -IsPipelineInput $MyInvocation.ExpectingInput -UnrollInput
+    $Actual = $collectedInput.Actual
+
+    $PSBoundParameters["ActualValue"] = $Actual
+    $PSBoundParameters.Remove("Actual")
+
+    $testResult = Should-HaveParameterAssertion @PSBoundParameters
+
+    Test-AssertionResult $testResult
+}

src/functions/assert/Parameter/Should-NotHaveParameter.ps1

@@ -0,0 +1,53 @@
+function Should-NotHaveParameter {
+    <#
+    .SYNOPSIS
+    Asserts that a command has does not have the parameter.
+
+    .PARAMETER ParameterName
+    The name of the parameter to check. E.g. Uri
+
+    .PARAMETER Actual
+    The actual command to check. E.g. Get-Command "Invoke-WebRequest"
+
+    .PARAMETER Because
+    The reason why the input should be the expected value.
+
+    .EXAMPLE
+    ```powershell
+    Get-Command "Invoke-WebRequest" | Should -NotHaveParameter Uri
+    ```
+
+    This test fails, because it expected the parameter URI to not exist.
+
+    .NOTES
+    The attribute [ArgumentCompleter] was added with PSv5. Previously this
+    assertion will not be able to use the -HasArgumentCompleter parameter
+    if the attribute does not exist.
+
+    .LINK
+    https://pester.dev/docs/commands/Should-NotHaveParameter
+
+    .LINK
+    https://pester.dev/docs/assertions
+    #>
+
+
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseProcessBlockForPipelineCommand', '')]
+    param(
+        [String] $ParameterName,
+        [Parameter(ValueFromPipeline = $true)]
+        $Actual,
+        [String] $Because
+    )
+
+    $collectedInput = Collect-Input -ParameterInput $Actual -PipelineInput $local:Input -IsPipelineInput $MyInvocation.ExpectingInput -UnrollInput
+    $Actual = $collectedInput.Actual
+
+    $PSBoundParameters["ActualValue"] = $Actual
+    $PSBoundParameters.Remove("Actual")
+    $PSBoundParameters["Negate"] = $true
+
+    $testResult = Should-HaveParameterAssertion @PSBoundParameters
+
+    Test-AssertionResult $testResult
+}

tst/functions/assert/Parameter/Should-HaveParameter.Tests.ps1

@@ -0,0 +1,15 @@
+Set-StrictMode -Version Latest
+
+Describe "Should-HaveParameter" {
+    It "Passes when function has a parameter" {
+        function f ($a) { }
+
+        Get-Command f | Should-HaveParameter a
+    }
+
+    It "Fails when function does not have a parameter" {
+        function f () { }
+
+        { Get-Command f | Should-HaveParameter a } | Verify-Throw
+    }
+}

tst/functions/assert/Parameter/Should-NotHaveParameter.Tests.ps1

@@ -0,0 +1,15 @@
+Set-StrictMode -Version Latest
+
+Describe "Should-HaveParameter" {
+    It "Passes when function does not have a parameter" {
+        function f () { }
+
+        Get-Command f | Should-NotHaveParameter a
+    }
+
+    It "Fails when function has a parameter" {
+        function f ($a) { }
+
+        { Get-Command f | Should-NotHaveParameter a } | Verify-Throw
+    }
+}