fflaten
commented
1 year ago 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
Checklist
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