When Done, You Will

Protection Against Regression

Because you’ll have a suite of unit tests that are built up over time, you can run them again every time you introduce new functionality (which you should also build tests for). This means that you can check to see if your new code had introduced errors to the existing code base (these are called regression defects ). Unit testing therefore gives you confidence that you’ve not introduced errors or, if you have, give you an early heads up so you can rectify.

Executable Documentation

When we come to write some unit tests, you’ll see that the way we name them is descriptive and speaks to what is being tested and the expected outcome. Therefore, assuming you take this approach, your unit test suite essentially becomes documentation for your code.

 When naming your unit test methods, they should follow a construct similar to

<method name>_<expected result>_<condition>

For example:

GetCommandItem_Returns200OK_WhenSuppliedIDIsValid

Note: There are variants on the convention, so find the one the one that works best for you.

Arrange

This is where you perform the “setup” of your test. For example, you may set up some objects and configure data used to drive the test.

Act

This is where you execute the test to generate the result.

Assert

This is where you “check” the actual result against the expected result. How that assertion goes will depend on whether your test passes or fails.

Going back to the characteristics of a good unit test, the “focused” characteristic comes in to play here, meaning that we should really have only one assertion per test. If you assert multiple conditions, the unit tests become diluted and confusing – what are you testing again?

So, enough theory – let’s practice!

Testing Our Model

Our first test is really at the trivial end of the spectrum to such an extent you probably wouldn’t unit test this outside the scope of a learning exercise. However, this is a learning exercise, and even though it is a simple test, it covers all the necessary mechanics to get a unit test up and running.

Thinking about our model, what would we want to test? As a refresher, here’s the model class in our API project.

 This is such a trivial test (we’re not even testing a method); we can’t really use the unit test naming convention mentioned earlier:

<method name>_<expected result>_<condition>

So, in this instance, we’re going with something more basic.

The following sections are of note.

The sections we added are highlighted here.

Steps 1 and 2 are straightforward, so it’s really step 3 and the use of the xUnit Assert class to perform the “Equal” operation that are possibly new to you. Whether this step is true or false determines whether the test passes or fails.

The test should pass and you’ll see something like the following.

It says two tests have passed? Where is the other test? That’s right we still have our original UnitTest1 class with an empty test method, so that’s where the second test is being picked up. Before we continue, lets’ delete that class.

We can also “force” this test to fail. To do so, change the “expected” value in our Assert.Equal operation to something random, for example.

Save the file, and rerun your tests; you’ll get a failure response with some verbose messaging.

Here, you can see the test has failed and we even get the reasoning for the failure. Revert the expected string back to a passing value before we continue.

Revisit Unit Testing Characteristics

I often struggle with the Focused characteristic and frequently have to pull myself back to testing just one thing, rather than wandering into integration test territory (and attempting to test an end-to-end flow). But that’s not the characteristic I’m most worried about in this instance.

When we come to Unit testing our controller, the Isolation characteristic will present as problematic. Why? Let’s remind ourselves of our Controller constructor.

Even though we are using Dependency Injection (which is awesome), they are still dependencies as far as our controller is concerned, so when we come to unit testing the controller – how do we deal with this? Dependency Injection again? Stick a pin in that for now – I just want to plant the seed.

As before, I think the best way to learn about this is to get coding, so let’s turn our attention back to our very first controller action: GetAllCommands.

GetAllCommands Overview

GetAllCommands Unit Tests

So why not roll these into one test and perform the three assertions there? Well again that would break our Focused characteristic – we should be testing for one thing only per test.

Groundwork for Controller Tests

As with our Command model , we want to create a separate test class in our unit test project to hold the controller tests, so create a class called CommandsControllerTests.cs, as shown in Figure 11-16.

So straight away we want to start arranging our tests so that we have access to a CommandsController class to work with, but how do we create one when it has two dependencies (the repository and AutoMapper)? Dependency Injection – I hear you say! But if you look back at the anatomy of our Unit Test project, there’s no equivalent of the Startup class in which to Register our services for injection. We could start to add one I guess, but that would then lead to the problem of testing against our repository.

Even if we were to use Dependency Injection here, we’d still need to provide a concrete implementation instance; which one would we use? SqlCommanAPIRepo? That requires a DB Context, which in turn requires our Database. Argh! Not only is that horrifically complicated, we’re breaking the Isolation characteristic in a big way by dragging all that stuff into our unit testing.

We could move back to MockCommandAPIRepo and implement test code in there that wasn’t dependent on external factors, a possibility, but still a hassle – don’t worry there is a better way!

Install Moq and AutoMapper

Open a command prompt, and make sure you’re “in” the CommandAPI.Tests folder, and issue the following commands:

dotnet add package Moq

dotnet add package AutoMapper.Extensions.Microsoft.DependencyInjection

Confirm that these dependencies have been added to the CommandAPITests.csproj file.

You’ll notice we’ve added AutoMapper in addition to Moq; we’ll require this later.

Using Moq (Mock the Repository)

Returning to our CommandsControllerTests class, add the following code (taking note of our new using directives):

using System;

using System.Collections.Generic;

using Moq;

using AutoMapper;

using CommandAPI.Models;

using CommandAPI.Data;

using Xunit;

using CommandAPI.Controllers;

using Microsoft.AspNetCore.Mvc;

namespace CommandAPI.Tests

{

  public class CommandsControllerTests

  {

    [Fact]

    public void GetCommandItems_Returns200OK_WhenDBIsEmpty()

    {

      //Arrange

      var mockRepo = new Mock<ICommandAPIRepo>();

      mockRepo.Setup(repo =>

        repo.GetAllCommands()).Returns(GetCommands(0));

      var controller = new CommandsController(mockRepo.Object, /* AutoMapper*/ );

    }

    private List<Command> GetCommands(int num)

    {

      var commands = new List<Command>();

      if (num > 0){

        commands.Add(new Command

        {

          Id = 0,

          HowTo = "How to generate a migration",

          CommandLine = "dotnet ef migrations add <Name of Migration>",

          Platform = ".Net Core EF"

        });

      }

      return commands;

    }

  }

}

Or code is still not runnable, but I wanted to pause here and go through what we have added as there is quite a lot going on!

 Quick reminder, all this code is on GitHub⁵ if you don’t want to type this stuff in.

1. 1.

   We set up a new “mock” instance of our repository; note that we only need to pass the interface definition.

    
2. 2.

   Using our new mock repository, we use the Setup method to establish how it will “behave.” Here, we specify the interface method we want to mock followed by what we want it to return (as described next).

    
3. 3.

   Still in our Setup, we specify that the repository GetAllCommands method returns GetCommands(0) – see step 5.

    
4. 4.

   We use the Object extension on our mock to pass in a mock object instance of ICommandAPIRepo.

    
5. 5.

   We’ve mocked a private method: GetCommands that will return either an empty List or a List with one Command object depending on the value of the input parameter.

    

You can see how easy it is to set up mock objects using this type of framework, saving us a lot of the hassle of writing up our own mock classes. It also highlights the usefulness of our repository interface definition once again.

OK, so we’ve created a mock of our repository that we can use to create a CommandsController instance, but what about AutoMapper?

Mock AutoMapper?

While you can use Moq to mock-up AutoMapper, we’re not going to do that here. Why? Well because in this particular instance, general consensus is that it is more effective (and useful) to use an actual instance of AutoMapper. Additionally, using this approach we get to test the AutoMapper Profiles we’ve set up in our API Project too.

Now I want to sense check here.

This may seem completely contrary to the Isolation and Focused principles, and to some extent it is. My response to that is one of pragmatism (you may call it a cop out!), but the Unit Test Characteristics are just that: Characteristics. They are not unbreakable rules.

As developers we’re often faced with choices and challenges. I may take one path, and you may choose another – personally I think that’s fine. Coding can be as much art as science.

What me must strive to do is solve a problem the best way we can, and sometimes that involves compromise or, as I prefer to call it, pragmatism. In this case (in my view), using an instance of AutoMapper (as opposed to a mocked instance of it) provides more benefits than downsides, so that is the approach I’m going to take.

But please feel free to disagree!

So back in our CommandsControllerTest class, add the following code to provide us with an instance of AutoMapper (taking care to note the new using directive to bring in our Profiles):

using System;

using System.Collections.Generic;

using Moq;

using AutoMapper;

using CommandAPI.Models;

using CommandAPI.Data;

using CommandAPI.Profiles;

using Xunit;

using CommandAPI.Controllers;

using Microsoft.AspNetCore.Mvc;

namespace CommandAPI.Tests

{

  public class CommandsControllerTests

  {

    [Fact]

    public void GetCommandItems_Returns200OK_WhenDBIsEmpty()

    {

      //Arrange

      var mockRepo = new Mock<ICommandAPIRepo>();

      mockRepo.Setup(repo =>

        repo.GetAllCommands()).Returns(GetCommands(0));

      var realProfile = new CommandsProfile();

      var configuration = new MapperConfiguration(cfg =>

        cfg.AddProfile(realProfile));

      IMapper mapper = new Mapper(configuration);

      var controller = new CommandsController(mockRepo.Object, mapper);

    }

    .

    .

    .

  }

}

To step through the changes (for brevity I’ve not shown the using directives below), see Figure 11-19.

1. 1.

   We set up a CommandsProfile instance and assign it to a MapperConfiguration.

    
2. 2.

   We create a concrete instance of IMapper and give it our MapperConfiguration.

    
3. 3.

   We pass our IMapper instance to our CommandController constructor.

    

There is a lot of new content and groundwork there, but now we’re set up; the rest of this chapter should be quite quick! Make sure you save your work, build to check for errors, commit to GitHub, and we’ll move onto completing our first test!

Finish Test 1.1 – Check 200 OK HTTP Response (Empty DB)

To put these in context, see Figure 11-20.

The only specific arrangement for this test case is the fact that we want the mock repository to return “0” resources.

If you want to “test your test,” save your work, and build the project, and then perform a dotnet test (of course inside the xUnit Project) to make sure it passes.

Test 1.2 – Check Single Resource Returned

To put in context, see Figure 11-21.

Save the code and perform a dotnet test to make sure it passes.

Test 1.3 – Check 200 OK HTTP Response

Test 1.4 – Check the Correct Object Type Returned

Out of the four tests we’ve constructed for our first controller action, this is my favorite. Why? It’s essentially testing our external contract. If we subsequently change how our controller behaves (and what it passes back to our consumers), this test will fail in regression. This is the mark of a valuable test for me!

GetCommandByID Overview

GetCommandByID Unit Tests

Test 2.1 – Check 404 Not Found HTTP Response

Here we setup the GetCommandsById method on our mock repository to return null when an Id of “0” is passed in. This is a great demonstration of the real power of Moq. How simple was that to set up the behavior of our repository? The answer is very simple!

We then just check for the NotFoundResult type (equating to a 404 Not Found HTTP Response).

Test 2.2 – Check 200 OK HTTP Response

The only novel code here is the way we set up the GetCommandByID method on our repository to return a valid object, again very simple and quick. The rest of the code doesn’t require further discussion.

Test 2.3 – Check the Correct Object Type Returned

This test checks to see if we returned a CommandReadDto. In terms of checking for the validity of our externally facing contract, I like this test very much. If we changed our Controller code to return a different type, this test would fail, highlighting a potential problem with our contract – very useful.

CreateCommand Overview

CreateCommand Unit Tests

I chose not to write unit tests for those. These cases could be considered valid integration tests that included our controller, but again that’s not what we are doing here. (This is the trap I said I could fall into around the Focused unit test principle.)

For tests 3 and 4, the behavior demonstrated here derived from the default behaviors we get from decorating our controller with the [ApiController] attribute. This is not code I (or you) wrote – so I’m not going to write a unit test for code that I have no control over.

If I subsequently decided to add my own code to handle these conditions, then I’d probably introduce testing for them.

Test 3.1 Check If the Correct Object Type Is Returned

Test 3.2 Check 201 HTTP Response

UpdateCommand Overview

UpdateCommand Unit Tests

Test 4.1 Check 204 HTTP Response

Here we ensure that the GetCommandById method will return a valid resource when we attempt to “update.” We then check to see that we get the success 204 No Content Response.

Test 4.2 Check 404 HTTP Response

We setup our mock repository to return back null, which should trigger the 404 Not Found behavior.

PartialCommandUpdate Overview

PartialCommandUpdate Unit Tests

Even fewer tests here! As mentioned, when we implemented this endpoint, there are addition external dependencies required to get PATCH endpoints up and running. This cascades into unit testing too. The cost vs. benefit proposition of including the necessary inclusions to perform one unit test (testing for a 204 No Content) did not stack up for me and I assumed for you too as the reader! I have therefore included only one test below – the 404 Not Found Response.

Test 5.1 Check 404 HTTP Response

DeleteCommand Overview

DeleteCommand Unit Tests

Test 6.1 Check for 204 No Content HTTP Response

Test 6.2 Check for 404 Not Found HTTP Response