Suggested Documentation Update: Mock Scope

[Veretax]

1. General summary of the issue

Mock scope appears to be not intuitive.

If you define a Mock in an It, and think that when the It is gone that the Mock is gone, it does not appear to be so. Since there doesn't appear to be a way to dispose of the Mock, the Mock may be available in every It and its parent Context.

The Work around is to put non mocked tests in a separate Context or Describe

2. Describe Your Environment

Happens in both Win 10 and Server 2016
Pester 4.9.0

Operating System, Pester version, and PowerShell version:

Pester version     : 4.9.0 C:\Program Files\WindowsPowerShell\Modules\Pester\4.9.0\Pester.psd1
PowerShell version : 5.1.14393.3053
OS version         : Microsoft Windows NT 10.0.14393.0

If you use Pester from a folder not included in the Env:PSModulePath please change a provided code accordingly.

3. Expected Behavior

I expected one of two things:

Either 1. Mocks are no longer available when defined in an it and the it is done.
2, A method to dispose of the Mock when done with it.

4.Current Behavior

Right now Mocks defined in an It, override the mocked call in all other its within the same context.
To test you have to create a second context. Not clear from documentation.

5. Possible Solution

Add a section on scoping to docs on wiki for Mocking, barring that add feature so that mocks can be disposed of

6. Context

The article published in 2014 here has a blurb about this issue: https://www.powershellmagazine.com/2014/09/30/pester-mock-and-testdrive/
Kudos to Jakub Jareš for this quote:

"Mock scoping
The last set of rules you should keep in mind are the scoping rules that apply to mocks and mock call assertions. They complicated our lives already when we tried to assert on a mock call count in the first example, and they may produce all kinds of unexpected results if you are not aware of them:

Mock defined in Describe is available in the whole Describe.
Mock defined in Context is available in the whole Context.

Mock defined in It is available in its parent scope. That is in whole Context if the It is placed in a Context, and in whole describe if the It is placed in a Describe."

THere is a section about 'Invoke-Pester' but it would be smart to add a section called Scoping that points to it to make the docs better.

[nohwnd]

@Veretax This is a problem that probably everyone coming to Pester faced. 😢

I remember discussing this with Dave Wyatt when we were talking about Pester v4 changes, and keeping Mock scoped to a Describe / Context level by default, seemed logical at that time, but in retrospect it was a bad choice.

The scoping is also mentioned in the first sentence of Mock description, but I agree that it is not obvious how the scoping works.

In Pester v5 the scoping works the way most people expect it to. Defining Mock on Describe / Context level will keep it alive in that block, but defining it in It will keep it alive only in that It block.

At the moment I think that the only step we can take is improving the documentation, but I don't want to introduce a new cmdlet to remove the mock, because the lifetime of mock is quite complicated, and the current behavior of v4 is quite well known.

What you should also know is that we are in the middle of migrating the documentation and wiki to a new technology and location, so the wiki is locked, but you can make a PR that updates the comment based help of Mock and it should update the docs as well (eventually, the CI is probably not setup yet).

And thanks for the mention. I see it was a loooong time ago I wrote that article. 🙂

[Veretax]

@nohwnd I agree, documentation change is what I'd do, because most people familiar with unit testing would likely be looking for a scoping section anyways. I wouldn't push for a code change if other changes are coming to Mocks. I do love that I can do this with pester though. So grateful for this library.

Also, double kudos on the blog post you probably saved me 3-4 hours of banging my head through debugging to figure out what was going on.,

[JustinGrote]

@Veretax FYI in Pester v5, this now works you would expect.

[fflaten]

@nohwnd Did I read that you're working on rewriting the Mocking-docs? If so, feel free to take over this.

[nohwnd]

@fflaten You did, but I will take it on after 5.3.0 is done at earliest. So if you want to have a stab on it go for it.

[nohwnd]

Two things resolved this: in Pester v5 the behavior itself changed so mocks defined in It stay scoped to that It (and Describe/Context mocks live for that block) — which is what most people expect — and the mock scoping is now covered in the docs on pester.dev. Since both the behavior and the documentation ask are addressed, I'm closing this. Thanks @Veretax.