Mock fallthrough

Author: nohwnd

src/functions/Mock.ps1

@@ -348,7 +348,7 @@ function Should-InvokeVerifiableInternal {
     }
 
     return [Pester.ShouldResult] @{
-        Succeeded      = $true
+        Succeeded = $true
     }
 }
 
@@ -460,7 +460,9 @@ function Should-InvokeInternal {
         #     $params.ScriptBlock = New-BlockWithoutParameterAliases -Metadata $ContextInfo.Hook.Metadata -Block $params.ScriptBlock
         # }
 
-        if (Test-ParameterFilter @params) {
+        $filterResult = Test-ParameterFilter @params
+        $passed = $filterResult[0]
+        if ($passed) {
             $null = $matchingCalls.Add($historyEntry)
         }
         else {
@@ -530,7 +532,7 @@ function Should-InvokeInternal {
     }
 
     return [Pester.ShouldResult] @{
-        Succeeded      = $true
+        Succeeded = $true
     }
 }
 
@@ -798,7 +800,8 @@ function Invoke-MockInternal {
     switch ($FromBlock) {
         Begin {
             $MockCallState['InputObjects'] = [System.Collections.Generic.List[object]]@()
-            $MockCallState['ShouldExecuteOriginalCommand'] = $false
+            $MockCallState['MatchedNoBehavior'] = $false
+            $MockCallState['NoBehaviors'] = $false
             $MockCallState['BeginBoundParameters'] = $BoundParameters.Clone()
             # argument list must not be null, if the bootstrap functions has no parameters
             # we get null and need to replace it with empty array to make the splatting work
@@ -815,8 +818,21 @@ function Invoke-MockInternal {
             # test caller scope here, but the scope from which the mock was called
             $SessionState = if ($CallerSessionState) { $CallerSessionState } else { $Hook.SessionState }
 
+            # When this bootstrap function runs but no behaviors are visible (e.g. a nested
+            # Invoke-Pester run inherits the outer mock's bootstrap function but not its
+            # behaviors), there is nothing to throw about - fall through to the original
+            # command so the unrelated nested call still works.
+            if (0 -eq @($Behaviors).Count) {
+                $MockCallState['NoBehaviors'] = $true
+                if ($null -ne $InputObject) {
+                    $null = $MockCallState['InputObjects'].AddRange(@($InputObject))
+                }
+
+                return
+            }
+
             # the @() are needed for powerShell3 otherwise it throws CheckAutomationNullInCommandArgumentArray (unless there is any breakpoint defined anywhere, then it works just fine :DDD)
-            $behavior = FindMatchingBehavior -Behaviors @($Behaviors) -BoundParameters $BoundParameters -ArgumentList @($ArgumentList) -SessionState $SessionState -Hook $Hook
+            $behavior, $failedFilterInvocations = FindMatchingBehavior -Behaviors @($Behaviors) -BoundParameters $BoundParameters -ArgumentList @($ArgumentList) -SessionState $SessionState -Hook $Hook
 
             if ($null -ne $behavior) {
                 $call = @{
@@ -841,7 +857,8 @@ function Invoke-MockInternal {
                 return
             }
             else {
-                $MockCallState['ShouldExecuteOriginalCommand'] = $true
+                $MockCallState['MatchedNoBehavior'] = $true
+                $MockCallState['FailedFilterInvocations'] = $failedFilterInvocations
                 if ($null -ne $InputObject) {
                     $null = $MockCallState['InputObjects'].AddRange(@($InputObject))
                 }
@@ -851,9 +868,12 @@ function Invoke-MockInternal {
         }
 
         End {
-            if ($MockCallState['ShouldExecuteOriginalCommand']) {
+            if ($MockCallState['NoBehaviors']) {
+                # No behaviors are defined in the current scope at all - this means the
+                # bootstrap function leaked from a parent scope (e.g. nested Invoke-Pester).
+                # Invoke the original command transparently so the unrelated caller still works.
                 if ($PesterPreference.Debug.WriteDebugMessages.Value) {
-                    Write-PesterDebugMessage -Scope Mock "Invoking the original command."
+                    Write-PesterDebugMessage -Scope Mock "No behaviors are visible in this scope, invoking the original command."
                 }
 
                 $MockCallState['BeginBoundParameters'] = Reset-ConflictingParameters -BoundParameters $MockCallState['BeginBoundParameters']
@@ -871,49 +891,32 @@ function Invoke-MockInternal {
                     }
                 }
 
-                $SessionState = if ($CallerSessionState) {
-                    $CallerSessionState
-                }
-                else {
-                    $Hook.SessionState
-                }
-
+                $SessionState = if ($CallerSessionState) { $CallerSessionState } else { $Hook.SessionState }
                 Set-ScriptBlockScope -ScriptBlock $scriptBlock -SessionState $SessionState
 
-                # In order to mock Set-Variable correctly we need to write the variable
-                # two scopes above
-                if ("Set-Variable" -eq $Hook.OriginalCommand.Name) {
-                    if ($PesterPreference.Debug.WriteDebugMessages.Value) {
-                        Write-PesterDebugMessage -Scope Mock "Original command is Set-Variable, patching the call."
-                    }
-                    if ($MockCallState['BeginBoundParameters'].Keys -notcontains "Scope") {
-                        $MockCallState['BeginBoundParameters'].Add( "Scope", 2)
-                    }
-                    # local is the same as scope 0, in that case we also write to scope 2
-                    elseif ("Local", "0" -contains $MockCallState['BeginBoundParameters'].Scope) {
-                        $MockCallState['BeginBoundParameters'].Scope = 2
-                    }
-                    elseif ($MockCallState['BeginBoundParameters'].Scope -match "\d+") {
-                        $MockCallState['BeginBoundParameters'].Scope = 2 + $matches[0]
-                    }
-                    else {
-                        # not sure what the user did, but we won't change it
-                    }
-                }
-
                 if ($null -eq ($MockCallState['BeginArgumentList'])) {
                     $arguments = @()
                 }
                 else {
                     $arguments = $MockCallState['BeginArgumentList']
                 }
-                if ($PesterPreference.Debug.WriteDebugMessages.Value) {
-                    Write-ScriptBlockInvocationHint -Hint "Mock - Original Command" -ScriptBlock $scriptBlock
-                }
                 & $scriptBlock -Command $Hook.OriginalCommand `
                     -ArgumentList $arguments `
                     -BoundParameters $MockCallState['BeginBoundParameters'] `
                     -InputObjects $MockCallState['InputObjects']
+
+                return
+            }
+
+            if ($MockCallState['MatchedNoBehavior']) {
+                if ($PesterPreference.Debug.WriteDebugMessages.Value) {
+                    Write-PesterDebugMessage -Scope Mock "The mock did not match any filtered behavior, and there was no default behavior. Failing."
+                }
+
+                $failedFilterInvocations = $MockCallState['FailedFilterInvocations']
+                $filterList = ($failedFilterInvocations | ForEach-Object { "    $_" }) -join [System.Environment]::NewLine
+
+                throw "No mock for command '$($Hook.CommandName)' matched the call: none of the parameter filters matched, and there is no default mock to fall back to. Add a default mock (e.g. ``Mock $($Hook.CommandName) { ... }``) or adjust an existing -ParameterFilter.$([System.Environment]::NewLine)$([System.Environment]::NewLine)The following parameter filters were evaluated and did not match:$([System.Environment]::NewLine)$filterList"
             }
         }
     }
@@ -980,6 +983,7 @@ function FindMatchingBehavior {
         Write-PesterDebugMessage -Scope Mock "Finding behavior to use, one that passes filter or a default:"
     }
 
+    $failedFilterInvocations = [System.Collections.Generic.List[String]]@()
     $foundDefaultBehavior = $false
     $defaultBehavior = $null
     foreach ($b in $Behaviors) {
@@ -999,11 +1003,17 @@ function FindMatchingBehavior {
                 SessionState    = $Hook.CallerSessionState
             }
 
-            if (Test-ParameterFilter @params) {
+            $filterResult = Test-ParameterFilter @params
+            $passed = $filterResult[0]
+            $filterInvocations = $filterResult[1]
+            if ($passed) {
                 if ($PesterPreference.Debug.WriteDebugMessages.Value) {
                     Write-PesterDebugMessage -Scope Mock "{ $($b.ScriptBlock) } passed parameter filter and will be used for the mock call."
                 }
-                return $b
+                return $b, $null
+            }
+            else {
+                $failedFilterInvocations.AddRange($filterInvocations)
             }
         }
     }
@@ -1012,13 +1022,13 @@ function FindMatchingBehavior {
         if ($PesterPreference.Debug.WriteDebugMessages.Value) {
             Write-PesterDebugMessage -Scope Mock "{ $($defaultBehavior.ScriptBlock) } is a default behavior and will be used for the mock call."
         }
-        return $defaultBehavior
+        return $defaultBehavior, $null
     }
 
     if ($PesterPreference.Debug.WriteDebugMessages.Value) {
-        Write-PesterDebugMessage -Scope Mock "No parametrized or default behaviors were found filter."
+        Write-PesterDebugMessage -Scope Mock "No parametrized or default behaviors were found."
     }
-    return $null
+    return $null, $failedFilterInvocations
 }
 
 function LastThat {
@@ -1241,8 +1251,11 @@ function Test-ParameterFilter {
         else { $null }
     }
 
+    $parameterFilterInvocations = [Collections.Generic.List[string]]@()
+
     $result = & $wrapper $parameters
-    if ($result) {
+    $passed = [bool]$result
+    if ($passed) {
         if ($PesterPreference.Debug.WriteDebugMessages.Value) {
             Write-PesterDebugMessage -Scope Mock -Message "Mock filter returned value '$result', which is truthy. Filter passed."
         }
@@ -1251,8 +1264,21 @@ function Test-ParameterFilter {
         if ($PesterPreference.Debug.WriteDebugMessages.Value) {
             Write-PesterDebugMessage -Scope Mock -Message "Mock filter returned value '$result', which is falsy. Filter did not pass."
         }
+
+        # Filter did not pass, serialize the values and store them for future reference in case we don't find any behavior.
+        $filterText = $scriptBlock.ToString().Trim()
+        $hasContext = 0 -lt $Context.Count
+        $contextText = if ($hasContext) {
+            'bound parameters: ' + (($Context.GetEnumerator() | ForEach-Object { "$($_.Key) = $($_.Value)" }) -join ', ')
+        }
+        else {
+            'no bound parameters'
+        }
+        $filterCall = "{ $filterText }  $contextText"
+        $parameterFilterInvocations.Add($filterCall)
     }
-    $result
+    # Return as a single 2-element array so multi-assignment works even when $result is empty/$null/array.
+    , @($passed, $parameterFilterInvocations)
 }
 
 function Get-ContextToDefine {

src/functions/Pester.SessionState.Mock.ps1

@@ -1001,9 +1001,9 @@ function Invoke-Mock {
     )
 
     if ('End' -eq $FromBlock) {
-        if (-not $MockCallState.ShouldExecuteOriginalCommand) {
+        if (-not $MockCallState.MatchedNoBehavior) {
             if ($PesterPreference.Debug.WriteDebugMessages.Value) {
-                Write-PesterDebugMessage -Scope MockCore "Mock for $CommandName was invoked from block $FromBlock, and should not execute the original command, returning."
+                Write-PesterDebugMessage -Scope MockCore "Mock for $CommandName was invoked from block $FromBlock, and matched at least one behavior, returning."
             }
             return
         }