Table of Contents – Working with Pester Output

After the length of the last chapter, this one, was much appreciated. That said, the last chapter may have been the best one thus far, so don’t skip it. I suspect I may head back and read it again, a time or two. In this chapter, however, we covered Pester output. Let’s review what we learned during this portion of The Pester Book.

The main goal of this chapter was to discuss some of the output options offered by Pester. There isn’t much. Hopefully you have something that’ll consume nUnit XML. When I was first searching for Pester output options, I had to do some work to get what I as after. I even wrote about it, and that was long before I started this book and these reviews.

So anyway, you have nUnit XML or this post. I didn’t know as much about Pester then, and I still don’t hate that post, so it may be worth something to you. See you after next chapter.

Table of Contents – Adding Tests – Again

If you haven’t yet read this chapter yet, then buckle up. It’s purposely long, as Adam indicates that he didn’t go into a good amount of detail in the last take-an-existing-function-and-add-tests-to-it example/chapter. With that, let’s discuss.

The first few sections we’re actually quite helpful. The whole thing was; don’t get me wrong. But these sections, more or less discussed something that’s important to me, and that’s using functions, and ensuring that they’re small and single purposed. It wasn’t word-for-word, but I’ve often said and written that I’d rather troubleshoot five 20 line functions, than one, one hundred line script. The book and I weren’t exact on words; however, we were on meaning. It’s much easier to handle things in small amounts. Think, checkbook registers — for those still using one — it’s much easier to enter things in small batches, as you spend your money, than to save up all your receipts until the end of the month, and then enter them. So seriously, let’s shoot for function writing only, and making them small and simple.

We also discussed the relation of the number of parameters to that of the number of tests. It makes sense to me, as each will add more ways in which the code will need to be tested. We covered using various types of parameter validation to limit the number of tests, as well, and then using helper functions to remove some of a function’s required, in-function work. We took one function and made three, and in doing so, made testing — and even supporting it — an easier thing to do. At first glance, I wasn’t sure there was that much we could alter; the function looked good to me, and yet we did remove some work from it, to be shared across helper functions — it was good to see.

Once we had our slimmed down function, we discussed flow, code paths, creating tests for the shortest code path, as well as other code paths, and saw some great examples of mocking. We’re still working with unit testing, and so you’ll appreciate the mocking examples in this chapter, if you’d like to see more. I did. Like the last one, this chapter helps make this book. While I enjoyed learning the basics from Part I, this has gotten much more interesting, to no surprise.

Table of Contents – Design Practices

Well, we’ve started Part II; it’s official.

The Design Practices chapter of The Pester Book went a little bit of everywhere, and no surprise really, when you consider the topic. Design practices are going to be a consideration at all points of your Pester authoring. This chapter began with the discussion of tests, and how they are forever. Testing isn’t something we do once, before a final release. It’s something we do before every release. We’ve likely all been troubled by code changes before that ended up doing more harm than good, as a new fix or feature broke previous fixes and features. By continually testing, we can ensure our code modifications only add to the tools we create, as we ensure that previous tests continue to pass.

We learned about being certain, beyond a doubt, that we’re testing the proper script or function, when it’s quite possible that we have more than one version of a script, or module, or function, on the same system. I pretty much read this as, always include the code necessary to ensure you’re working the correct code. It makes sense to me that everyone just simply get into this habit now.

We also got to look at the below three lines of code; it seems like I see them everywhere. They are a product of the New-Fixture Pester function. They are included in the .Tests. file created by this function; a function that produces a script file, and test file for the script file that includes a failing test. Remember, we write our tests first, ensure that each fails, and then start coding our solution, which in turn corrects our tests.

$here = Split-Path -Parent $MyInvocation.MyCommand.Path
$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path) -replace '\.Tests\.', '.'
. "$here\$sut"

While I didn’t find it in the book first — although, I did determine it is included — I stumbled across the meaning of $sut earlier yesterday. It stands for system under test. The next thing we covered was how to modify our tests files when working with modules. The code included in the book was substantially different from the code above. I’m certainly glad I don’t have to figure that one out myself — thanks, Adam.

The chapter continues on to discuss the Input/Execution/Output pattern — I can kind of seeing myself use this pattern. The best part after the chapter opening, however, was the discussions on Describe blocks, naming conventions, and tagging. It was nice to see the preferences of someone else. For me, I cannot seem to stop adding colons after the Name parameter values for the Describe, Context, and It blocks. They should just be there by default… to me, at least.

Describe -Name 'Advanced Function Template 2.3.4:' {
    Context -Name 'Tests without including parameters:' {
        It -Name 'Testing empty Advanced Function Template:' {
            ___-_________ | Should -Be $null
        } # End It.
    } # End Context.
} # End Describe.

Describing Advanced Function Template 2.3.4:

  Context Tests without including parameters:
    [+] Testing empty Advanced Function Template: 242ms

Off to the next chapter.

Table of Contents – The TestDrive Drive

Today we’re going to discuss the final chapter in Part I of The Pester Book. It’s time to discuss the TestDrive. But before doing that, let me point out that you may want to go back and review the Mocks chapter. While it’s not directly tied to the TestDrive, that entire chapter covered a good deal of information — know that stuff. Those last few sections were intense! And after that sentence, I would like to mention that I rarely use exclamation points.

Okay, so moving on. Remember that in unit tests, we want to be dependent of all entities outside of our tests. This includes databases, Active Directory, and anything else that has to be in place for a function to properly execute. This includes the file system, too. If it has to be there, and it’s separate from our test and the code that we’re testing, then it needs to removed mocked.

We don’t really want to actually modify the file system of the system on which our tests are running. Again, we don’t want to require any dependence on our system; it’s an important distinction of unit tests. We have a “drive” we can use in our testing without any real disturbance to the underlying operating system.

See the book for some solid examples of how the TestDrive is scoped. As many things in Pester do, the TestDrive works differently here and there, and it’s best to learn it now, instead of later, in that stuffing some of this in your mind now, might save time when you’re having to revisit this alone. A couple pointers I do want to write down myself, however: One, tests cannot access a TestDrive in a different Describe block, other than the one in which they are executing. Two, Files created directly in a Describe block can be accessed by Context blocks contained in that same Describe block. I think I got it right.

Oh yeah, there’s also a variable created that you can use. Take a look at that, as well as what values are displayed when I return all my FileSystem PSDrives, from within a test (yes, using Write-Host).

Clear-Host
Describe 'TestDrive system location:' {
    Write-Host $TestDrive
    Write-Host (Get-PSDrive -PSProvider FileSystem)
}

Describing TestDrive system location:
C:\Users\tommymaynard\AppData\Local\Temp\b41d3954-dece-3a2c-9b14-e0206a3a5d63
C D S TestDrive X

Time to start Part II. See you then.

Table of Contents – Mocks

The Mocks chapter of The Pester Book has several sections. The final paragraph, of the final page in the final section says, “Mocks are by far the hardest concept in Pester to wrap your head around but are critical in creating good unit tests.” Now, jumping back to the beginning of the chapter, and we have this quote: “Mocks are one of the most important concepts in Pester yet also the least understood.”

Another way to say all this, would have been, “pay attention — it’s about to get good, and if you don’t pay attention, you might as well put the book down.” Well, that didn’t happen for me. Let’s review.

This chapter gives us our first real example of using Mocks. Remember from a few chapters and days back that the first type of test we want to write is a unit test. It’s the smallest test. But, that’s not the most significant part — the most significant part is that it’s a standalone test, that needs all it’s dependencies removed. What’s the mean? This is chapter opens with a walk through where we create a function that reads from a CSV file, and uses the username obtained from the document inside a call to Get-ADUser. If we remove dependence, then we remove this need for a CSV file, and an Active Directory environment. Think about that. Or rather, think about the PowerShell you’ve written in the past. Your testing probably needed all those things. Didn’t it? Yeah…, we know.

You’ll enjoy the opening to this chapter. I did. There’s something exciting about watching a successful test that requires a CSV file and AD, suddenly not need either one.

The chapter closes with a few small sections: Mocking Specific Object Types, Mock Scope, Module-Level Mocks, Parameter Filters, Mock Assertions, and Asserting A Single Mock, just before the chapter’s Wrap Up. Every one of these was important, and vital, to the complete Mocking topic. Read them; they are all very important to fully comprehend!

Table of Contents – Test Cases

It’s a chapter like this, if you didn’t know it before, that you suddenly realize how much more powerful Pester is than you may have first thought. Test cases allow us to reuse an It block multiple times. Each time we use it, we can pass in different values that we want our parameter(s) to have, and record what happens when each of those are used. This might be confusing in text alone, so let me show you an example that I came up with.

Clear-Host
Describe -Name 'add two numbers:' {
    $TestCases = @(
        @{Number1 = 1; Number2 = 1; Total = 2; TestName = '1 + 1'}
        @{Number1 = 2; Number2 = 2; Total = 4; TestName = '2 + 2'}
        @{Number1 = 3; Number2 = 3; Total = 6; TestName = '3 + 3'}
        @{Number1 = 4; Number2 = 4; Total = 8; TestName = '4 + 4'}
        @{Number1 = 5; Number2 = 5; Total = 10; TestName = '5 + 5'}
    )
 
    It -Name 'Testing addition of two numbers <TestName>:' -TestCases $TestCases {
        Param ($Number1,$Number2,$Total)
        $Number1 + $Number2 | Should -Be $Total 
    } # End It.
} # End Describe.

I’ll quickly point out a few things we learned in this chapter: We’re now using a new It parameter called TestCases. This parameter accepts an array of hash tables, Yes, you read that correctly, and each one is tested against the It block. In our example, two of the hash table’s key-value pairs serve as the values to the Param block. The TestName value, however, ends up being stuffed into the It block’s Name parameter, allowing us to differentiate between which test is which.

Here’s the results the above code produces.

Describing add two numbers:
  [+] Testing addition of two numbers '1 + 1': 52ms
  [+] Testing addition of two numbers '2 + 2': 10ms
  [+] Testing addition of two numbers '3 + 3': 25ms
  [+] Testing addition of two numbers '4 + 4': 28ms
  [+] Testing addition of two numbers '5 + 5': 32ms

It is a chapter such as this, and even Pester on its own, that make you realize that you have to have some sort of grounding in PowerShell function writing to be successful. And maybe not function writing, maybe script writing as well, providing you understand how to include parameters in your code. It’s important you’re comfortable with PowerShell long before you tackle Pester — just putting that out there.

Next is Mocks; can’t wait!

Update: I made a slight change to the above code. While it produces the same results, what I did was this. Instead of calculating the Total inside the It block, we send in what the total should be as the Total parameter value. This ensures that if the Number1 or Number2 parameter values are changed, that the test actually fails. When the total is calculated in the It block, it’s always going to pass, and I didn’t want that to be the case.

Table of Contents – Should

I finished the Should chapter in The Pester Book. As I’ve already been doing some testing with Pester, Should is a keyword, or command, in which I’m familiar, and in which I’ve used. It works this way: the Describe block, houses optional Context block(s), which house It block(s), which include an assertion. This assertion includes a PowerShell command piped to Should, that either passes or fails.

It it’s simplest form, a nested It block might look something like this example, taken almost exactly from The Pester Book.

...
    It ‘Testing 1 is an Integer:’ {
        1 | Should BeOfType [int]
    }
...

Because the numeric value of 1 is in fact an integer, this test will succeed. When Pester runs against this assertion, it’s going to pass, and produce output such as this:

...
    [+] Testing 1 is an Integer: 28ms
...

Those test results will be in green — the color of success.

The piping of our command to Should turns useable PowerShell, into Pester testing. Previously, we’ve discussed the keywords necessary to create the test framework. Now, we’re adding to our test, what’s really making it a test.

The Should keyword, or command, requires operators. We saw the -BeOfType operator in the above example. These operators, according to The Pester Book, are Be, BeExactly, BeLessThan, BeGreaterThan, BeLike, BeLikeExactly, Match, MatchExactly, BeOfType, Throw, Exist, Contain, ContainExactly, BeNullOrEmpty, and BeIn. Keep your eyes out for new ones, as Pester is continually being developed.

Remember, Should takes our assertion and determines whether it’s accurate or not. If the test is accurate, or is true, the test has passed. In reverse, if the test isn’t accurate, or is false, it has failed. Remember however, that you can have a successful test, if you’re testing for failure.

Table of Contents – It Blocks

Today, we’ll review some of what was offered by the It Blocks chapter. Things, are getting interesting.

It turns out that It blocks are our main unit for testing. These blocks are the smallest blocks and belong inside a Describe and/or any Context blocks, if you’re using those. As they’re the smallest, it’s always best to keep them “simple, and as straightforward as possible.” The idea was that we should test everything independently of each other when we can, and that when we can’t, there needs to be a good idea as to why. That lead me to this write this Tweet today, where I questioned whether I should test all the permitted random password length values (4 – 35), that my random password function would accept in a single test, or one test — one It block — per value from 4 – 35. Take a look and let me know what you think as I’ve done both below. I haven’t actually seen any replies yet besides a few likes, and I still don’t know which I’ll end up using.

Which would you do? Test all the permitted random password lengths in one #Pester test, or test the permitted length in individual tests? #PowerShell pic.twitter.com/tawx4erUEA

— Tommy Maynard (@thetommymaynard) March 26, 2018

We also learned to have your It block throw a terminating error if an expectation isn’t met, the five possible results of an It block (passed, failed, etc.), using the Pending and Skip parameters on our It blocks, and finally about the Set-TestInconclusive option for It blocks that ensure a test is never run, under any circumstance.

Next we’re talking about Should. That should be interesting.

Table of Contents – Before and After Blocks

If for some reason you’re just getting here now, we’re doing chapter reviews on Adam Bertram‘s The Pester Book. Get a copy, start reading, and follow along with us. It’s the PowerShell testing framework, and you’re going to need to know it, if knowing PowerShell is something you already need to know.

Today we’re going to review a good, but short chapter on Before and After blocks. Before and After blocks contain two blocks each. Those are BeforeAll and BeforeEach, and AfterAll, and AfterEach.

BeforeAll and AfterAll blocks indicate things that should happen before any of the It blocks run, and after all the It blocks run, respectively. The difference with BeforeEach and AfterEach, is that whatever arbitrary code runs in these, does so before and after each It block, and not just once at the beginning and once at the end of a Describe and/or Context block.

Got it.