Fix module import performance regression (#2336)

Author: fflaten

src/Main.ps1

@@ -119,6 +119,43 @@ function Add-ShouldOperator {
     Add-AssertionDynamicParameterSet -AssertionEntry $entry
 }
 
+function Set-ShouldOperatorHelpMessage {
+    <#
+    .SYNOPSIS
+    Sets the helpmessage for a Should-operator. Used in Should's online help for the switch-parameter.
+    .PARAMETER OperatorName
+    The name of the assertion/operator.
+    .PARAMETER HelpMessage
+    Help message for switch-parameter for the operator in Should.
+    .NOTES
+    Internal function as it's only useful for built-in Should operators/assertion atm. to improve online docs.
+    Can be merged into Add-ShouldOperator later if we'd like to make it pulic and include value in Get-ShouldOperator
+
+    https://github.com/pester/Pester/issues/2335
+    #>
+    [CmdletBinding()]
+    param (
+        [Parameter(Mandatory = $true, Position = 0)]
+        [string] $OperatorName,
+        [Parameter(Mandatory = $true, Position = 1)]
+        [string] $HelpMessage
+    )
+
+    end {
+        $OperatorParam = $script:AssertionDynamicParams[$OperatorName]
+
+        if ($null -eq $OperatorParam) {
+            throw "Should operator '$OperatorName' is not registered"
+        }
+
+        foreach ($attr in $OperatorParam.Attributes) {
+            if ($attr -is [System.Management.Automation.ParameterAttribute]) {
+                $attr.HelpMessage = $HelpMessage
+            }
+        }
+    }
+}
+
 function Test-AssertionOperatorIsDuplicate {
     param (
         [psobject] $Operator
@@ -163,12 +200,6 @@ function Add-AssertionDynamicParameterSet {
     $attribute = & $SafeCommands['New-Object'] Management.Automation.ParameterAttribute
     $attribute.ParameterSetName = $AssertionEntry.Name
 
-    # Add synopsis as HelpMessage to show in online help for Should parameters.
-    $assertHelp = $commandInfo | & $SafeCommands['Get-Help']
-    # Ignore functions without synopsis defined (they show syntax)
-    if ($assertHelp.Synopsis -notmatch '^\s*__AssertionTest__((\s+\[+?-\w+)|$)') {
-        $attribute.HelpMessage = $assertHelp.Synopsis
-    }
 
     $attributeCollection = & $SafeCommands['New-Object'] Collections.ObjectModel.Collection[Attribute]
     $null = $attributeCollection.Add($attribute)
@@ -241,7 +272,8 @@ function Add-AssertionDynamicParameterSet {
         $attribute.ParameterSetName = $AssertionEntry.Name
         $attribute.Mandatory = $false
         $attribute.Position = ($i++)
-        $attribute.HelpMessage = 'Depends on operator being used. See `Get-ShouldOperator -Name <Operator>` for help.'
+        # Only visible in command reference on https://pester.dev. Remove if/when migrated to external help (markdown as source).
+        $attribute.HelpMessage = 'Depends on operator being used. See `Get-ShouldOperator -Name <Operator>` or https://pester.dev/docs/assertions/ for help.'
 
         $null = $dynamic.Attributes.Add($attribute)
     }

src/functions/Pester.SessionState.Mock.ps1

@@ -669,6 +669,9 @@ function Should-InvokeVerifiable ([switch] $Negate, [string] $Because) {
     -InternalName Should-InvokeVerifiable `
     -Test         ${function:Should-InvokeVerifiable}
 
+Set-ShouldOperatorHelpMessage -OperatorName InvokeVerifiable `
+    -HelpMessage 'Checks if any Verifiable Mock has not been invoked. If so, this will throw an exception.'
+
 function Assert-MockCalled {
     <#
     .SYNOPSIS
@@ -1034,6 +1037,9 @@ function Should-Invoke {
     -InternalName Should-Invoke `
     -Test         ${function:Should-Invoke}
 
+Set-ShouldOperatorHelpMessage -OperatorName Invoke `
+    -HelpMessage 'Checks if a Mocked command has been called a certain number of times and throws an exception if it has not.'
+
 function Invoke-Mock {
     [CmdletBinding()]
     param (

src/functions/assertions/Be.ps1

@@ -63,12 +63,15 @@ function NotShouldBeFailureMessage($ActualValue, $ExpectedValue, $Because) {
     return "Expected $(Format-Nicely $ExpectedValue) to be different from the actual value,$(if ($null -ne $Because) { Format-Because $Because }) but got the same value."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name               Be `
+& $script:SafeCommands['Add-ShouldOperator'] -Name Be `
     -InternalName       Should-Be `
     -Test               ${function:Should-Be} `
     -Alias              'EQ' `
     -SupportsArrayInput
 
+Set-ShouldOperatorHelpMessage -OperatorName Be `
+    -HelpMessage 'Compares one object with another for equality and throws if the two objects are not the same.'
+
 #BeExactly
 function Should-BeExactly($ActualValue, $ExpectedValue, $Because) {
     <#
@@ -133,12 +136,14 @@ function NotShouldBeExactlyFailureMessage($ActualValue, $ExpectedValue, $Because
     return "Expected $(Format-Nicely $ExpectedValue) to be different from the actual value,$(if ($null -ne $Because) { Format-Because $Because }) but got exactly the same value."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name               BeExactly `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeExactly `
     -InternalName       Should-BeExactly `
     -Test               ${function:Should-BeExactly} `
     -Alias              'CEQ' `
     -SupportsArrayInput
 
+Set-ShouldOperatorHelpMessage -OperatorName BeExactly `
+    -HelpMessage 'Compares one object with another for equality and throws if the two objects are not the same. This comparison is case sensitive.'
 
 #common functions
 function Get-CompareStringMessage {

src/functions/assertions/BeGreaterThan.ps1

@@ -58,16 +58,22 @@ function Should-BeLessOrEqual($ActualValue, $ExpectedValue, [switch] $Negate, [s
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeGreaterThan `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeGreaterThan `
     -InternalName Should-BeGreaterThan `
     -Test         ${function:Should-BeGreaterThan} `
     -Alias        'GT'
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeLessOrEqual `
+Set-ShouldOperatorHelpMessage -OperatorName BeGreaterThan `
+    -HelpMessage "Asserts that a number (or other comparable value) is greater than an expected value. Uses PowerShell's -gt operator to compare the two values."
+
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeLessOrEqual `
     -InternalName Should-BeLessOrEqual `
     -Test         ${function:Should-BeLessOrEqual} `
     -Alias        'LE'
 
+Set-ShouldOperatorHelpMessage -OperatorName BeLessOrEqual `
+    -HelpMessage "Asserts that a number (or other comparable value) is lower than, or equal to an expected value. Uses PowerShell's -le operator to compare the two values."
+
 #keeping tests happy
 function ShouldBeGreaterThanFailureMessage() {
 }

src/functions/assertions/BeIn.ps1

@@ -34,10 +34,12 @@
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeIn `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeIn `
     -InternalName Should-BeIn `
     -Test         ${function:Should-BeIn}
 
+Set-ShouldOperatorHelpMessage -OperatorName BeIn `
+    -HelpMessage "Asserts that a collection of values contain a specific value. Uses PowerShell's -contains operator to confirm."
 
 function ShouldBeInFailureMessage() {
 }

src/functions/assertions/BeLessThan.ps1

@@ -58,16 +58,22 @@ function Should-BeGreaterOrEqual($ActualValue, $ExpectedValue, [switch] $Negate,
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeLessThan `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeLessThan `
     -InternalName Should-BeLessThan `
     -Test         ${function:Should-BeLessThan} `
     -Alias        'LT'
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeGreaterOrEqual `
+Set-ShouldOperatorHelpMessage -OperatorName BeLessThan `
+    -HelpMessage "Asserts that a number (or other comparable value) is lower than an expected value. Uses PowerShell's -lt operator to compare the two values."
+
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeGreaterOrEqual `
     -InternalName Should-BeGreaterOrEqual `
     -Test         ${function:Should-BeGreaterOrEqual} `
     -Alias        'GE'
 
+Set-ShouldOperatorHelpMessage -OperatorName BeGreaterOrEqual `
+    -HelpMessage "Asserts that a number (or other comparable value) is greater than or equal to an expected value. Uses PowerShell's -ge operator to compare the two values."
+
 #keeping tests happy
 function ShouldBeLessThanFailureMessage() {
 }

src/functions/assertions/BeLike.ps1

@@ -42,10 +42,13 @@
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeLike `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeLike `
     -InternalName Should-BeLike `
     -Test         ${function:Should-BeLike}
 
+Set-ShouldOperatorHelpMessage -OperatorName BeLike `
+    -HelpMessage "Asserts that the actual value matches a wildcard pattern using PowerShell's -like operator. This comparison is not case-sensitive."
+
 function ShouldBeLikeFailureMessage() {
 }
 function NotShouldBeLikeFailureMessage() {

src/functions/assertions/BeLikeExactly.ps1

@@ -41,10 +41,13 @@
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeLikeExactly `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeLikeExactly `
     -InternalName Should-BeLikeExactly `
     -Test         ${function:Should-BeLikeExactly}
 
+Set-ShouldOperatorHelpMessage -OperatorName BeLikeExactly `
+    -HelpMessage "Asserts that the actual value matches a wildcard pattern using PowerShell's -like operator. This comparison is case-sensitive."
+
 function ShouldBeLikeExactlyFailureMessage() {
 }
 function NotShouldBeLikeExactlyFailureMessage() {

src/functions/assertions/BeNullOrEmpty.ps1

@@ -72,7 +72,10 @@ function NotShouldBeNullOrEmptyFailureMessage ($Because) {
     return "Expected a value,$(Format-Because $Because) but got `$null or empty."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name               BeNullOrEmpty `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeNullOrEmpty `
     -InternalName       Should-BeNullOrEmpty `
     -Test               ${function:Should-BeNullOrEmpty} `
     -SupportsArrayInput
+
+Set-ShouldOperatorHelpMessage -OperatorName BeNullOrEmpty `
+    -HelpMessage "Checks values for null or empty (strings). The static [String]::IsNullOrEmpty() method is used to do the comparison."

src/functions/assertions/BeOfType.ps1

@@ -67,11 +67,14 @@ function Should-BeOfType($ActualValue, $ExpectedType, [switch] $Negate, [string]
 }
 
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeOfType `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeOfType `
     -InternalName Should-BeOfType `
     -Test         ${function:Should-BeOfType} `
     -Alias        'HaveType'
 
+Set-ShouldOperatorHelpMessage -OperatorName BeOfType `
+    -HelpMessage "Asserts that the actual value should be an object of a specified type (or a subclass of the specified type) using PowerShell's -is operator."
+
 function ShouldBeOfTypeFailureMessage() {
 }