Examples could be slightly more verbose and real-world

[merddyin]

Checklist

• Issue has a meaningful title
• 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

[fflaten]

Thank you for taking time to write such detailed feedback.

Getting started
I agree that docs is currently missing a reference project. There's not one way to structure and write tests, but still a more complex example would be useful. Maybe a new beginner-tutorial that links to a example repo and adds a few tests on each page using different features:

• Integration tests vs unit tests
• Data-driven tests/-ForEach
• Discovery vs Run
• Mocking public and private functions
• CodeCoverage (ex. to uncover the last missing test)
• etc.

Each page ending with links to the relevant usage-pages for more details. The quick start-page already introduce some of this, but I believe it'd be easier to read as a multi-page tutorial.

I believe there is samples for most scenarios, but they're spread into different pages that jumps a bit back and fourth in skill-level. There's also a relevant issue #85 about bringing more content about why we bother testing that might be included somehow.

Mocking
Mocking in particular can be hard for advanced flows. There's also a few limitations ex. being unable to mock calls made by a binary cmdlet (can't fix), and as you've experienced, mocking functions with pipeline-input.

I can't help with your concrete example without code, but some parts are easier to mock than others. See https://pester.dev/docs/commands/New-MockObject for a simple way function to mock objects like DirectoryEntry with only the required properties needed for your function. Passing mocked data are meant to be used with your functions, anything else could fail.

If you have more question about that, there's lots of helpful people on Discord/Slack (synced testing-channel) etc. See: https://pester.dev/docs/contributing/introduction#where-to-get-support.

[merddyin]

Thanks much for taking the time to respond. I think a sample project that does something, even if that something is relatively simple, would go a long ways towards helping others connect the dots on things. The current examples in the documentation are very disconnected, and represent only the most simple of approach. I know I can look at other projects and such, but that means I have to find such projects first, so even links to projects with well-written tests that cover a particular aspect would help.

It would probably be less of an issue if I had an actual developer background, but since my background is instead infrastructure and automation, tests are essentially just trying it in a non-prod environment and seeing what breaks. This type of testing makes a lot more logical sense, but I keep running into problems that the documentation doesn't really help me solve. For example, the issue you helped me with that was actually just path resolution working differently than I thought it would when I tried to import a module to run my tests.

As for the mocking, the functionality I was referencing is from the dev branch of my ADDeploy module, which is publicly accessible here if you are interested in checking it out. Not asking for specific assistance here, as I know this isn't the place, but if it leads to additional examples or a how-to, I'd love to read them! Once I can get the hang of it and get the tests written, I also would be more than happy to be a reference project down the road, if it helps.

In the meantime, I'll definitely look into the New-MockObject cmdlet, which will hopefully help solve the challenge.