Fix module import performance regression (#2336)

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() {
 }
 

src/functions/assertions/BeTrueOrFalse.ps1

@@ -75,15 +75,19 @@ function Should-BeFalse($ActualValue, [switch] $Negate, $Because) {
 }
 
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeTrue `
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeTrue `
     -InternalName Should-BeTrue `
     -Test         ${function:Should-BeTrue}
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         BeFalse `
+Set-ShouldOperatorHelpMessage -OperatorName BeTrue `
+    -HelpMessage "Asserts that the value is true, or truthy."
+
+& $script:SafeCommands['Add-ShouldOperator'] -Name BeFalse `
     -InternalName Should-BeFalse `
     -Test         ${function:Should-BeFalse}
 
-
+Set-ShouldOperatorHelpMessage -OperatorName BeFalse `
+    -HelpMessage "Asserts that the value is false, or falsy."
 
 # to keep tests happy
 function ShouldBeTrueFailureMessage($ActualValue) {

src/functions/assertions/Contain.ps1

@@ -34,11 +34,14 @@
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         Contain `
+& $script:SafeCommands['Add-ShouldOperator'] -Name Contain `
     -InternalName Should-Contain `
     -Test         ${function:Should-Contain} `
     -SupportsArrayInput
 
+Set-ShouldOperatorHelpMessage -OperatorName Contain `
+    -HelpMessage "Asserts that collection contains a specific value. Uses PowerShell's -contains operator to confirm."
+
 function ShouldContainFailureMessage() {
 }
 function NotShouldContainFailureMessage() {

src/functions/assertions/Exist.ps1

@@ -35,10 +35,12 @@
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         Exist `
+& $script:SafeCommands['Add-ShouldOperator'] -Name Exist `
     -InternalName Should-Exist `
     -Test         ${function:Should-Exist}
 
+Set-ShouldOperatorHelpMessage -OperatorName Exist `
+    -HelpMessage "Does not perform any comparison, but checks if the object calling Exist is present in a PS Provider. The object must have valid path syntax. It essentially must pass a Test-Path call."
 
 function ShouldExistFailureMessage() {
 }

src/functions/assertions/FileContentMatch.ps1

@@ -65,6 +65,9 @@ function NotShouldFileContentMatchFailureMessage($ActualValue, $ExpectedContent,
     return "Expected $(Format-Nicely $ExpectedContent) to not be found in file '$ActualValue',$(Format-Because $Because) but it was found."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         FileContentMatch `
+& $script:SafeCommands['Add-ShouldOperator'] -Name FileContentMatch `
     -InternalName Should-FileContentMatch `
     -Test         ${function:Should-FileContentMatch}
+
+Set-ShouldOperatorHelpMessage -OperatorName FileContentMatch `
+    -HelpMessage 'Checks to see if a file contains the specified text. This search is not case sensitive and uses regular expressions.'

src/functions/assertions/FileContentMatchExactly.ps1

@@ -48,6 +48,9 @@ function NotShouldFileContentMatchExactlyFailureMessage($ActualValue, $ExpectedC
     return "Expected $(Format-Nicely $ExpectedContent) to not be case sensitively found in file $(Format-Nicely $ActualValue),$(Format-Because $Because) but it was found."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         FileContentMatchExactly `
+& $script:SafeCommands['Add-ShouldOperator'] -Name FileContentMatchExactly `
     -InternalName Should-FileContentMatchExactly `
     -Test         ${function:Should-FileContentMatchExactly}
+
+Set-ShouldOperatorHelpMessage -OperatorName FileContentMatchExactly `
+    -HelpMessage 'Checks to see if a file contains the specified text. This search is case sensitive and uses regular expressions to match the text.'

src/functions/assertions/FileContentMatchMultiline.ps1

@@ -57,6 +57,9 @@ function NotShouldFileContentMatchMultilineFailureMessage($ActualValue, $Expecte
     return "Expected $(Format-Nicely $ExpectedContent) to not be found in file $(Format-Nicely $ActualValue),$(Format-Because $Because) but it was found."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         FileContentMatchMultiline `
+& $script:SafeCommands['Add-ShouldOperator'] -Name FileContentMatchMultiline `
     -InternalName Should-FileContentMatchMultiline `
     -Test         ${function:Should-FileContentMatchMultiline}
+
+Set-ShouldOperatorHelpMessage -OperatorName FileContentMatchMultiline `
+    -HelpMessage 'As opposed to FileContentMatch and FileContentMatchExactly operators, FileContentMatchMultiline presents content of the file being tested as one string object, so that the expression you are comparing it to can consist of several lines.'

src/functions/assertions/FileContentMatchMultilineExactly.ps1

@@ -74,6 +74,9 @@ function NotShouldFileContentMatchMultilineExactlyFailureMessage($ActualValue, $
     return "Expected $(Format-Nicely $ExpectedContent) to not be case sensitively found in file $(Format-Nicely $ActualValue),$(Format-Because $Because) but it was found."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         FileContentMatchMultilineExactly `
+& $script:SafeCommands['Add-ShouldOperator'] -Name FileContentMatchMultilineExactly `
     -InternalName Should-FileContentMatchMultilineExactly `
     -Test         ${function:Should-FileContentMatchMultilineExactly}
+
+Set-ShouldOperatorHelpMessage -OperatorName FileContentMatchMultilineExactly `
+    -HelpMessage 'As opposed to FileContentMatch and FileContentMatchExactly operators, FileContentMatchMultilineExactly presents content of the file being tested as one string object, so that the case sensitive expression you are comparing it to can consist of several lines.'

src/functions/assertions/HaveCount.ps1

@@ -70,11 +70,14 @@
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         HaveCount `
+& $script:SafeCommands['Add-ShouldOperator'] -Name HaveCount `
     -InternalName Should-HaveCount `
     -Test         ${function:Should-HaveCount} `
     -SupportsArrayInput
 
+Set-ShouldOperatorHelpMessage -OperatorName HaveCount `
+    -HelpMessage 'Asserts that a collection has the expected amount of items.'
+
 function ShouldHaveCountFailureMessage() {
 }
 function NotShouldHaveCountFailureMessage() {

src/functions/assertions/HaveParameter.ps1

@@ -299,6 +299,9 @@
     }
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         HaveParameter `
+& $script:SafeCommands['Add-ShouldOperator'] -Name HaveParameter `
     -InternalName Should-HaveParameter `
     -Test         ${function:Should-HaveParameter}
+
+Set-ShouldOperatorHelpMessage -OperatorName HaveParameter `
+    -HelpMessage 'Asserts that a command has the expected parameter.'

src/functions/assertions/Match.ps1

@@ -54,6 +54,9 @@ function NotShouldMatchFailureMessage($ActualValue, $RegularExpression, $Because
     return "Expected regular expression $(Format-Nicely $RegularExpression) to not match $(Format-Nicely $ActualValue),$(Format-Because $Because) but it did match."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         Match `
+& $script:SafeCommands['Add-ShouldOperator'] -Name Match `
     -InternalName Should-Match `
     -Test         ${function:Should-Match}
+
+Set-ShouldOperatorHelpMessage -OperatorName Match `
+    -HelpMessage 'Uses a regular expression to compare two objects. This comparison is not case sensitive.'

src/functions/assertions/MatchExactly.ps1

@@ -47,7 +47,10 @@ function NotShouldMatchExactlyFailureMessage($ActualValue, $RegularExpression) {
     return "Expected regular expression $(Format-Nicely $RegularExpression) to not case sensitively match $(Format-Nicely $ActualValue),$(Format-Because $Because) but it did match."
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         MatchExactly `
+& $script:SafeCommands['Add-ShouldOperator'] -Name MatchExactly `
     -InternalName Should-MatchExactly `
     -Test         ${function:Should-MatchExactly} `
     -Alias        'CMATCH'
+
+Set-ShouldOperatorHelpMessage -OperatorName MatchExactly `
+    -HelpMessage 'Uses a regular expression to compare two objects. This comparison is case sensitive.'

src/functions/assertions/PesterThrow.ps1

@@ -181,6 +181,9 @@ function NotShouldThrowFailureMessage {
     # to make the should tests happy, for now
 }
 
-& $script:SafeCommands['Add-ShouldOperator'] -Name         Throw `
+& $script:SafeCommands['Add-ShouldOperator'] -Name Throw `
     -InternalName Should-Throw `
     -Test         ${function:Should-Throw}
+
+Set-ShouldOperatorHelpMessage -OperatorName Throw `
+    -HelpMessage 'Checks if an exception was thrown. Enclose input in a scriptblock.'