Using Istanbul for Code Coverage in React
Chances are high that your React app has untested lines of code. Enter Istanbul, a JavaScript tool that helps you understand where unit tests are needed.
Sep 24, 2020 • 5 Minute Read
Introduction
Chances are high that, in this very moment, your React app has untested lines of code. These are essentially lines of codes that are being executed consistently within the control flow of your program without proper unit tests to cover them. If it sounds like an incredibly daunting task to manually walk through each line of your code and ensure that they are all covered by unit tests, that's because it is! So how can you identify and provide a solution to this problem?
Enter Istanbul.
Istanbul is a JavaScript code coverage tool that works by analyzing your codebase and providing you with the coverage insights you need in order to understand, file by file, where unit tests are needed in your app. In this guide, you will learn not only what Istanbul is, but how to use it and incorporate it into your React app.
Let's get started!
Istanbul Overview
Istanbul is a phenomenal tool that has been around the JavaScript ecosystem for quite some time. It works with both ES5 and ES6+ JavaScript code, so you can easily integrate it with your React app, assuming that you are using one of the following JavaScript testing frameworks:
- Jest
- AVA,
- Mocha,
- Node Tap
- Intern
In fact, if you used create-react-app to bootstrap your React app, you are most likely using Jest as your testing framework. At any rate, if you are using Jest, you don't even need to manually install Istanbul at all since Jest comes with Istanbul baked in.
Getting Started
Irrespective of the testing framework you are using, you can get set up by following the relevant tutorial located on the Istanbul tutorials page. In this guide, we will assume that Jest is being used to test your React app as it is largely considered a best practice. For this example, the first thing you will need to do is to use create-react-app to bootstrap a new React app. You can do this by running npx create-react-app istanbul-test-app.
Note: npx is a package runner that comes included with NPM v5.2 or greater.
Now that you have your new app created, you can start using Istanbul out of the box! In the next section, you will learn how to start generating code coverage with Istanbul.
Measuring Code Coverage
In the previous section, you bootstrapped a new React app using create-react-app, which comes with the Jest testing framework included. Because Istanbul is included with Jest by default, it is very easy to get started!
Located in the package.json file, the new app's test script looks like this: react-scripts test. Under the hood, this script is using Jest to run all of the tests in the new app. Conveniently for you, Istanbul can be used to provide a coverage report by simply adding the --coverage flag onto the end of the test command like this: react-scripts test --coverage.
It is recommended that you create a new NPM scripting command named coverage or test:coverage so that you can easily configure when you want to run your unit tests with coverage. The updated portion of the package.json should look like this:
...
"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"coverage": "react-scripts test --coverage",
"eject": "react-scripts eject"
},
...
It's really that easy when using create-react-app and Jest! Now you are ready to start generating code coverage reports. Istanbul's command-line tool nyc is used under the hood to generate a table that shows you the percent coverage for the following code stats by file:
- Statements
- Branches
- Functions
- Lines
Istanbul conveniently gives you the line numbers of pieces of code that are not covered, organized by file, so that you can begin implementing tests for the uncovered lines.
In order to generate this report, all you have to do is run npm run coverage or npm run test:coverage depending upon what you decided to name the relevant NPM script. And, voila! Jest will run your unit tests in the command line, and then Istanbul will print your code coverage statistics in the command line for you afterward.
Conclusion
In this guide, you learned what Istanbul is as a code coverage tool and how you can use it to analyze your React codebase from a testing perspective. You discovered how you can use Istanbul to help you realize code paths that you have not tested yet so that you can achieve and maintain 100% code coverage.
I hope that this guide has helped you to see how valuable Istanbul can be to your React app and has made you confident in your ability to integrate it with your existing codebase and unit tests. For more information, check out the Istanbul documentation.
