Examples could be slightly more verbose and real-world

[merddyin]

Checklist

• [X] Issue has a meaningful title
• [X] I have searched the existing issues. See issues

Summary of the request

I've been a PowerShell user ever since it was called Monad, and I have known of Pester for years. While the idea of test-driven PowerShell development always resonated with me, I have not been able to actively begin actually using Pester until the last few months or so. Even now, the journey is very slow going, with lots of trial and error, and it comes back to the documentation for me. This is not to say that the documentation isn't there, or it isn't good, it's just difficult to correlate for someone like me I suppose. I am originally a 'lazy' infrastructure guy who likes automating things . I got more advanced because I wanted to stop writing scripts for others, and instead build tools. Unfortunately I stuck with manually testing everything though, because I could not figure Pester out from the documentation and experimentation alone.

What finally got me going was seeing a real module in GitHub, with real detailed tests stored with the module. It wasn't comprehensive, but it was enough to finally bridge my gap in understanding, at least enough to let me experiment more. I think that is what is missing from the current documentation is a sufficiently 'real-world' type of setup, sort of like the examples you see in most of the help for Microsoft cmdlets. Yes, you provide an example module today, but the example isn't something I can connect with for whatever reason...I dunno, maybe it's too simple? What would be awesome, from my perspective at least, would be seeing something more involved that does something real, and then seeing that used throughout the documentation. Alternatively, instead of changing the documentation, you could just provide a reference link to a module with tests that use that capability, and then use that module within the examples in place of the basic one.

The biggest area I struggle with presently is understanding Mocking. In theory, I understand that I am faking a call to another cmdlet, but I don't understand how that actually works. For example, I have a module I've written that deploys OUs, then passes those OUs and produces System.DirectoryServices.DirectoryEntry objects. Those objects are intended to be sent via the pipeline to another cmdlet that creates groups, which once again results in DirectoryEntry objects that continue down to yet other cmdlets. Whether I'm faking the call to another cmdlet, or passing a set of 'fake' objects down the pipeline, I can't conceive of how I would mock that without writing a whole massive set of code that crafts a DirectoryEntry object. From the documentation, it looks like I don't, I just have a test that confirms a call was made a certain number of times?

This is just a thought on my part, as a non-dev Pester newbie, so if it doesn't make sense, feel free to tell me so and close out.

Suggested section

Usage