Using Gulp and Karma to test a jQuery Plugin

After playing around with gulp and seeing the various things it can do, I decided it was about time I integrated it in with the jQuery plugin I have developed; and am still developing. This article is going to assume you have used gulp before and have basic understanding as well as know what jQuery is and what a plugin is. For the sake of this article I will be using a small plugin and use that as oppose to the one I initially referred to.

So you have started developing your plugin and think actually it would be a good idea for to have some tests to ensure as you make changes and add new features, you don't break anything. Assuming you have got a package.json and you're already using some npm packages, we can begin adding everything we need to start writing our tests.

Ensure you've got gulp and the command line interface for karma installed:

npm install gulp karma-cli -g

You will then need to install quite a few npm packages so rather than writing them all out, here are the devDependencies from the package.json which you can copy and paste into your own package.json file.

"devDependencies": {
    "gulp": "^3.9.0",
    "gulp-jasmine": "^2.0.1",
    "gulp-karma": "0.0.4",
    "jasmine-core": "^2.3.4",
    "jasmine-jquery": "^2.1.0",
    "karma": "^0.13.9",
    "karma-chrome-launcher": "^0.2.0",
    "karma-jasmine": "^0.3.6",
    "karma-jasmine-html-reporter": "^0.1.8",
    "karma-jasmine-jquery": "^0.1.1"    
}

If you don't already have a gulpfile.js then you'll need to create one at the root of your project, same location as the package.json if you're unsure. Add in the following to the top of the gulpfile:

var gulp = require('gulp');
var karma = require('karma').server;
var jasmine = require('gulp-jasmine');

Now you'll need a gulp task to actually run your tests. Copy the following into your gulpfile:

gulp.task('tests', function (done) {
    return karma.start({
    configFile: __dirname + '/karma.conf.js',
    singleRun: false
  }, done);
});

gulp.task('default', ['tests']);

You'll have probably noticed that this task contains a file we have not yet created, karma.conf.js; this is the configuration file for karma. You can either create this and type it yourself or you can get karma to generate one automatically for you and then edit and make changes as you require. To do this run:

karma init karma.conf.js

For more details about the steps that follow that init command check out http://karma-runner.github.io/0.8/intro/configuration.html as I won't be explaining that here. But for some guidance, we are using jasmine and Chrome. Also regarding the question about source and test files files, leave blank as I will explain that bit next.

Once the karma config file has been created we need to edit it so it knows where to find our source files and our test files. By default it adds in a bunch of default options and comments to explain what they are. The only one we need to pay attention to is files:

files: [
  '<PATH-TO-TESTS>/*.js', '<PATH-TO-JQUERY>/jquery.js', '<PATH-TO-PLUGIN>/<PLUGIN-NAME>.js',
  {
    pattern:  '<PATH-TO-TESTS>/*.html',
    watched:  true,
    served:   true,
    included: false
  }
]

Copy the above into the files option and where specified as path to or your plugin etc, please change to whatever matches your file structure. This tells karma where are tests and our code is that we want to test; as well as any other dependencies we need for our code, i.e. jQuery. That's it for the karma.conf, there is nothing else to add and so now we add some tests!

You'll need to create an .html page in your tests folder (matching the pattern you specified in the karma.conf). In here you will add in the markup needed to run your plugin, this markup is then used for the tests. My markup is shown below, so add yours in the same way:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <head>
        <title>jQuery Plugin</title>
    </head>
    <body>
        <div id="myPlugin-Test"></div>
    </body>
</html>

Finally you can start to write the tests - woohoo! Create a new js file in your tests folder, as we are using jasmine for our tests, we need to add the wrapper code for our tests, which can be seen below. If you used jasmine before then this will be very familiar.

describe('myPlugin Initialisation', function() {

    var el, myPlugin;

    beforeEach(function(){
        jasmine.getFixtures().fixturesPath = 'base/Tests';
        loadFixtures('Template.html');
        el = $('#myPlugin-Test');
        myPlugin = el.myPlugin().data('myPlugin');
    });
});

The above code sets everything up ready for our tests. Inside the beforeEach, we get the path to find our templates for our tests, then load our template in. Then it's back to normal jQuery, get your element and then initialise it. If you copy the above make sure to change the names to whatever your plugin is called, paths, templates etc.

The tests themselves are also a simple structure and jasmine users will be familiar once again:

it('Should add the class "myPlugin" to the element', function() {
    expect(el.hasClass('myPlugin')).toBe(true);
});

All you need to do now is run:

gulp tests

For more complicated tests I suggest you look at jasmine to see what you can do with it that will help you better test your plugin. That's all for this post though, hopefully you can now get your plugin fully tested nice and easily.

Link to code: Download Source