Microsoft 365 Community CLI for Microsoft 365, 18 Aug 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: How to write tests for CLI for Microsoft 365

Description

In this video Rabia Williams demonstrates how to use write tests for CLI for Microsoft 365. When you contribute commands to CLI for Microsoft 365, you should also include tests that prove that the particular command works as intended and this video explains how to do it.

Video demonstrates the following steps:
- CLI for Microsoft 365 command structure
- writing basic tests
- stubbing methods

Presenter: Rabia Williams (Microsoft MVP) @williamsrabia

For more information about CLI for Microsoft 365 visit https://aka.ms/cli-m365

Learn more about the Microsoft 365 Patterns and Practices community at: http://aka.ms/m365pnp

A

Do you want to contribute to office 365 cli? Are you stuck or not sure where to begin for writing tests for cli commands, then this video will help you to do just that.

A

So before we write test for the command, let's go ahead and look into one of the commands, that's already available and see how it is structured to better understand the kind of tests we need to write for each command now um office. 365 cli is a project where 100 coverage is uh preferred for any of your pull requests to be approved. So um we have to make sure that each and every bits in your code or any you know pathway for your code is being covered using a test written for it.

A

So uh we'll go ahead and dissect this particular command called the teams channel list command, which basically is one of the simplest command. I can show you to better understand the concept, so the structure of the file is very similar. You've got channellist.ts and your test file would basically be dot. Spec, dot, ts, instructor tiers for our main function. You have a name function which basically is the name of the command the new command that you're writing, for you also have a description function, which, basically is um the description of the command uh command.

A

Action is where all the juicy bits happen. The where the api call is being made um to display information to you or to run an operation for you using cli, and this is where the entire thing uh would happen, and this might change based on what kind of command you're working on, whether it's a post operation or a get operation or a patch etc.

A

Then you have a function called options, which is where you can pass your parameters. um This would also change based on what kind of parameters your command would be using. In our case, we have a mandatory argument. Called team id validate is another function in every command which validates if there is a required parameter or if a parameter should be office for a particular format. For example, in our case, we have to check whether it's a valid view id.

A

You also have a function for command help which basically is to let the user understand how to use this particular command if he is passing a wrong argument or passing the name incorrectly.

A

So that's basically the structure of a command in office, 365 cli. Now, let's jump on to the spec file for it, which is basically where all the tests are written.

A

So, let's jump into the test file for the previous command that we saw channel list.ts we have channel list.spec.ts, which is a test file and office365 cli uses signon.js to create a spy, stubs and mocks.

A

So this is how our file would look like it has the configuration in the beginning for your particular command, and then you will have tests written for each and every code path that we have in the command. um Keep in mind that we have a hundred percent coverage uh in office 365 for to um to accept your pull request. So it is very important. You cover all the different pathways of your command now in this um particular command.

A

uh What we can take away from the existing uh test, written already in in this project, is to um you know you don't have to start from scratch. You can go ahead and look into a similar command that either lists or it removes or gets a particular item or adds a particular item and go ahead and copy the spec and make minimal changes or add extra test functions to cover all the different cases in your command. So that's exactly what we usually do when we have a new command in hand.

A

So this section where you're configuring um your test uh file is mostly very similar to um to the others already being done. um There might be a few changes here and there, you might add, maybe request dot, um post or request or delete to restore things, but other than that there might be only a few different changes across this entire section.

A

But of course this area would would I mean the test that you write for each command may differ, but even then I would say that there are a lot of tests are written, which is, um which is. uh We should be there across all the commands like, um for example, this one. It has correct name now, every command has to have a correct name.

A

It's also checking whether you have uh mentioned the correct name of the command in your test file, and then there are other bits like supports debug mode, which I cannot imagine it would ever change um and also having help uh for your command, or it has helped with examples. All these things are, you can just straight away, go ahead and copy it and make sure those bits of your command are already taken care of uh during unit test device. Now what may change?

A

Oh, I forgot about this one it has description, is also another one that is um that is duplicated or used across in every command. So yeah you can just go ahead and copy it, as is, and you have basically covered the description side of things as well. So uh with that in mind, there are a few changes you may have to make, for example, validating your command now this would be different for each and every command.

A

In our case, we know that team id is a required field and it also has to have a certain uh pattern like it should be a goo id. So this is what the two validations that we have done here.

A

So if you just correlate these things, you can understand how uh test and you know and writing tests for each function is so if you go ahead and come to our validate function here, there are the two uh pathways we have, whether checking whether team id is present or not um also whether check checking it, whether it's a valid google id or not. So these two things have been captured in these tests.

A

Validation. If the team id is not a valid uid and also if it is not provided, then you basically have to throw an error. So those things are now taken care of another um validation that happens. Is you have a correct input so yeah, it's probably a duplicate but yeah. It doesn't hurt to add anyway um so another.

A

So another thing that we have to notice is writing tests for your main function, which is um which is something that's going to change for every command and yes, based on the complexity of your command action, uh you can have a few too many uh tests written to make sure that every bit of this is covered. So you have, if you look at this one, you know that you have a pathway where json output is option.

A

Output option is being provided where you are basically have to print out or show all the items that are retrieved by this api. Another pathway is, if that's not provided, then I mean the output option is not provided with json. Then you can just display id and display name of all the information that is being given by the api.

A

Another pathway is, if we've got um in the wordpress mode or another pathway is if all this api endpoint fails, then you have to have some sort of an error display mechanism. So this is a very simple scenario. There might be more complex scenario, but just to give you an idea of how we should be writing tests. So all these things should be um written with tests so that every pathway is already covered.

A

Now, let's see the first one here, so I think these bits are the ones that will take care of all that the first one is um without debug mode.

A

How would it give you information back so we have now a sign on stub um feel free to go ahead and check out signon.js to understand what stubs are, what calling a fake function is or to understand how spies work, for um I might give you a quick overview steps or functions with pre-programmed behavior. In our case here we have a stub where we are of calling a very fake function, which would um call an api for this request. All these things are taken care of for you.

A

You just have to pass your endpoint and uh predict the behavior of what that endpoint does, which basically is us passing some values here um and resolving that function, and then we say that hey once we have a command instance, which is uh going to say that in my command instance, I'm saying this is my team id. In that case, my spy spies again are basically something that would record arguments and return values for all the calls made by the stub. um So the spy would go ahead and say hey once this is passed.

A

This is pass and this information is passed. What our command does is, after getting this information back, it would display the id and the display name, that's exactly what we are doing in our function as well. This is how it displays information.

A

If the output json is not provided, so that's basically it and we say we call it done. Another option is again the debug mode or not. We just have to make sure that um debug option in it is true and it will be very similar to what we have done earlier and another uh test written here is the json output mode to cover this section of the command, which basically would mean that this the stub remains very same, very similar to the earlier one, but the information that we get back.

A

For example, we have got the output json also passed into the command instance, and the information that the spy would record would be the entire value that is being uh given by the stub. So it does not do that filtering or not filtering exactly, but being mindful of the properties being passed out.

A

It would just give out everything that is given out by the um stub, so that takes care of this part of the function which basically is checking if there is an output option being given for json now, the last one that we need to look into is to make sure that error handling is done properly as well, so that is the next function.

A

So um what here? What we do here is the stub basically would say: hey just reject the function altogether. So what happens here is this. um This call is rejected and it goes straight away to um error being shown to us and we are predicting here again. We are predicting and pre-programmed being the behavior saying an error has occurred now this would. um This is only faking it right.

A

So um in our special in our real scenario, it would be an error thrown by the apr or something that will be displayed, but we are making sure that it's discovered by giving our own pre-programmed rejection message and uh we'll go ahead and assert that as the error message being displayed as well.

A

So this is how we can write test, um and this is how we have to think when we are writing tests to make sure that every bit of code that you have every pathway or every action that you take within your command action is completely completely translated into different tests. That you write here so um go ahead, and let us know what you think about what we should do next uh on in our videos.

A

You can go ahead and add your discussions here in github.com, slash, pnp, slash office, 365, hyphen, cli, slash discussions or open up an issue and we'll take care of that. Thanks for watching.