DEV Community: Jesús Rodríguez

Unit Testing - Pipes

Jesús Rodríguez — Sun, 12 Sep 2021 18:31:54 +0000

(To follow along, download the project from Github and use the master branch).

In the following sections we are going to develop a Calendar. It will allow us to see the current month or navigate to an specific date. As mentioned in the introduction, the Calendar is cumbersome to manually test. We need to check the current month to see that we don't have repeated or missing days. We need to check that the algorithm doesn't degrade if we generate a Calendar for a date in the future. We also need to check that the February of a leap and non leap years is generated correctly as well. Sounds like a waste of time in my book.

The first thing we are going to develop is the Calendar's header. We give it a date and we get something like September of 2021. Yes, we are speaking about a pipe here.

Pipes are the easiest component in Angular and they are also the easiest to test.

We are going to follow a TDD approach in this tutorials, so let's open our calendar.spec.ts and code a basic skeleton.

File: libs/calendar/src/calendar.pipe.spec.ts:

import { CalendarPipe } from './calendar.pipe';

describe('CalendarPipe', () => {
  let pipe: CalendarPipe;

  beforeEach(() => {
    pipe = new CalendarPipe();
  });
});

Here we are importing our pipe and creating an instance before each test. Let's code one test:

File: libs/calendar/src/calendar.pipe.spec.ts:

import { CalendarPipe } from './calendar.pipe';

describe('CalendarPipe', () => {
  let pipe: CalendarPipe;

  beforeEach(() => {
    pipe = new CalendarPipe();
  });

  it('transforms 2021/06 to "June of 2021"', () => {
    expect(pipe.transform('2021/06')).toBe('June of 2021');
  });
});

We defined our API for this pipe in the test. We use a string with the date and it returns us another string with the date in English.

Note: To run the test, type: npm run test:all -- --watch so it runs all tests and enables watch mode.

This obviously fails. Even when our pipe exists, it just returns null.

Let's code it:

File: libs/calendar/src/calendar.pipe.ts:

import { Pipe, PipeTransform } from '@angular/core';

@Pipe({
  name: 'calendar',
})
export class CalendarPipe implements PipeTransform {
  transform(value: string): string {
    const dateParts = value.split('/');

    const date = new Date(+dateParts[0], +dateParts[1]);

    return `${date.toLocaleDateString('en-us', { month: 'long'})} of ${date.getFullYear()}`;
  }
}

We split the date in two strings that we use to create a new date object. Then we construct a string out of it. The test pass correctly:

Ah, it doesn't.

...

Oh, I see, dates in Javascript are 0 based, so if we send 06 it means July and not June. Since it is a good practice to provide an easy API, we are going to modify our code so the API is not 0-based.

File: libs/calendar/src/calendar.pipe.ts:

transform(value: string): string {
  const dateParts = value.split('/');

  const date = new Date(+dateParts[0], +dateParts[1] - 1);

  return `${date.toLocaleDateString('en-us', { month: 'long'})} of ${date.getFullYear()}`;
}

Much better.

Fun fact: This API is quite odd. Having to split a string in two, cast the strings into numbers and then create a date object is well, not too smart. As we follow through this course, we will see many times that this API is horrible. This is a good proof that a well tested code doesn't imply that it is better or easier to use. It just means that it works as expected.

With our first test working, let's use the API in other ways to see if it behaves:

File: libs/calendar/src/calendar.pipe.ts:

it('transforms 2040/8 to "August of 2040"', () => {
  expect(pipe.transform('2040/8')).toBe('August of 2040');
});

Without the extra 0, it still works as expected.

What happens if we pass a malformed date?

File: libs/calendar/src/calendar.pipe.ts:

it('transforms 2021 to "Unknown date"', () => {
  expect(pipe.transform('2021')).toBe('Unknown Date');
});

Invalid Date of NaN. Yeah, that is what I get when I input my holidays. Jokes aside, let's fix that:

File: libs/calendar/src/calendar.pipe.ts:

import { Pipe, PipeTransform } from '@angular/core';

@Pipe({
  name: 'calendar'
})
export class CalendarPipe implements PipeTransform {
  transform(value: string): string {
    const dateParts = value.split('/');

    if (dateParts.length !== 2) { return 'Unknown Date'; }

    const date = new Date(+dateParts[0], +dateParts[1] - 1);

    return `${date.toLocaleDateString('en-us', { month: 'long' })} of ${date.getFullYear()}`;
  }
}

We simply check if the string is malformed and if so, we return an error string.

Conclusions

Testing pipes is really easy. It is not any different to our Calculator example. We instantiate it, we write some tests and that is it.

Next, we will code our Calendar's heart, the service.

Unit Testing - Spies and Mocks

Jesús Rodríguez — Sun, 25 Jul 2021 19:33:55 +0000

We have done a unit test of a calculator in the previous part. But we never mentioned what does unit means in unit test.

There are several ways to test our application:

Unit Test: We test one piece of code in isolation. That means, without its dependencies. A component without its services or the other components used in the template. A service without other services, etc.

Integration Test: Here we test that a several pieces works in conjunction. Some people agrees that testing that a component works with its template is considered an integration testing. But more on that in later parts.

End to End: In a end to end (e2e), we assert that our use cases works from start to finish. That means server calls, authentication and other stuff. We might talk about this in a different series.

In angular we want to do as many Unit Tests as possible because they are cheaper (to do and to maintain).

Let's see a new example. This time, we will focus on the tests.

(If you want to follow this, I have a codesandbox for you to work.)

This is a very contrived example but is what we need to keep learning.

Here we have a recipe service:

File: src/recipe.service.ts

export interface Recipe {
  name: string;
  ingredients: string[];
  cookTemperature: number;
  temperatureUnit: string;
  steps: string;
}

export class RecipeService {
  getRecipes() {
    // In a real world, this is calling some backend
    // through an API call
    return [
      {
        name: "Pizza",
        ingredients: ["Tomato", "Mozarella", "Basil"],
        cookTemperature: 500,
        temperatureUnit: 'F',
        steps: "Put in oven until it gets your desired doneness"
      }
    ];
  }
}

It has a method called getRecipes that returns a list of well, recipes. In a real world scenario this would be a real HTTP call. We don't need that here.

We also have a service that converts Fahrenheit to Celsius:

File: src/temperature.service.ts

export class TemperatureService {
  fahrenheitToCelsius(temperature: number): number {
    return ((temperature - 32) * 5) / 9;
  }
}

Nothing fancy.

And lastly, we have a component (again, contrived example, no template) that uses both services:

File: src/recipe.component.ts

import { Recipe, RecipeService } from "./recipe.service";
import { TemperatureService } from "./temperature.service";

export class RecipeComponent {
  recipes: Recipe[];

  constructor(
    private recipeService: RecipeService,
    private temperatureService: TemperatureService
  ) {}

  fetchRecipes() {
    this.recipes = this.recipeService.getRecipes();
  }

  printRecipesInCelsius() {
    return this.recipes.map((recipe) => {
      const cookTemperature = this.temperatureService.fahrenheitToCelsius(
        recipe.cookTemperature
      );
      return {
        ...recipe,
        temperatureUnit: 'C',
        cookTemperature
      };
    });
  }
}

The recipe component has a reference to our two services. One method that fetch the recipes from our service to store them locally and a method that returns a new list but with the temperature in celsius.

We are asked to unit test this component class. Ok, let's open our code spec file and let's write the basic skeleton:

File: src/recipe.component.spec.ts

import { RecipeComponent } from "./recipe.component";

describe("RecipeComponent", () => {
  let component: RecipeComponent;

  beforeEach(() => {
    component = /* what goes here? */
  });
});

Before we jump into "Obviously we need to pass an instance of both services" let's think a bit.

What does this component? It holds a list of recipes, a method that fetches the recipes and a method that returns the recipes in celsius.

That is it, it doesn't care where how the recipes are fetched in the service. It only cares that recipeService.getRecipes() returns a list of recipes. We have to assume that the service itself is tested. The component boundaries ends on "I call this method in the server that is supposed to return me recipes".

With that said, if we pass an instance of RecipeService into our component we are coupling our tests with a real service. If that service calls a slow third party backend to fetch recipes, our tests won't be fast nor reliable.

In other words, we can't use the real RecipeService here because it will only add complexity to our test, and as I said at the beginning, in a unit test, we need to test our piece of code in isolation.

Alright, but how do we make this code work without using the real deal?

Mocks

A mock is an object that mimics another object for testing. It has the same interface as the real one but its implementation is way simpler or even empty.

That sounds extrange, so let's see it in action:

File: src/recipe.component.spec.ts

import { RecipeComponent } from "./recipe.component";
import { RecipeService } from "./recipe.service";

const recipeServiceMock: RecipeService = {
  getRecipes: () => []
}

describe("RecipeComponent", () => {
  let component: RecipeComponent;

  beforeEach(() => {
    // ommited for now
  });
});

Our recipeServiceMock is a mock of RecipeService. It has the same interface (the getRecipes method). It just returns an empty array. And that is perfectly fine. We just need to know that its methods are used by our SUT (subject under test, AKA the piece of code we are testing).

Now we can use that mock when creating our component for testing:

File: src/recipe.component.spec.ts

describe("RecipeComponent", () => {
  let component: RecipeComponent;

  beforeEach(() => {
    component = new RecipeComponent(recipeServiceMock, ...)
  });
});

Good, we just need to do the same with TemperatureService.

File: src/recipe.component.spec.ts

import { RecipeComponent } from "./recipe.component";
import { RecipeService } from "./recipe.service";
import { TemperatureService } from "./temperature.service";

const recipeServiceMock: RecipeService = {
  getRecipes: () => []
}

const temperatureServiceMock: TemperatureService = {
  fahrenheitToCelsius: () => 0
}

describe("RecipeComponent", () => {
  let component: RecipeComponent;

  beforeEach(() => {
    component = new RecipeComponent(recipeServiceMock, temperatureServiceMock);
  });
});

With our skeleton ready, let's do a first test. We want to make sure that it calls the service to fetch the recipes:

File: src/recipe.component.spec.ts

it("calls a service to fetch the recipes", () => {
  component.fetchRecipes();
});

Wait a second, we are simply calling the fetchRecipes method, that yes, it is supposed to call the service. But we aren't sure. How can we assert this?

Spies

Spies allows us to record information on how a function were called. We can see how many times a function has been called, if parameters were used...

That is perfect. It is just what we need, isn't it? Jest has a method that creates an spy for us:

File: src/recipe.component.spec.ts

import { RecipeComponent } from "./recipe.component";
import { RecipeService } from "./recipe.service";
import { TemperatureService } from "./temperature.service";

const recipeServiceMock: RecipeService = {
  getRecipes: jest.fn()
}

const temperatureServiceMock: TemperatureService = {
  fahrenheitToCelsius: jest.fn()
}

Now both getRecipes and fahrenheitToCelsius are empty functions like before, but decorated with spying technology.

Thanks to that, we can update our test as follows:

File: src/recipe.component.spec.ts

it("calls a service to fetch the recipes", () => {
  component.fetchRecipes();

  expect(recipeServiceMock.getRecipes).toHaveBeenCalled();
});

Here we say: We call fetchRecipes and we expect getRecipes from our RecipeService to have been called.

Does our test pass?

It sure does. How is the service going to fetch the recipes for us? We don't care. I just need to know that my component is calling the right method at the right time. No service's code was even executed here.

Ok, while that is true and many of our tests are as simple as that, the real implementation returns a list of recipes that we store in our component. We need to test that as well because even if the service was called, we might have forgotten to assign the result to a variable.

Let's augment our mock to both spy and return recipes.

File: src/recipe.component.spec.ts

import { RecipeComponent } from "./recipe.component";
import { Recipe, RecipeService } from "./recipe.service";
import { TemperatureService } from "./temperature.service";

const recipes: Recipe[] = [
  {
    name: "Chicken with cream",
    ingredients: ["chicken", "whipping cream", "olives"],
    cookTemperature: 400,
    temperatureUnit: 'F',
    steps: "Cook the chicken and put in the oven for 25 minutes"
  }
];

const recipeServiceMock: RecipeService = {
  getRecipes: jest.fn().mockReturnValue(recipes)
};

First we created a mock recipe and then we added the .mockReturnValue to our spy so it also returns a value.

Now we can add a new expectation to our test.

File: src/recipe.component.spec.ts

it("calls a service to fetch the recipes", () => {
  component.fetchRecipes();

  expect(component.recipes).toBe(recipes);
  expect(recipeServiceMock.getRecipes).toHaveBeenCalled();
});

Tests still pass. So we now assert that the service gets called and that the recipes are assigned locally.

NOTE: We can have as many expectations as we need in a single test. It is not limited to just one.

For our second test, we want to make sure that we can get our recipes with the temperature in celsius.

File: src/recipe.component.spec.ts

it('can print the recipes with celsius using a service', () => {
  component.fetchRecipes();

  expect(component.recipes[0].cookTemperature).toBe(400);
  expect(component.recipes[0].temperatureUnit).toBe('F');

  const recipesInCelsius = component.printRecipesInCelsius();

  const recipe = recipesInCelsius.pop();

  expect(recipe.cookTemperature).not.toBe(400);
  expect(recipe.temperatureUnit).toBe('C');

  expect(temperatureServiceMock.fahrenheitToCelsius).toHaveBeenCalledWith(400);
});

Let's go step by step. First we call fetchRecipes to populate the component's recipes. Then before we do any change, we assert that the current temperature and unit are the default ones.

Next, we call printRecipesInCelsius and we assert that the cookTemperature is no longer 400 (we don't care about the exact number in this test. We assume that is tested in the service's tests) and also that the unit is 'C'.

Lastly, we want to know that the service was called with the correct parameter.

This test is also passing.

At this point we are really done. We have tested that our component uses the services in the correct way but we are not meddling in how they do it.

Do we always need to mock?

Ha, good question. There are different answers depending to whom you ask. I believe that if a service is THAT simple, we shouldn't worry about mocking it. Surely the real RecipeService would use HTTP calls to retrieve the recipes, but the TemperatureService is that simple that it won't affect our tests at all.

In other words, if a service is small, has no dependencies and runs fast, we can decide not to mock it at all.

Let's update our code to not use a mock for temperature:

File: src/recipe.component.spec.ts

const recipeServiceMock: RecipeService = {
  getRecipes: jest.fn().mockReturnValue(recipes)
};

const temperatureService = new TemperatureService();

describe("RecipeComponent", () => {
  let component: RecipeComponent;

  beforeEach(() => {
    component = new RecipeComponent(recipeServiceMock, temperatureService);
  });

Here we just instantiate our original TemperatureService. For this to work, we need to comment out a line of our test.

File: src/recipe.component.spec.ts

it('can print the recipes with celsius using a service', () => {
  component.fetchRecipes();

  expect(component.recipes[0].cookTemperature).toBe(400);
  expect(component.recipes[0].temperatureUnit).toBe('F');

  const recipesInCelsius = component.printRecipesInCelsius();

  const recipe = recipesInCelsius.pop();

  expect(recipe.cookTemperature).not.toBe(400);
  expect(recipe.temperatureUnit).toBe('C');

  // expect(temperatureServiceMock.fahrenheitToCelsius).toHaveBeenCalledWith(400);
});

Since it is not a mock anymore, we cannot do that.

But isn't this solution now worse? At least before we made sure that the service was called and now we cannot do that anymore. Right. We can spy on the real service as we did before.

File: src/recipe.component.spec.ts

it('can print the recipes with celsius using a service', () => {
  jest.spyOn(temperatureService, 'fahrenheitToCelsius');
  component.fetchRecipes();

  expect(component.recipes[0].cookTemperature).toBe(400);
  expect(component.recipes[0].temperatureUnit).toBe('F');

  const recipesInCelsius = component.printRecipesInCelsius();

  const recipe = recipesInCelsius.pop();

  expect(recipe.cookTemperature).not.toBe(400);
  expect(recipe.temperatureUnit).toBe('C');

  expect(temperatureService.fahrenheitToCelsius).toHaveBeenCalledWith(400);
});

jest.spyOn is the same as using jest.fn before but applied to an existing method. In this case it will also call the real service, but as we said before, it is small and simple so it doesn't really matter.

Conclusions

When doing unit testing, we need to mock out some of our dependencies so the focus of our testing is just the piece of code we are testing and not its dependencies.

In the tests, we make sure that our code is doing what it is supposed to do and also that it is using it's dependencies in the right way and also in the exact moment.

If one of the dependencies is too small, has no dependencies and it is fast, we could simply use the real one.

In the next section, we will start our Angular component.

Unit Testing - Introduction

Jesús Rodríguez — Sat, 24 Jul 2021 16:20:46 +0000

Let's talk about unit testing our applications.

What is unit testing and why should I care?

Unit tests are a bunch of Typescript files that we create to make sure that every part of our application works as it is expected to work. That means that we need to write hundred of lines of code to assert that our code does what is supposed to do.

Isn't that a waste of time? The boss is always telling us that we need to be faster and hundred of lines doesn't sound like fast. Au contraire, that bunch of code will save us HOURS. Don't believe me? I have proofs.
Extra code: How many times did you end with code that is not used? Maybe we added some extra loops that are not needed or some function to do something and then realize that we are not using it. When we code our modules before any test, we don't actually know what we are going to need or if our algorithm is going to support any kind of input (that could lead to those extra loops). More code means more stuff to maintain which also means, more money.
Bad API design: Maybe we need to create a new service to do something, and then we start writing functions to do the work and we put some of them public to define the service's API. Good, that is the idea isn't it? Some time after we get complaints about our really poor API that well, it is not as intuitive as we expected. In this category also goes those API functions that are not really needed (which is also extra code).
Refactor: What happens when we want to refactor our code? We are in big trouble. Even when we decide to not break the API, maybe that internal change is not working properly on some edge cases where it worked in the past. That will break the application for some people and they won't be happy at all (and those kind of bugs are normally a pain to debug).
Will it work: That is the end goal and probably the biggest time waster of anything you have to do in your applicaton. Something as simple as a calendar, involves some maths and some magic numbers to make it work. We really need to be sure it works. How? We open a certain date, we manually check with our OS calendar to see if it matches. We repeat that for some random dates (old ones, future ones). Then we change something in our service and well, we need to check the dates again to assert that nothing is broken. Repeat that 20 times for a normal service development.

How does the unit test help?

Ok, you convinced me that maybe I was wrong about not doing unit testing. But how can it help with those problems? What if we see a really simple example? (General example, not Angular related and it will be in a really slow peace to make the point).

Let's say I want an object which will be able to do some basic maths (Addition and Division). Your first thought is to start writing a class with some methods to do some math. We will end doing something like that, but what we are going to do is to test it first. Test it first? Why? Bear with me.

(If you want to follow this, I have a codesandbox for you to work.)

This codesandbox (and the Angular app that we will test in the next sections) uses Jest. Jest is a testing framework that can be used for any Javascript / Typescript project.

Our object should be able to sum 5 and 3and get 8. Let's test that.

File: src/calculator.spec.ts

describe('Calculator', () => {
  it('should be able to sum 5 and 3 to return 8', () => {
    // Arrange
    const calc = new Calculator();

    // Act
    const result = calc.sum(5, 3);

    // Assert
    expect(result).toBe(8);
  });
});

Before we even look at the Tests tab at codesandbox, let's talk about this piece of code.

First we see that this looks like something between English and Typescript. Testing is meant to be something that is easy to read and easy to understand and just by reading the code, we get an idea of what it does:

"Describe a calculator. It should be able to run 5 and 3 to return 8. Create a calculator object, call a method and expect the result to be 8.".

Now back to technical details, tests are wrapped into describe functions. They are used to group our tests. The actual tests are functions called it where we actually code our tests.

Inside those it functions, we follow a pattern called AAA (Arrange, Act, Assert). With those 3 steps, we successfully write a test.

In this example, we are Arranging by creating a Calculator object, then Acting by calling it's sum method and Asserting by checking its result with our expected result.

Alright, but what is the result of this test?

Kind of expected, isn't it? We wrote our test before we even created our Calculator class.

Something interesting to notice here is how are we designing our API before we even coded it. We say that we want a sum method before we created the class.

Let's fix this, Shall we?

File: src/calculator.ts

export class Calculator {
  sum(num1: number, num2: number): number {
    return 8;
  }
}

And also let's import it to our spec file:

File: src/Calculator.spec.ts:

import { Calculator } from './calculator';

describe('Calculator', () => {
  ...
});

What does our test says now?

But... That is definitely not right, isn't it? We hardcoded the result 8 into the method. That way our tests surely pass.

We have to code the minimum possible code to make our tests pass. I understand that this is a contrived example and we already know that this implementation is not enough, but in a real world scenario (as we will see in the next sections) you may not know when an implementation is enough or not, so our job is to make a test pass as simple as possible, as we did in here.

Since we may not be sure that this implementation is enough, we have to write more tests:

File: src/calculator.spec.ts

it('should be able to sum a number with 0', () => {
  const calc = new Calculator();

  const result = calc.sum(7, 0);

  expect(result).toBe(7);
});

If we see the test tab we see:

1 test failed, 1 test passed. And we can see where it failed and why. We expected the result of 7 but we got 8. That means that something is wrong with our code.

This solves our Will it work? dilemma. We can immediately see that our code doesn't really work, so we need to fix it so all our test passes.

Let's fix it:

File: src/calculator.ts

export class Calculator {
  sum(num1: number, num2: number): number {
    return num1 + num2;
  }
}

Now our tests says:

Before we move on, let's take a peek to our current spec file:

import { Calculator } from './calculator';

describe('Calculator', () => {
  it('should be able to sum 5 and 3 to return 8', () => {
    // Arrange
    const calc = new Calculator();

    // Act
    const result = calc.sum(5, 3);

    // Assert
    expect(result).toBe(8);
  });

  it('should be able to sum a number with 0', () => {
    const calc = new Calculator();

    const result = calc.sum(7, 0);

    expect(result).toBe(7);
  });
});

First, notice here that every it in our spec file is completely independent of the others. They run independently and you should never ever rely on the way they are ordered to "start something in one one them" and "assert in the other". In fact, Jest may run the it in a random order to avoid dependency between them.

Also, look at the code. There is some repetition in it. The DRY (don't repeat yourself) principle doesn't apply as strongly as it does in our application code. We are allowed to repeat some code for the sake of testing, but that doesn't mean that we should repeat all our code.

In this case we are repeating our Arrange part in those two tests, and if we have 20 of them, we are going to repeat it 20 times. We can do better.

There is a method called beforeEach that runs before each it function. There we can setup whatever we need for each test. Let's Arrange our code there so we have access to calc in each test.

Let's look at the new code:

File: src/calculator.spec.ts:

import { Calculator } from './calculator';

describe('Calculator', () => {
  let calc: Calculator;

  beforeEach(() => {
    // Arrange
    calc = new Calculator();
  });

  it('should be able to sum 5 and 3 to return 8', () => {
    // Act
    const result = calc.sum(5, 3);

    // Assert
    expect(result).toBe(8);
  });

  it('should be able to sum a number with 0', () => {
    const result = calc.sum(7, 0);

    expect(result).toBe(7);
  });
});

This is a test refactor. We should only do them when all our tests are green, to be sure that it doesn't break anything.

So far so good, let's throw more different scenarios to see it behaves correctly:

it('should be able to sum a negative number for a positive result', () => {
  const result = calc.sum(7, -3);

  expect(result).toBe(4);
});

it('should be able to rum a negatrive number for a negative result', () => {
  expect(calc.sum(-20, 7)).toBe(-13);
});

Notice how I wrote two lines in one in the last example. It is still readable so it is good in my book.

Seems like our code handles this two use cases correctly.

Now, let's move to division, but before we do that, we could group or sum test in their own describe like this:

File: src/calculator.spec.ts:

import { Calculator } from './calculator';

describe('Calculator', () => {
  let calc: Calculator;

  beforeEach(() => {
    // Arrange
    calc = new Calculator();
  });

  describe('#sum', () => {
    it('should be able to sum 5 and 3 to return 8', () => {
      // Act
      const result = calc.sum(5, 3);

      // Assert
      expect(result).toBe(8);
    });

    it('should be able to sum a number with 0', () => {
      const result = calc.sum(7, 0);

      expect(result).toBe(7);
    });

    it('should be able to sum a negative number for a positive result', () => {
      const result = calc.sum(7, -3);

      expect(result).toBe(4);
    });

    it('should be able to rum a negatrive number for a negative result', () => {
      expect(calc.sum(-20, 7)).toBe(-13);
    });
  });
});

We can anidate as many describe as we need. Also notice the # at #sum. It is a convention that says that we are testing a method.

Now let's create a new describe for a division with a simple test:

File: src/calculator.spec.ts:

    it('should be able to rum a negatrive number for a negative result', () => {
      expect(calc.sum(-20, 7)).toBe(-13);
    });
  });

describe('#division', () => {
  it('should be able to do an exact division', () => {
    const result = calc.division(20, 2);

    expect(result).toBe(10);
  });
});

It fails:

What a surprise. Let's fix it real quick:

File: src/calculator.ts:

export class Calculator {
  sum(num1: number, num2: number): number {
    return num1 + num2;
  }

  division(num1: number, num2: number): number {
    return num1 / num2;
  }
}

This time with the application requisites a bit clearer, we wrote a better division method.

We don't want or Calculator to deal with decimals, because who likes decimal anyway?

File: src/calculator.spec.ts:

it('returns a rounded result for a non exact division', () => {
  expect(calc.division(20, 3)).toBe(7)
});

Apparently Typescript does like them.

Let's fix that.

File: src/calculator.spec.ts:

export class Calculator {
  sum(num1: number, num2: number): number {
    return num1 + num2;
  }

  division(num1: number, num2: number): number {
    return Math.round(num1 / num2);
  }
}

Yay, not only in rounds numbers now, but our other test still works as expected.

Now we want to throw an exception if we divide something by 0.

File: src/calculator.spec.ts:

it('throws an exception if we divide by 0', () => {
  expect(() => 
    calc.division(5, 0)
  ).toThrow('Division by 0 not allowed.');
});

This test looks different. Instead of passing a variable to expect, we are passing a function. The idea is something like "We expect that when running this function, an exception will be thrown". Since division won't be able to return anything if it throws an exception, we cannot test the result as we previously did.

This test obviously fails:

Let's see our code before we change it:

File: spec/calculator.ts:

export class Calculator {
  sum(num1: number, num2: number): number {
    return num1 + num2;
  }

  division(num1: number, num2: number): number {
    return Math.round(num1 / num2);
  }
}

Division by 0 happened when divisor is 0 but... which is which in our code? Let's refactor our code, but before we do that, we need our tests to pass and we have one that is failing. What we can do is "skip" the test until we refactor:

File: src/calculator.spec.ts:

xit('throws an exception if we divide by 0', () => {
  expect(() => 
    calc.division(5, 0)
  ).toThrow('Division by 0 not allowed.');
});

Notice the xit. We use this as a way to "ignore" a test. We can always comment out the code, but that way we may forget that we had a test to fix. With xit we can see that it exist but that it was skipped.

NOTE: codesandbox doesn't manage this xit very well, but at least it says that there are no failing tests

Now we our broken test ignored, let's refactor our code:

export class Calculator {
  sum(num1: number, num2: number): number {
    return num1 + num2;
  }

  division(dividend: number, divisor: number): number {
    return Math.round(dividend / divisor);
  }
}

Much better and tests still pass:

NOTE: As mentioned, codesandbox doesn't manage this well and you may see a red X saying failed but all correct in the summary, that is fine.

That is a code refactor without the fear of breaking any feature.

Now swap the xit for it again:

File: src/calculator.spec.ts:

it('throws an exception if we divide by 0', () => {
  expect(() => 
    calc.division(5, 0)
  ).toThrow('Division by 0 not allowed.');
});

And let's fix the code:

export class Calculator {
  sum(num1: number, num2: number): number {
    return num1 + num2;
  }

  division(dividend: number, divisor: number): number {
    if (divisor === 0) {
      throw new Error('Division by 0 not allowed.');
    }
    return Math.round(dividend / divisor);
  }
}

And that is it! Congratulations, you just wrote your first test suite.

Conclusions of this example

Even when it is really really simple example. We already saw how we can address those problems I described earlier:

Our calculator doesn't have any extra code because we coded just what we needed to make our calculator work. Its API design is good enough, that is because we used it as we would like to use it on the real world. Will it work? Sure, I have a bunch of tests that proves that. What about refactor? Go ahead, if the tests still pass, then you're doing good.

Maybe you won't notice it with this example, but with proper tests, you will save a lot of hours maintaining extra code, dealing with API design with hopefully won't end on breaking changes, refactoring code without fear and of course being sure that your code will work.

Testing is your friend, and with little effort on it, will save us real pain.

See you in the next section where we will dive into mock and spies to then test an Angular component from scratch.

Mocking with MSW and Nx

Jesús Rodríguez — Mon, 14 Jun 2021 06:48:33 +0000

We are sitting in front of our new project and we need to start coding some new screens but the backend is just not ready yet. Isn't that familiar?

It is a good practice to have some sort of mocking mechanism so we can start coding as soon as we can and also make our unit testing less error prone by using well known data.

Yes, but that sounds overly complicated to achieve. We need to turn off and on the backend, swap modules around to enable or disable the mocking and be careful to not deploy any of that the production.

Well, not anymore.

Introducing MSW

MSW as they say, is the API mocking of the next generation. Right, but what does that mean? It works by intercepting requests on the network level or in other words, by using a service worker.

The interesting part is that it is invisible for us, developers. Isn't that great?

Creating our project using NX

There is no other reason of using NX other than it being awesome. Everything we are going to see here works with Angular CLI as well.

Let's create a new workspace with an Angular + Nest projects. The fact we are going to mock the backend doesn't mean we don't need a backend... eventually.



$ npx create-nx-workspace msw-tutorial

When asked, select angular-nest and call the application whatever you want, I used spa. Then choose CSS (we are not going to do styles here) and No for the cloud.

Open the workspace in your ~~favorite editor~~ vscode and also run both the spa and the api:



$ npx nx serve



$ npx nx serve api

You need two terminal open for this.

Once it finish, we can navigate to http://localhost:4200 and then see:

That Message at the bottom is a message from our API. We can open apps/api/src/app/app.controller.ts if we want to take a look.

Setting up the environment for MSW

With our app working, let's set up MSW.

First, let's install it:



$ npm i -D msw

MSW depends on a service worker being installed, so let's create it first:



$ npx msw init apps/spa/src

This will copy the mockServiceWorker.js inside the spa project. You can copy it in a different place if needed, but for the sake of this tutorial, let's assume we installed it there. If asked to save the directory in the package.json, feel free to say no. We don't need it.

Our next step is register this mockServiceWorker.js within Angular. For that, open angular.json and update it:



"options": {
  "outputPath": "dist/apps/spa",
  "index": "apps/spa/src/index.html",
  "main": "apps/spa/src/main.ts",
  "polyfills": "apps/spa/src/polyfills.ts",
  "tsConfig": "apps/spa/tsconfig.app.json",
  "assets": [
    "apps/spa/src/favicon.ico",
    "apps/spa/src/assets",
    "apps/spa/src/mockServiceWorker.js"
  ],
  "styles": [
    "apps/spa/src/styles.css"
  ],
  "scripts": []
},

Now when MSW ask for this service worker to be installed, Angular will be able to locale it.

Our next question is: When do we want to use mocking? Certainly not in production and sometimes at development. A common pattern is to create another environment called mock.

First, let's update again our angular.json to add a new configuration:



"development": {
  "buildOptimizer": false,
  "optimization": false,
  "vendorChunk": true,
  "extractLicenses": false,
  "sourceMap": true,
  "namedChunks": true
},
"mock": {
  "buildOptimizer": false,
  "optimization": false,
  "vendorChunk": true,
  "extractLicenses": false,
  "sourceMap": true,
  "namedChunks": true,
  "fileReplacements": [
    {
      "replace": "apps/spa/src/environments/environment.ts",
      "with": "apps/spa/src/environments/environment.mock.ts"
    }
  ]
}

It is a copy of development but adding a new environment.mock.ts file. So let's add it to apps/spa/src/environments:

File: environment.mock.ts



export const environment = {
  production: false,
};

To make things easier, let's create a new script:

File: package.json



"scripts": {
    "ng": "nx",
    "postinstall": "node ./decorate-angular-cli.js && ngcc --properties es2015 browser module main",
    "nx": "nx",
    "start": "ng serve",
    "start-mock": "ng serve spa --configuration mock",
    "build": "ng build",

To be able to serve the app with this new mock configuration, we have to add it to the angular.json:



"development": {
  "browserTarget": "spa:build:development"
},
"mock": {
  "browserTarget": "spa:build:mock"
}

Creating our MSW configuration

Now with our environment set up, the next thing is create our actual mock, right? Since we are using NX, let's create a new library:



$ npx nx g @nrwl/workspace:library --name=mock-api --skipBabelrc --unitTestRunner=none

Let's delete libs/mock-api/src/lib/mock-api.ts and create there:

File: handlers.ts



export const handlers = [];

File: browser.ts



import { setupWorker } from 'msw';
import { handlers } from './handlers';

export const worker = setupWorker(...handlers);

Also update libs/mock-api/src/index.ts:



export * from './lib/browser';

At handlers we configure all the network calls we want to mock and at browser.ts we create a worker object that we can use to start MSW with our handlers.

Where should we start MSW? Since we only want to run it in mock mode, let's update apps/spa/src/environments/environments.mock.ts:



import { worker } from '@msw-tutorial/mock-api';

worker.start({
  onUnhandledRequest: 'bypass',
});

export const environment = {
  production: false,
};

Here we made an important decision. What do we do with all those requests that are not handled by our mock? We bypass it to the real deal. By doing this, we can be selective with the mocks we want to have.

Now, we run our backend and frontend again:



$ npm run start-mock



$ npx nx serve api

Only that this time we are using our new start-mock script.

If we now open our site again at http://localhost:4200 we see, well, the exact same page:

But if we open the console, we can see:

MSW seems to be enabled and working. It is just that we haven't create a mock handler yet.

Before we move on, you may notice a warning in the console about one file that depends on 'debug'. If that is the case, open the angular.json and update it as follows:



"options": {
  "outputPath": "dist/apps/spa",
  "index": "apps/spa/src/index.html",
  "main": "apps/spa/src/main.ts",
  "polyfills": "apps/spa/src/polyfills.ts",
  "tsConfig": "apps/spa/tsconfig.app.json",
  "assets": [
    "apps/spa/src/favicon.ico",
    "apps/spa/src/assets",
    "apps/spa/src/mockServiceWorker.js"
  ],
  "allowedCommonJsDependencies": [
    "debug"
  ],

In any case, let's create our first mock route. If we check our app.component we can see:



@Component({
  selector: 'msw-tutorial-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent {
  hello$ = this.http.get<Message>('/api/hello');
  constructor(private http: HttpClient) {}
}

We see, first, very bad practices by including a HTTP call here, but then we see that it is calling /api/hello.

Let's add a handler:

File: handlers.ts



import { rest } from 'msw';

export const handlers = [
  rest.get('/api/hello', async (req, res, ctx) => {
    return res(ctx.json({ message: 'Msw works like a charm!' }));
  }),
];

This looks like pretty much like express.

If now we open our page again, we see:

That is our mock!!

And if we check the console, we can see:

This is just, perfect.

Go ahead and restart your app in development mode:



$ npx nx serve

What do we see? No mock trace anywhere at all.

Conclusion

MSW is an easy way to add a mocking layer in an application. We can deliberately decide if we want to mock everything or just part of the application.

Once configured, we just need to add as many handlers as we need for our mocking purposes and we can go as complex as we need there. We can have a json "database" with fake data, or use faker for example.

But the best part is that it is completely invisible for Angular. We don't need to mock any service to make it work or be sure that we are not leaving any "flag" on before we deploy to production.

We can also leverage this mocking in our e2e without having to do anything at all. Since e2e depends on a running app, as long as we run it using our mock configuration, our e2e tests will use this mock data.

For unit test, we can use our mock as well, but I still think that unit test shouldn't bother with real calls, whether or not they are mock or real.

You can grab the final example from github.