JS Code Coverage Part 2

The previous part of this series covered how-to setup JSCover, add test instrumentation, and run some manual tests.

Within this blog, I would like to automate the instrumentation injection step as part of the build process using Gulp.

JS Code Coverage – Automating instrumentation.

If you are responsible for deploying a website and would like to perform this reliably, then automation is your friend.

Now, If you like, you can just run the JSCover command we cover before. If this is a viable solution for you, then this article might not be of your interest. Because here, we will include the step as part of the main build using a client-side build tool called Gulp.

What is Gulp?

I will only cover the basics here, and there is a lot more. Gulp allows you to automate tasks by creating workflows. The easiest way to understand what Gulp is, is by comparing it with something you already know. In many ways it is used like Ant, CMAKE or MS Build, however, covering client-side (not only JavaScript) related operations such as:

• Bundling and minifying JavaScript libraries and stylesheets.
• Run JavaScript Unit tests
• Compress images
• Copy website assets to a different directory
• Running a custom task created yourself or an existing plugin

Note: A very complete beginners guide on gulp can be found here https://css-tricks.com/gulp-for-beginners/.

Benefits of using Gulp

The benefits of using Gulp even for a small scenario are:

• A central place for all client-side rated tasks (including unit tests in an upcoming post)
• Only include instrumentation for non-production builds
• Only minify JavaScript for production builds

The last two are essential for our scenario, because we don’t want to release instrumented files by mistake. Also, not minifying the assets for a test releases will make debugging a lot simpler.

Using Gulp

Here I will cover how to include/utilize gulp within your project. I’ve chosen to do this in ASP.NET MVC, a technology many of my blog readers are using.

Gulp and ASP.NET MVC

If you would like to work with Gulp in conjunction with an APS.Net project, it’s recommended to enable and configure this within Visual Studio as well as for your build scripts / CI environment.

I’ve already written a short post on how to install gulp for Visual Studio which can be found here Gulp and ASP.NET MVC.

Note It’s important that you have immediate feedback when running your JavaScript unit test, therefore enabling gulp within visual studio is crucial.

Gulp in MS Build

At some point, you will have the need to build, package and deploy your website. This also includes executing all your gulp tasks outside of Visual Studio. Now every project and CI environment will be different, and it’s therefore hard to find the best way of doing this, but I will list some standard options below.

– Pre-Build events

This is very easy to implement and ideal for simple projects. however, the pre-build event can only be used if your main project build is not altering any website assets; otherwise, these changes won’t be included.

To implement this, you will create a prebuild.bat (or PowerShell) file, which calls gulp after navigating to your project directory.

gulp --production

– Post-Build events

What about Post-build events? Post-Build events will trigger after all main project talks have been completed, which most likely also includes your deployment (web deploy, Octopus, etc.) and packaging and, therefore, not an option.

– MsBuild.NodeTools

MsBuild.NodeTools consists out of several MS build tasks for dealing with Node/Npm and Gulp related activities. You can define MS Build typed tasks (not just the execution of a .bat or ps1 file) which makes everything a little easier.

The examples are self-explanatory and therefore not including them within this post. Just make sure the custom MS build tasks are available on your CI environment a well.

The Gulp Script

Now that we have covered how to run Gulp scripts within both visual studio as well as MS Build, we can finally start creating the Gulp script needed to include the JSCover instrumentation. We will be using some helper tools to make things even easier. Don’t forget that every package should be installed in the CI environment as well.

Note: I’m Assuming that you have Gulp installed and running as covered in the previous chapters.

Step 1 – install gulp-util

gulp-util contains utility functions for gulp plugins. The function we will be using is gutil.env.type. This function will help us with building the right output based on the environment type.

Npm install gulp-util

Step 2 – install gulp-instrument

gulp-instrument helps with adding JSCoverage instrumentation as expected.

Npm install gulp-instrument

Step 3 – install laravel-elixir

I’m using Laravel Elixir, which provides a clean, fluent API for defining basic Gulp tasks. Laravel Elixir is part of Laravel; an MVC framework for PHP however, can be used for other projects without any complications.

It’s not required to use laravel-elixir, but it simplifies a lot of common tasks. The documentation is also very detailed.

Npm install laravel-elixir

Within The Gulp file

Because we will be using some plugins, the ‘require’ section looks like this;

Note: It’s not required to include minification instructions directly in the gulp file because only a production build (use gulp –production.) includes minification.

The main code will look like this.

If you run the default (dev) task within visual studio, the code will call a nested task called instrument. Later on, the instrumented file(s) will be saved into a different location because we don’t want to override the original source files. Therefore, it’s also important that the web application points to the generated files, and never to the original source files.

For production (call gulp –production within MS Build), the script combines several separate scripts into files to a file called public/js/all.js. Again, it’s important that the website is pointing to the correct files based on the type of build.

Conclusion

I have to admit that It’s quite a bit of work to get everything together. However, once set up, it’s very easy to add additional features like compile Sass files, combine styles sheets, version CSS and js files, and last but not least, run unit tests. Units tests will be covered in the next episode together with Jslint, a static code analysis tool.