Unit Testing (Vitest) Tutorial #12 - Creating Spies

Key Takeaways

All right then, gang. In this lesson, we're going to talk about something which is in some ways similar to mocking functions, and that is spying on functions. So, when we spy a function, we're not replacing it with a fake one like we do when we mock a function. Instead, we're keeping the original exactly as it is, but we're just watching what happens when it's called. And just like with mocks, we can track how many times it's been called, what arguments it received, and what values it returned. But unlike mox, a spy lets the original function logic still run unless we choose to manually override it. So using a spy might be a good idea when we want to test maybe the side effects of a function call or to verify that it was triggered correctly at the right time without removing its behavior. In this lesson then we're going to spy a function and see how all of this works. Now to do that we'll be working with a brand new function that I've already created inside this setup game.js JS file in the source directory. And inside this file, we import two of the other functions we've already created throughout this series so far. The shuffle one, and the deal one. Now, this setup game function takes in three arguments. An array of cards, a hand size, and the number of players. Inside the function, we shuffle the cards first, and then we deal those shuffled cards using the deal function together with the hand size that we take in and the number of players. Then we create a new constant called players which will be an array of player objects. And to make those player objects we use the map method on the hands array. So inside the players array then each player object will have these three properties. An ID property which we're making using the index of the original hands and a hand property which will be an array of card objects dealt to them and then a final one called current turn which is a boolean. And that should be true for the first player where the index is equal to zero but initially false for every other player. And then finally we return the players array. So this function brings together some of the functions we already have to start a new game of cards. Right. And these are the two function calls right here that we're going to spy on. And now we're going to test this function inside a new test file which I've already prepped as well inside the test folder called setupgame.test.js. So then inside this file we already import four things from vest describe it expect and v which is what we used in the last lesson to mock functions. In this lesson we'll be using it to spine functions. I've also imported two functions we'll be needing inside the test. The create cards one to actually create an array of cards and the setup game one. Then we have a new test suite called setup game. And inside that, we've got some suits and values already created that we can pass into the create cards function to generate the cards. I've also created a couple of test cases ready for us down here, which we're going to work through. And in both of these, we're invoking this create cards function to generate the cards array for us, which we can then pass into the setup game function. And again, because we're bringing different parts of the application together in a single test here, we are technically wandering into the realms of integration testing, but we know that the create card function uh produces predictable results. So, it won't have any actual bearing on the tests unless we pass in invalid arguments. Anyway, this first test case says it calls shuffle before dealing cards. So that's what we want to test right now that the shuffle function gets called before the deal function inside the setup game function. To do that then we can make a new spy to spy on the shuffle function. But how do we do that? Well, let's start by making a new constant here which I'm going to call shuffle spy. And I'm going to set that equal to v which we imported and then use a method on that called spy on and invoke it. So this method lets us spy on a function from any given module. And to do that we need to pass in two arguments. The module itself and then the function name within that module. So then we need to import this module at the top of the file. So we can use it in the spy on method. And we can do that by saying import then an asterisk which means import the whole module and then we say as followed by whatever name we want to give this imported module. So we could call this shuffle module for example, but it can be called whatever you want. And then we'd use this name to refer to that imported module when we use it. Anyway, that comes from dot do/ to come out of this current folder then into the source folder and then the file name is shuffle. Okay, so now we've imported that module. We can go ahead now and use it in the spyon method. So let's come back down here and pass that shuffle module in as the first argument. So that now we're telling V test that we want to spy on something from within this module as a second argument. Then we need to pass in a string which should be the name of the function in that module that we want to spy on. So in our case that's the shuffle function. So let's add that in. Okay then. So now we're spying on this function using this shuffle spy and we can make assertions on that shuffle spy now to verify how many times it's been called and with what arguments and so forth. Before we do that though, we need to invoke the setup game function, don't we? Because within that the shuffle function gets invoked as well. So as arguments to the setup game call, we can pass in the cards, then five for the hand size and then we'll say three for the number of players. Okay, then so the first assertion is going to be a simple one. I just want to make sure this gets called one time this function, this shuffle one. So let's say expect and then pass in the shuffle spy and then we should add on a matcher which is to have been called times and then we'll pass in one. Let's save that and run the test over here just to make sure it passes which it does. Awesome. Okay, so the next one is to make sure that the shuffle function runs before the deal function here. All right, because we want to deal with shuffled cards. So what I'm going to do is say expect and I'm going to paste something in then I'll explain it. So we take the shuffle spy and we use a property on it called mock. And you might be thinking that's a little bit weird because we're not mocking this function. And that is correct. But this mock property is basically metadata. It's where V test stores all the tracking information about function calls regardless of whether it's a spy or a mock. And on that property we can access the invocation call order property which is an array of numbers. And those numbers represent the global call order of any tracked functions including spies. So we're saying get the number the global order of the first time this function was called. Right? And then we're going to tack on a matcher which is to be less than. And then we want to check the same thing for the deal spy because we want the global number of the first call of this function, the shuffle one, to be less than the deal one. So, we need a deal spy. And to do that, we're going to have to import the module. So, let's duplicate that and change this to deal module. And that's from the deal file. And then down here, I'm going to duplicate this. And we'll call this deal spy. And that comes from the deal module. And the function call uh the function is called deal. All right. So now we can say dealspy down here dot mock and then dot invocation call order and we want the first time that this was called. So this number right here should be less than this number if this was called first. This shuffle function. So let's save that and run this. And we can see that this passes right. Awesome. However, check this out. If I change the order of these things, I'm going to cut that and paste it down here. And I'll change this argument to cards because shuffle cards at this point hasn't been made. But now if we run this, it should fail. This should fail right here because the order of these have been changed. So now it's not less than this. So let's change it back to make sure it passes again. Like so. Save it. Run the tests. Yep. Awesome. All right then. So now let's do this second test case down here which says it calls deal with the correct arguments. So again, we have the cards right here using this function. And now I'm just going to paste in a few things. So we have a deal spy set up again using this spy on method and a shuffle spy. So we're spying on those two functions again. Then we have a call to this setup game function and we're passing the cards five for the hand size and three for the number of players. Now if we take a look at the function, we can see that the deal function should be called with that correct hand size and number of players. So the second two arguments here, but not with the cards, but with the shuffled cards right here. And we get that from this shuffle function. So we need to somehow access what is returned from this using the spy. And we can do that. We can get the shuffled cards right here by using the shuffle spy. Then we say domok again like we did up here. And then we can get the results from that call. And then we want the first set of results and we want to grab the value from that. All right. So now we say expect the deal spy to have been called with the shuffled cards and then five which is the same as up here and three. Okay. So let's save this and run the tests to see if they work. And yep they do. However, check this. If I was to just pass in the regular cards, save this and rerun the tests. Then now it's going to fail because this right here is incorrect. It's not called with the cards. it's called with the shuffled cards instead. So, let's save that. Run the test again. And now they pass. So then, my friends, that's how we create spies in Vest to spy on functions. They're a little bit like mock functions in that we can make assertions about the functions we spy on, much like we can with mocks. But whereas mock functions change the implementation of the functions, spies don't do that by default. So if you want to keep the original function implementation and you just want to watch what it does, then making a spy for that function would probably be a better option. Next up, we're going to have a quick lesson about something called setup and tearown.