The major browser vendors have adopted Source Maps over the past few years as the de facto standard for finding source code origin. While this has made in-environment debugging easier, it still left some challenges for fully testing your code. While Intern has been able to use source maps for a while to map back the stack traces of errors that get thrown, it has been more challenging when trying to understand how well your code is covered by your tests.
A couple of us started exploring how we might be able to accomplish mapping the coverage report back to its origins and after a bit of work, we created
remap-istanbul, a package that allows Istanbul coverage information to be mapped back to its source when there are Source Maps available. While we have been focused on TypeScript, it can be used wherever the coverage is being produced on emitted code, including the tools mentioned above!
So how can you use
remap-istanbul? Well let’s take an example, where we are using the Intern 3 as our testing framework and Grunt as our build tool on a library of TypeScript code. From the root of our project (where your
package.json sits), lets install Intern and
remap-istanbul as development dependencies:
$ npm install intern remap-istanbul --save-dev
There are many different ways to use both Intern and
remap-istanbul in our development chain. With both, you can use Grunt, Gulp or other tools for your task orchestration. We are going to focus on using the command line for this blog post.
At a high level, our workflow is that we need to generate or transpile our code and write Intern tests cases to test our transpiled code. That workflow contains too many options to cover here, but you need to ensure that your transpiled files are emitted with source maps. Once we have done that, we will want to run Intern to run our tests and generate the coverage information for those tests, then we will use
remap-istanbul to remap the coverage information and then output an HTML report which will show the coverage for the original source files.
We need to add the Intern reporter that will write the JSON coverage information
remap-istanbul needs to map back to the original source. From the command line, running our tests remotely, from the root of our project, it would look something like this:
$ node_modules/.bin/intern-runner config=tests/intern reporters=Console reporters=node_modules/remap-istanbul/lib/intern-reporters/JsonCoverage
This will instruct Intern to use the configuration to run the tests and report on the tests via the console and output a JSON coverage file which defaults to
./coverage-final.json. Once our tests complete, we will then want to take that file and remap it against our source file using
$ node_modules/.bin/remap-istanbul -i coverage-final.json -t html -o html-report
This will read in the
coverage-final.json, remap all the locations by inspecting our emitted files and their source maps, and then outputting an HTML report into the path
./html-report. You can then browse to the
html-report directory and see how well your code is covered based on its original source files!
Once you have everything strung together, you can start reaping the benefits.
remap-istanbul is now integrated into Dojo 2’s dojo/core. When you look at the output of coverage information, you get all your information mapped back to it’s original sources. For example:
And if you view the HTML report that is generated, you can see actual line and branch coverage mapped back to its original source as well:
Your workflow might not exactly fit the pattern we described above. There are many other ways to ways integrate and use
remap-istanbul. So here are some locations for some further reading: