Mocking Invoke-RestMethod -StatusCodeVariable

[dkaszews]

I am using Invoke-RestMethod with -StatusCodeVariable to return the status code alongside data, to be processed further down. I can quite easily mock the return value, but have no idea how to mock setting the variable in caller's scope. I tried Set-Variable with different -Scope values, but it only works with maximum scope which is global all the way in terminal scope, messing with other stuff.

Repro example, the real DownloadStuff is defined in another module loaded into the test. I would prefer solutions which do not require modifying production code, so no wrapping Invoke-RestMethod into a helper and mocking that helper instead, or adding testing hooks which modify flow in UT.

BeforeAll {
    function DownloadStuff {
        $stuff = Invoke-RestMethod 'example.com/api/stuff' -SkipHttpErrorCheck -StatusCodeVariable scv
        @( $scv, $stuff )  # Throws RuntimeException: The variable '$scv' cannot be retrieved because it has not been set.
    }
}

Describe 'DownloadStuff' {
    Context 'Forbidden' {
        BeforeEach {
            Mock Invoke-RestMethod {
                Set-Variable -Scope 1 'scv' 401
                'no data'
            }
            $result = DownloadStuff
        }

        It 'Returns 401' {
            $result[0] | Should -Be 401
        }
    }
}

[fflaten]

This a great question! There's two versions of this answer: one for your sample and one for your production code.
Your sample should work when you find the right scope-level to use with Set-Variable. Example:

Describe 'DownloadStuff in same session state' {
    BeforeAll {
        function DownloadStuff {
            # $demoVar = 123
            $stuff = Invoke-RestMethod 'example.com/api/stuff' -SkipHttpErrorCheck -StatusCodeVariable scv
            @( $scv, $stuff )
        }
    }
    Context 'Forbidden' {
        BeforeEach {
            Mock Invoke-RestMethod {
                # We need to find the correct Scope-level for DownloadStuff
                # 1. Uncomment $demoVar in DownloadStuff
                # 2. Set a breakpoint on next line and debug test
                # 3. When it stops on the breakpoint, try Get-Variable demoVar -Scope 2 (then 3, 4 etc. until match)
                Set-Variable -Scope 3 'scv' 401
                'no data'
            }
            $result = DownloadStuff
        }

        It 'Returns 401' {
            $result[0] | Should -Be 401
        }
    }
}

It will not work as-is in your production code because DownloadStuff is defined in a module. Modules have their own session state which includes a separate set of scopes - only GlobaL is shared. Scriptblocks are bound (linked to/runs in) the session state they are created in.

The mock scriptblock is defined in the test code, which runs in the global (default) session state, while the code in DownloadStuff will run in the module's session state. Except for the global scope, Set-Variable in your mock can't reach any relevant scopes that DownloadStuff can see variables in.

We solve this by making the mock run in the module's session state as well.

Describe 'DownloadStuff in module state' {
    BeforeAll {
        Get-Module DemoModule | Remove-Module
        New-Module DemoModule {
            function DownloadStuff {
                # $demoVar = 234
                $stuff = Invoke-RestMethod 'example.com/api/stuff' -SkipHttpErrorCheck -StatusCodeVariable scv
                @( $scv, $stuff )
            }
        } | Import-Module
    }

    Context 'Using a bound scriptblock' {
        BeforeEach {
            # We need to bind the scriptblock to the module state so it has access to the same variable scopes as DownloadStuff
            $moduleBoundScriptblock = (Get-Module DemoModule).NewBoundScriptBlock({
                    # Find the right Scope-value. This will be different from the previous example
                    Set-Variable -Scope 2 'scv' 401
                    'no data'
                })
            Mock Invoke-RestMethod -ModuleName DemoModule -MockWith $moduleBoundScriptblock

            $result = DownloadStuff
        }

        It 'Returns 401' {
            $result[0] | Should -Be 401
        }
    }

    Context 'Creating mock with InModuleScope' {
        BeforeEach {
            InModuleScope DemoModule {
                # Running inside the module will automatically bind the scriptblock to the module state
                # + automatically publish mock in the module (no need for -ModuleName ..)
                Mock Invoke-RestMethod {
                    # Find the right Scope-value. This will be different from the previous example
                    Set-Variable -Scope 3 'scv' 401
                    'no data'
                }
            }

            $result = DownloadStuff
        }

        It 'Returns 401' {
            $result[0] | Should -Be 401
        }
    }
}

[dkaszews]

Thank you so much for the detailed writeup! Changing Mock -ModuleName MyModule Invoke-RestMethod { ... } to InModuleScope MyModule { Mock Invoke-RestMethod { ... } } was exactly what I needed. Set-Variable -Scope 3 is indeed the correct level, was that a guess, or experience? I'm guessing it's one for parent, one for hook and one for luck 😅

Maybe it would be worth adding such example to https://pester.dev/docs/usage/mocking ? There is nothing about InModuleScope on that page and https://pester.dev/docs/usage/modules does not speak about variables either from what I can see. Maybe that is generic PowerShell knowledge that modules have entirely separate variable scopes, but it was news to me. And mocking commands with -Variable parameters should not be that uncommon.

[fflaten]

Glad I could help!

Set-Variable -Scope 3 is indeed the correct level, was that a guess, or experience?

I may have tested the code before posting it 😉

Maybe it would be worth adding such example to https://pester.dev/docs/usage/mocking ?

The function is mentioned in Unit Testing within Modules and InModuleScope.

Not this particular use case, but as I showed above you could achieve it without InModuleScope as well. Might be a relevant example in the first link, but it's advanced and -*Variable ... are probably not used very much so might confuse more than it helps. At least it's documented here for now.

Maybe that is generic PowerShell knowledge that modules have entirely separate variable scopes, but it was news to me.

You're not alone. Most users only need to remember to export any functions, variables and aliases from a module that should be visible on the outside. Normally there's no need to understand the mechanics behind unless you start to provide scriptblocks as parameters like we do with Mock. That's when things get... interesting 😄

[dkaszews]

One more thing, not that crucial as I went with a different approach that does not need this, but still interesting. Any way to access variables from the current module when using approaches above? My motivating example is a helper method for creating mocks:

BeforeAll {
    function Mock-RestMethod($status, $result) {
        InModuleScope TestModule {
            Mock Invoke-RestMethod {
                Set-Variable -Scope 3 'scv' $status
                $result
            } 
        } 
    } 
}

It 'Returns 401' {
    Mock-RestMethod 401 'no data'
    $result = DownloadStuff
    $result[0] | Should -Be 401
    $result[1] | Should -Be 'no data'
} 

I found that I can pass variables into InModuleScope with -Parameter, but they are still not accessible inside the Mock scriptblock. Couple threads on Stackoverflow suggest using globals, but as I already said, it doesn't seem like a proper solution.

I have no issues with using helpers for mocking Get-UICulture but that does not use Set-Variable, so I'm using normal Mock -ModuleName TestModule Get-UICulture { [CultureInfo] $MockSystemCulture }.

[fflaten]

See comment in your next post :)

[dkaszews]

I tried using closures per your blog in https://frodeflaten.com/posts/generating-pester-mocks/ , but no luck, maybe messed up the syntax somewhere, will try again tomorrow and post some code if still no dice.

[fflaten]

Closures would store the variables (good), but it won't work alone as the scriptblock would run in it's own module (the closure). You'd basically be back to the initial problem where Set-Variable wouldn't set the variable in the session state for TestModule where you need to read it.

[fflaten]

Something like this would work, but remember KISS. Do you really need to abstract this when you already have a complicated mock?

BeforeAll {
    function Mock-RestMethod($status, $result) {
        InModuleScope DemoModule -Parameters @{ status = $status; result = $result } {
            param ($status, $result)
            # Using param-block only to define the variables locally so closure can see and capture them

            Mock Invoke-RestMethod -ModuleName DemoModule -MockWith {
                # This runs in a closure (dynamic module) but the variable should be set in the DemoModule
                InModuleScope DemoModule -Parameters @{ status = $status } {
                    Set-Variable -Scope 4 'scv' $status
                }
                $result
            }.GetNewClosure() # using closure to capture the variables
        }
    }
}

It 'Returns 401' {
    Mock-RestMethod 401 'no data'
    $result = DownloadStuff
    $result[0] | Should -Be 401
    $result[1] | Should -Be 'no data'
}

[dkaszews]

Yeah, KISS is why I went with a different approach, making a single mock for all tests that checks $PesterBoundParameters and uses it to determine what data should be returned. If I need to overwrite this for a single run, I will just introduce a helper, e.g. InModuleScope TestModule { function MockIsServerBusy { $false } } and mock that instead.