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 file path 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 mock the implementation!
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: recipes.js

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

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

// then, tell Jest to mock the implementation!
jest.mock('./api-request.js');

it("Gets 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);
 
  // assert
  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
it("Gets 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);
  
  //assert
  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, we can now work with asynchronous code that returns a promise. Jest will wait for any `await` statement to resolve before continuing on.

<details>
<summary>When should I use `done()` and `async/await`?</summary>
<p>Although both are functionally similar, their uses can help make your test code more readable. You should use <code>done()</code> for asynchronous code that uses callbacks, while <code>async/await</code> is best suited for code that returns Promises. Choosing the appropriate method can help make your code more readable and easier to understand.</p>
</details>

Testing Async Code with Jest (Part 2)

Over the past few exercises, we have been analyzing the `findRecipe()` function, which makes a REST API call to fetch the recipe data. Testing with the 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. A mock function is a clone implementation of the code we are testing. It behaves the same way, but it is easier to control and test. We can use the mock function to test our code in isolation without worrying about the actual implementation details.

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. This is a special directory that Jest will know to look for 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
// Create a Jest mock function with the same name as the function we're mocking
const apiRequest = jest.fn(() => {
  //Return a resolved Promise with a mock response object
  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: 

```bash
npm test -- --coverage
```

Make sure to note the double dash between the `npm test` and `--coverage`. This is to separate the arguments from the test command itself. 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 ensure 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 been 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.

Configuring Jest

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. We can do this by creating separate containers for our testing logic using the `it()` function or the `test()` function. 

Functionally, `it()` and `test()` are the same. Using one over the other can make tests more readable. You should choose the one that organizationally makes sense in your project and use case.

For example: 

```js
it("should render onto the screen") () => {});
test("should render onto the screen") () => {});
``` 

For the purpose of this course, we'll stick to using `it()`. 

The `it()` 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 `it()` 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"; 

it("gets the full recipe for pesto", async () => {
    // testing logic for findRecipe() omitted...
}, 10000);

it("gets 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 `it()`, 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 `it()`. 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 `it()` 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 `it()` 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 must balance various requirements while coding, such as ensuring that the code is free from errors, complies with the project's specifications, and maintains a high level of overall quality.

One process that can help us get closer to fulfilling these requirements is **testing**. We can do this with libraries that provide functions that enable testing, known as **testing frameworks**.

Without formal testing, developers can only have a vague grasp of the reliability of their application. By testing early and often, developers can catch issues with their code and build confidence that their development process is effective, reliable, and secure.

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 in which an inputted language is spoken. While analyzing this app, we will learn some of the core features of Jest, including:
* Creating tests using the `it()` 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 in 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 `it()` 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!


Review

With our `it()` container set up, it is time to finish our first unit test by writing **assertions** to validate the various features of our code. 

An assertion helps us define an expected outcome and check if the code meets these expectations.

Jest helps us make assertions with the `expect()` function. It is used to assert the expected behavior of our program and is employed whenever we write a test. However, this function is rarely used alone — it can almost always be found in conjunction with _matcher methods_ such as `.toBe()`. 

Take a look at this example:

```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 the validation method for that expression and its expected value (`.toBe(4)`). 

Let's examine the `getIngredients()` method in the `recipes` module again to see how `expect()` assertions fit into an `it()` function.

`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 `it()` function:

```js
//file: recipes.test.js
 
// import the function to test
import { getIngredients } from "./recipes.js"; 
 
it("Gets 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);

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

In this example, we follow the _Arrange_, _Act_, _Assert_ best practice testing pattern in the callback passed to `it()`:

* Arrange: In this stage, we set up the variables and conditions we need. We first declare the input (`pestoRecipe`) to be passed to the function being tested (`getIngredients()`) as well as the expected output (`expectedIngredients`).
* Act: In this stage, we invoke the functionality we want to test. We pass the input variable into the function being tested and store the result in a new variable (`actualIngredients`).
* Assert: In the last stage, we check if the code has produced the expected output. 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 `it()` call. 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 is used to compare simple data types for equality, while the `.toEqual()` matcher is used for 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: recipes.test.js
 
// import the function to test
import { getIngredients } from "./recipes.js"; 
 
it("Gets 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);
 
  //assert
  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. 

When we include asynchronous operations in our code, we must account for the possible timing issues in our test arising from these operations. Although you may be able to avoid these issues with custom timeouts, if the code takes longer, it will fail with a timeout error. Thus, it is crucial to handle these events effectively.

Let's return to the `findRecipes()` function from the `recipes` module. 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
it("Gets 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) => {
    //assert
    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 
it("Gets 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) => {
    //assert
    expect(undefined).toBeDefined(); // No way this passes, right?
  });
});
``` 
Running this test will produce a bewildering pass! Again, Jest has no way of knowing 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
// Notice that we need to pass `done` as an argument to the `it()` function to signal that the test will perform an async operation.
it("Gets 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) => {
    //assert
    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 `it()`. 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()` results will not be reported until the async operation is complete and Jest moves on to the next test!

You should notice that the `expect()` and `done()` calls 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, the `jest` package must first be installed and configured. Thankfully, Jest is the default test runner included and preconfigured in `create-react-app`. There is no further installation necessary when using `create-react-app` to build a new app! 

If you are working without `create-react-app`, follow this [getting started guide](https://jestjs.io/docs/getting-started) to install Jest separately.

To begin testing, we need to make sure that our test files are located, or match the following name conventions under the **/src** top-level directory: 
* files with names ending in **.test.js**
* files with names ending in **.spec.js**
* **.js** files within a **\_\_tests\_\_/** directory

How you store test files in your project may depend on your specific needs. You may choose to colocate test files with the code being tested or to separate them into a **\_\_tests\_\_** directory. For the purpose of this course, we will be colocating our test files with the code being tested.

Our file structure will look like this:

```
src/
└── Button/
    ├── Button.js
    └── Button.test.js
```

It is a good practice to match the name of the test file to the file that you want to test. For example, if you were to test a file called **math.js**, you might create a file called **math.test.js**.

Once you have your test files created (more on writing test logic in the upcoming exercises), you can run the test using the npm command:

```js
npm test
```

This will launch the test in _watch mode_, allowing the test to re-run every time the file is saved! You'll need to type `q` in the terminal to quit out of the watch mode.