Learn how to make your application stable and bug-free with unit testing with Jest.

Unit Testing with Jest

Now that we have a module set up with our mocked function it's time to use it within our Jest test for `findRecipe()`. Remember, we want to replace the actual `apiRequest()` function with the mocked one we created!

Let's take a look at the steps to use a function that we've created in our **\_\_mocks\_\_/** directory in our tests. 

1. First, in the test file, we import the real function. This allows the test to work as it would otherwise if no mock existed. 

2. Then use the `jest.mock()` function provided by Jest to override the value with the mocked one defined in the **\_\_mocks\_\_/** folder. `jest.mock()` accepts a string as an argument that should match the filepath to the file being mocked.

> Note: This second step is only required when mocking local modules. When mocking modules installed into the `node_modules` directory, the module will automatically be mocked when it is imported in step 1.

```js
// import the actual module
import apiRequest from './api-request.js';

// then tell Jest to use the mocked version!
jest.mock('./api-request.js');
```

Following these steps will cause any `apiRequest()` function calls made in the Jest tests to use the mocked version instead. 

We can also further manipulate how specific methods in the mocked module behave by using special methods attached to functions mocked with `jest.fn()`. One of these methods is `mockFunction.mockResolvedValueOnce()`, which accepts a value that the next call to `mockFunction()` will resolve to.

```js
// file: __tests__/recipes.js

import { findRecipe } from './recipes.js'; 

// import the actual module
import apiRequest from './api-request.js';

// then tell Jest to use the mocked version!
jest.mock('./api-request.js');

test("get the full recipe for a dish", async () => {
  // arrange  
  const dish = "Pesto";
  const expectedValue = { "Magical Deliciousness": "3 cups" };

  // set the resolved value for the next call to apiRequest  
  const mockResponse = {
    status: "mock",
    data: { "Magical Deliciousness": "3 cups" }
  }
  apiRequest.mockResolvedValueOnce(mockResponse);

  // act  
  const actualRecipe = await findRecipe(dish);
 
  // assertion
  expect(actualRecipe).toEqual(expectedValue);
});
```   

In the example above, the `.mockResolvedValueOnce()` method is used to determine what the next call to the `apiRequest()` function will resolve to. This method may be called any number of times in a test and may be useful if you'd like to finely control what each call to your mocked function resolves to.

There are many other methods available for controlling mocked functions. To see a full list of these methods, check out the [Jest documentation](https://jestjs.io/docs/mock-function-api).

Mocking with Jest (Part 2)

We will now explore testing functions that return a [Promise](https://www.codecademy.com/learn/asynchronous-javascript/modules/javascript-promises). Let's return to the `findRecipe()` function altered slightly. Instead of passing the fetched data to a callback, the function will now return a Promise. We now can use this function, along with the `await` keyword, like so:

```js
const recipe = await findRecipe('pesto');
console.log(recipe);
/* 
Prints {
  'Basil': '2 cups',
  'Pine Nuts': '2 tablespoons',
  'Garlic': '2 cloves',
  'Olive Oil': '0.5 cups',
  'Grated Parmesan': '0.5 cups'
}
*/
```

Jest supports the use of the `async` and `await` keywords, making handling Promises a breeze! Our test for the `findRecipe()` function can now be written like so:

```js
test("get the full recipe for pesto", async () => {
  //arrange
  const dish = "Pesto"
  const expectedRecipe = {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  }
 
  //act  
  const actualRecipe = await findRecipe(dish);
  
  //assertion
  expect(actualRecipe).toEqual(expectedRecipe);
});
```

Remember, when using the `async` and `await` keywords, the `async` keyword is placed before the function that contains asynchronous code. In this case, that would be the callback passed to `test()`. Then, the `await` keyword is placed in front of the asynchronous function call `findRecipe()`.

With the inclusion of the `async`/`await` keywords, Jest will wait for any `await` statement to resolve before continuing on.

Testing Async Code with Jest (Part 2)

Over the past few exercises, we have been analyzing the `findRecipe()` function which makes an REST API call to fetch the recipe data. Testing with a real REST API is not ideal for a few reasons:

* We aren't concerned about whether the third-party API works. Instead, we only care about whether or not the function that performs the API call works.
* Incorporating REST API calls into our tests can create fragile tests that may fail simply due to network issues. 
* If we were interacting with a production-grade database, we could accidentally alter official data. 

A safer and more efficient way to write our tests would be to create a mock function that bypasses the API call and returns values that we control instead. Luckily, Jest provides us with a way to mock functions and even entire modules to do just that! 

Creating the mock function and then replacing the real function with the mocked one requires two separate steps. For the sake of clarity, we will break down this process over this exercise and the next. First, let's go over the steps to create a mocked function. 

1. First we need to create a directory labeled **\_\_mocks\_\_/** in the same directory as the module that we want to mock. Later on, Jest will know to look for this directory when mocking the specified module.
2. Next, inside the directory, we create a file with the same name as the module that will be mocked. 
3. Then, we create a module with the functionality that we want. Functions that we want to mock can be created using `jest.fn()` – the function provided by the Jest library for creating [mock functions](https://jestjs.io/docs/mock-function-api).
4. Lastly, we export the module.

The function that makes the API call is called `apiRequest()` and it is exported from a file called **utils/api-request.js**. To mock this file and the `apiRequest()` function, we might write something like this:

```js
// file: utils/__mocks__/api-request.js
const apiRequest = jest.fn(() => {
  return Promise.resolve({ 
    status: "", 
    data: {} 
  });
});

export default apiRequest;
```    
Let's break down this example:
* Since we are mocking the **utils/api-request.js** file, we created a file called **utils/\_\_mocks\_\_/api-request.js**. 
* Inside, we declared an `apiRequest()` function that is assigned a value of `jest.fn()`. 
* By passing a callback function to `jest.fn()`, we can define the behavior of the mocked function. In this case, we have the mocked function return a custom Promise that matches the structure expected by our application (an object with `status` and `data` properties). 
* Lastly, we export `apiRequest` as the default export.  

In the next exercise, we'll see how we can replace the actual `apiRequest()` function with our mocked version and even further define how our mock function will behave within our tests. For now, however, let's practice making a mock function!

Mocking with Jest (Part 1)

Before we move on to actually writing our tests, we should cover a few best practices. 

By default, each test produces the terminal output that we saw in the previous exercise. Jest allows us to customize this output by using command line flags. Though there are many [command-line flags](https://jestjs.io/docs/cli#reference), one of the most commonly used is the `--coverage` flag:

```jest __tests__/ --coverage```

This `--coverage` flag allows us to get a report of which lines of our code were actually tested. In addition to being outputted in the terminal, this report becomes available in a directory named **coverage/** that is created at runtime. 

![jest coverage report](https://static-assets.codecademy.com/Courses/jest/jest_3_1.png)

This report can help us make sure that our code has been thoroughly tested.  From the report, we can see that there are four categories of our code that are being analyzed:
 
- **Statement** coverage analyzes the percentage of the program’s statements that have been executed.
- **Branch**  coverage analyzes the percentage of the program’s edge cases that have executed.
- **Function** coverage analyzes the percent of the program’s functions that have been called during testing. 
- **Line** coverage analyzes the percentage of the program’s executable lines in the source file that have been executed.

Currently, each of those sections will show up at 0% coverage which makes sense – we haven't written any tests yet! Strategies for interpreting and analyzing this coverage report are outside of the scope of this lesson, however, you should keep an eye on how this report changes as we continue to write our tests.

Though the coverage report is incredibly useful, it can be annoying to type out the full command every time we want to run our tests! Therefore, it is a good practice to preconfigure our test commands in our **package.json** file to allow us to run tests through `npm` with a simple terminal command. 

To do this, we set up the `"test"` script in our **package.json** file's `"scripts"` property:

```js
"scripts": {
  // other scripts...
  "test": "jest __tests__/ --coverage"
}
``` 

We can now run tests on all of our Jest test files while also creating a coverage report by running this terminal command:

```npm test```

In the future, if we wanted to change how we run our tests, we could adjust the **package.json** file and then continue using the `npm test` command. At any point, we are still able to use `jest` commands directly in the terminal. 

Configuring Jest

Now that Jest is installed and configured it is time to set up our first unit test. A unit test is designed to test the smallest unit of your code, like a single function. 

Let's consider testing some functions from a module called `recipes.js`. This module has two functions we'd like to test:
* `findRecipe()` takes a name of a recipe and makes an API call to find the specified recipe. When the request resolves, the provided callback is executed with the fetched data. The data will be an object containing ingredients and their quantities for the recipe.
*`getIngredients()` converts an object retrieved using `findRecipe()` into an array of just the ingredients. 

Below, we can see an example of how these functions might be used (the actual implementation of them isn't important):

```js
import { findRecipe, getIngredients } from './recipes.js';
 
findRecipe('pesto', (recipe) => {
  console.log(recipe);
  /* 
  Prints {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  }
  */

  console.log(getIngredients(recipe)); 
  // Prints ["Basil", "Pine Nuts", "Garlic", "Olive Oil", "Grated Parmesan"]
});

```

When unit testing, each function should be tested in isolation. In Jest, we do this by creating separate containers for our testing logic using the `test()` function. 

The `test()` function takes three arguments:
1. A string describing what is being tested
2. A callback function containing assertions and other testing logic
3. An optional timeout in milliseconds that specifies how long a test should wait before automatically aborting. If unspecified, this defaults to 5000 ms. 

If we wanted to test the functions from the `recipes` module, we could use the `test()` function to create containers for each, like so:

```js
//file: __tests__/recipes.test.js

// import the functions to test
import { findRecipe, getIngredients } from "./recipes.js"; 

test("Get the full recipe for Pesto", async () => {
    // testing logic for findRecipe() omitted...
}, 10000);

test("Get only the ingredients list for Pesto", () => {
    // testing logic for getIngredients() omitted...
});
```

Let's look at the tests in this example. 
* With the first argument of `test()`, we state the purpose of the test - to get the recipe for Pesto. This string shouldn't explain the implementation of the function being tested, only the desired result. 
* A callback function is passed as the second argument to `test()`. Inside is where we will write our testing logic (we will cover this soon in more detail in the next exercise). Since the function being tested makes an asynchronous API call, this callback is marked as `async` (again, we'll come back to this).
* Lastly, with the third argument, we specify that we want to see if this operation can be carried out in under 10000ms (10 seconds) since making the API call may take some time.
* The second `test()` follows the same pattern, however, the function being tested is not asynchronous so the `async` keyword is omitted from the callback function. Also, by leaving out the third argument, we are using the default 5000ms timeout.

Each time we create a new `test()` function call, we create a separate entry in our testing output when we run `npm test`. Running the `npm test` command for the example above would produce this output:

![Jest test output](https://static-assets.codecademy.com/Courses/jest/jest_4_1_recipes.png)

Now it's your turn to try!

Unit Testing with Jest (Part 1)

As developers, we strive to make our code bulletproof from bugs that could break our applications. One process that can help us get closer to "unbreakable code" is _testing_ while _testing frameworks_ are libraries that provide functions that enable testing. 

When developing and testing in JavaScript, we can use a testing framework called [Jest](https://jestjs.io/docs/getting-started). While there are many testing frameworks out there, Jest focuses on simplicity. Jest provides the two key ingredients needed for testing:

1. An assertion library – an API of functions for validating a program's functionality
2. A test runner – a tool that executes tests and provides outputted test summaries

Unlike other testing frameworks which may require you to bundle these separately, Jest provides both, allowing us to begin testing right out of the box without much setup. 

In this lesson, we will analyze and test the command-line application found in **language_spoken.js** that outputs the number of countries that an inputted language is spoken in. While analyzing this app, we learn some of the core features of Jest including:
* Installing and configuring Jest
* Creating tests using the `test()` function
* Testing asynchronous code
* Creating and using mocks within your tests

Let's begin!

> Note: If you have used other testing frameworks like [Mocha](https://mochajs.org/) (covered in the [Learn JavaScript Unit Testing course](https://www.codecademy.com/learn/learn-javascript-unit-testing)), much of the syntax of Jest will be familiar to you. While you may continue to use Mocha to test your applications, consider the tradeoffs of each framework as you choose the framework that is right for you! Jest, for example, is frequently used when testing React applications.

What is Jest?

Great work! We have covered a lot over this lesson. Let's take a moment to review:
* We have learned that Jest is an easy-to-use framework for testing in a JavaScript environment because it combines a test-runner with assertion methods like the `expect()` API. 
* We also learned some of the basic syntax involved with creating a simple unit test, such as the `test()` function. 
* After tackling basic unit tests we adventured into the realm of testing asynchronous code with Jest by using the `done` parameter to wait for asynchronous callbacks and the `async`/`await` keywords to wait for Promises to resolve
* Lastly, we learned how to mock functions using `jest.fn()` and make use of mocked modules with `jest.mock()` by mocking the Axios module.  

While we have learned a lot there is always more knowledge to be obtained and we encourage you to continue exploring Jest and its wonderful features!


Let's Review!

With our `test()` container set up, it is time to finish our first unit test by writing _assertions_ to validate the various features of our code. To do this, Jest provides the `expect()` function. 

The `expect()` function asserts how we expect our program to run and is used every time that we want to write a test. However, this function is rarely used alone – it can almost always be found in conjunction with _matcher methods_, like `.toBe()`, in the example below:

```js
expect(2+2).toBe(4)
```

The value passed to `expect()` should be an expression that you want to test (`2+2`) while the matcher method determines how that expression will be validated and what the expected value of that expression is (`.toBe(4)`). 

Let's look again at the `getIngredients` method in the `recipes` module to see how `expect()` assertions fit into a `test()`. 

Remember, `getIngredients()` converts an object containing ingredients and their quantities for a recipe into an array of just the ingredients. To test this function, we can add testing logic to the callback passed to the `test()` function:

```js
//file: __tests__/recipes.test.js
 
// import the function to test
import { getIngredients } from "./recipes.js"; 
 
test("Get only the ingredients list for Pesto", () => {
  //arrange
  const pestoRecipe = {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  }
  const expectedIngredients = ["Basil", "Pine Nuts", "Garlic", "Olive Oil", "Grated Parmesan"]
  
  //act
  const actualIngredients = getIngredients(pestoRecipe);

  //assertions
  expect(actualIngredients).toEqual(expectedIngredients)
});
```

In this example, we follow the **Arrange**, **Act**, **Assert** pattern in the callback passed to `test()`:
* Arrange: We first declare the input (`pestoRecipe`) to be passed to the function being tested (`getIngredients()`) as well as the expected output (`expectedIngredients`).
* Act: We then pass the input variable into the function being tested and store the result in a new variable (`actualIngredients`).
* Assert: Finally, we use the `expect()` assertion function and the `.toEqual()` matcher to compare the values of the expected output with the actual output.

Multiple `expect()` assertions can be made within a single call to `test()`. Regardless of the number of assertions made within a unit test, in order for the entire test to pass, all assertions must pass.

Now it's your turn to try writing some assertions for the `language_spoken` app!

> Note: The `.toBe()` matcher can be used to compare simple data types for equality while the `.toEqual()` matcher is used to perform deep equality comparisons.

Unit Testing with Jest (Part 2)

Congrats on writing your first unit test! In the last exercise, you used the `expect()` assertion function along with the `.toEqual()` matcher method. Let's learn about a few more common matcher methods. 

Take a look at the file below where we've now added a number of new assertions to test the `getIngredients()` method from the `recipes` module.

```js
//file: __tests__/recipes.test.js
 
// import the function to test
import { getIngredients } from "./recipes.js"; 
 
test("Get only the ingredients list for Pesto", () => {
  //arrange
  const pestoRecipe = {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  };
  const expectedIngredients = ["Basil", "Pine Nuts", "Garlic", "Olive Oil", "Grated Parmesan"];
 
  //act
  const actualIngredients = getIngredients(pestoRecipe);
 
  //assertions
  expect(actualIngredients).toBeDefined();
  expect(actualIngredients).toEqual(expectedIngredients);
  expect(actualIngredients.length).toBe(5);
  expect(actualIngredients[0] === "Basil").toBeTruthy();
  expect(actualIngredients).not.toContain("Ice Cream");
});
```

Let's go over the matchers used in this example:
1. `.toBeDefined()` is used to verify that a variable is not ```undefined```. This is often the first thing checked.
2. `.toEqual()` is used to perform deep equality checks between objects. 
3. `.toBe()` is similar to .toEqual() but is used to compare primitive values.
4. `.toBeTruthy()` is used to verify whether a value is truthy or not.
5. `.not` is used before another matcher to verify that the opposite result is true
6. `.toContain()` is used when we want to verify that an item is in an array. In this case, since the `.not` matcher is used, we are verifying that `"Ice Cream"` is NOT in the array.

As mentioned in the previous lesson, there are many different matches. Rather than memorizing all of them, you should consult the complete list in the [Jest documentation](https://jestjs.io/docs/expect).
 

Matcher Functions

Armed with how to write simple unit tests, we will now add a layer of complexity by exploring how to test asynchronous code in Jest. 

Let's return to the `findRecipes()` function from the `recipes` module. Remember, the `findRecipes()` method will make an asynchronous [REST API](https://www.codecademy.com/articles/what-is-rest) call and pass the resolved data to a callback function. We might use this function to find the ingredients for pesto like so:

```js
findRecipe('pesto', (recipe) => {
  console.log(recipe);
  /* 
  Prints {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  };
  */
});
```

If we wanted to make sure that this function does in fact get the requested data, we may be tempted to put our `expect()` assertion inside the callback function like so:

```js
test("get the full recipe for pesto", () => {
  //arrange
  const dish = "pesto";
  const expectedRecipe = {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  };

  //act  
  findRecipe(dish, (actualRecipe) => {
    //assertion
    expect(actualRecipe).toEqual(expectedRecipe);
  });
});
```

This logic seems fairly sound. When the API call resolves, the provided callback will be executed with the fetched data (`actualRecipe`) which can be compared to `expectedRecipe`. 

However, this test would leave us vulnerable to a false positive, meaning it would pass even if our API call and/or assertion failed! By default, Jest is not aware that it must wait for asynchronous callbacks to resolve before finishing a test. From Jest's perspective, it executed the `findRecipe()` call and then moved on. When it didn't immediately encounter any failing `expect()` assertions, the test passed! 

We can see this more clearly by replacing the assertion used above with an obviously failing assertion like `expect(undefined).toBeDefined()`: 

```js 
test("get the full recipe for pesto", () => {
  //arrange
  const dish = "pesto";
  const expectedRecipe = {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  };

  //act  
  findRecipe(dish, (actualRecipe) => {
    //assertion
    expect(undefined).toBeDefined(); // No way this passes, right?
  });
});
``` 
Running this test will produce a bewildering pass! Again, Jest has no way to know that the callback is asynchronous so it will not wait for it and it will not see the failing `expect()` assertion.

To fix this issue, Jest allows us to add a `done` parameter in the `test()` callback function. The value of `done` is a function and, when included as a parameter, Jest knows that the test should not finish until this `done()` function is called. 

Let's take a final look at the test for the `findRecipe()` function, this time using the `done` parameter.

```js
// This time we'll use the `done` parameter
test("get the full recipe for pesto", (done) => {
  //arrange
  const dish = "pesto";
  const expectedRecipe = {
    'Basil': '2 cups',
    'Pine Nuts': '2 tablespoons',
    'Garlic': '2 cloves',
    'Olive Oil': '0.5 cups',
    'Grated Parmesan': '0.5 cups'
  };

  //act  
  findRecipe(dish, (actualRecipe) => {
    //assertion
    try {
      expect(actualRecipe).toEqual(expectedRecipe);
      done();
    } catch (error) {
      done(error);
    }   
  });
});
```

Let's break down this example:
* In the first line of code, the `done` parameter is added to the callback passed to `test()`. Jest now knows to wait until that function is called before concluding the test.
* The `done()` function is called after the `expect()` assertion is made. This way, the `expect()` is guaranteed to be seen and any false-positives will be caught.

You should notice that the `expect()` and `done()` call are being made in a `try` block. Without this, if the assertion were to fail, `expect()` would throw an error before the `done()` function gets a chance to be called. From Jest's perspective, the reason for the test failure would be a timeout error (since `done()` was never called) rather than the actual error thrown by the failed `expect()` assertion. 

By using a `catch` block, we can capture the `error` value thrown and pass it to `done()`, which then displays it in the test output. Though not required, this is a best practice and will yield better test outputs.

Testing Async Code with Jest (Part 1)

Before we can begin testing our code with Jest, the `jest` package must first be installed and configured. We will download Jest via the **N**ode **P**ackage **M**anager (NPM) by running the following command in our terminal:

```
npm install jest@^27 --save-dev
```

The `npm install jest` command installs the `jest` node package and `@^27` specifies which version of the package will be installed. If no version is given, the latest version of Jest will be installed by default. The `--save-dev` flag specifies that Jest should be saved as a developer dependency. At this point, we should see `"jest"` included in the **package.json** file under `"devDependencies"`:

```js
"devDependencies": {
  "jest": "<version number>"
}
```

> Note: If you were to install Jest locally on your machine you would need to include the `-g` global flag to get access to the command line tools.

Now that we have Jest installed, let's create a file to write our tests. The Jest API looks for files that are either inside of a **\_\_tests\_\_/** directory or any file that ends in either **.test.js** or **.specs.js**. 

It is a good practice to match the name of the test file to the file that you are wanting to test. For example, if you were to test a file called **math.js**, you might create a file in the **\_\_tests\_\_/** directory called **math.test.js**. 

Once you have your test files created (more on writing test logic in the upcoming exercises), Jest provides a terminal command to run test files individually: `jest <filepath/filename>`. For example, to run the **math.test.js** test file we might write:

```jest __tests__/math.test.js```

![You can run individual files by specifying the filename after the jest command](https://static-assets.codecademy.com/Courses/jest/jest-2-single-file.png)

We can also run tests on all of the files that have the **.test.js** or **.spec.js** extension or are within a **\_\_tests\_\_/** folder by simply running the `jest` command on its own:

![Runnign the jest command with no additional arguments will test all files in the __tests__/ directory](https://static-assets.codecademy.com/Courses/jest/jest-2-all-files.png)
