Javascript: testing mediators using sinon and inject-loader

Unit testing in javascript is not always easy, especially when it comes to testing asynchronous code. And searching the internet might not always give you an answer or, at least, the best answer…

I personally like the mediator pattern and I use it a lot in my projects. Mediators allow you to decouple your front-end components from your services, and by doing so, testing all the different parts of your application becomes easier.

structure of the Mediator pattern

I like to use Postal.js for communication between the different parts of my applications, especially between the front-end components, the mediators and the services. Postal.js is a very well known in-memory message bus inspired by AMQP and allows you to post and subscribe to messages in a very simple fashion.

Now, testing front-end components and services is relatively straightforward, but testing mediators is not so easy. And the reason is that you mediators will normally call services to do some kind of logic, and you need to mock those services, which is not trivial if you’re using bundlers like webpack or requirejs.

If you’re using webpack, fortunately, a very simple library is available that allows you to mock the required dependencies that your mediator uses. So if you imagine you have a service like this:

//myService.js
exports default () => {
    this.doWork = () => {
        return 'doing some work...';
    }
}

and a mediator like this:

//myMediator.js
import postal from 'postal';
import myService from 'myService';

var channel = postal.channel('channel.name');

channel.subscribe('topic.name', () => {
       console.log(myService.doWork()); // doing some work...
});

Then you can easily test this mediator like this:

//myMediator-test.js

var postal = require('postal');
var sinon = require('sinon/pkg/sinon');
var expect = require('chai').expect;

describe('My mediator', function(){
      var myServiceStub, myServiceMock;
      var channel = postal.channel('channel.name');

      beforeAll(function(){
            var MyModuleInjector = require('inject!myMediator');
            
            //Create stub for doWork
            myServiceStub = sinon.stub().returns('Mock do work...');

            //Creating mock to be injected
            myServiceMock = function (){
                 this.doWork = myServiceStub;
            });

            //Injecting the mock
            MyModuleInjector({
                   'myService': myServiceMock
            });
      });

      it('should use mock service', function(){
         channel.publish('topic.name');
         expect(myServiceStube.called).to.be.true;
      });
});

Some clarifications about the code above.

First, in the mediator test where I do something like require(‘inject!myMediator’), I’m using the inject-loader an awesome webpack loader that allows you to mock your required dependencies. With the inject loader you can mock all or just the dependencies you want, which makes it extremely flexible!

Second, I’m using sinon to create my stubs, because it’s an amazing library for stubbing, mocking and spying. Really, if you don’t know what it is you should look it out, it is extremely easy to use and is agnostic to your application infrastructure, so you can always use it.

As you see, if you’re using webpack, testing your mediators should be simple enough, and now you don’t have an excuse not to test them. 🙂

Advertisements

Building a yeoman X-Tag WebComponent generator

yeomanx-tag

Yeoman generators are very useful and they allow you to focus on implementing your application without having to reinvent the wheel over and over again…

Building a yeoman generator is not rocket science and a very comprehensive tutorial on how to do it can be seen at yeoman’s website.

WebComponents are also in a trend these days, and I strongly believe they are the future. Apart from Polymer, X-Tag is probably the most used and talked WebComponents library out there. X-Tag started as a Mozilla project but is now supported by Microsoft. It’s a very clever library, that does not rely on all WebComponents API to work, which is a big advantage over Polymer. It only needs the browser to support custom elements, which means that it supports IE9+. It’s also very simple to understand, which means the learning curve is not that steep.

Now, building a yeoman generator that allows you to scaffold an X-Tag WebComponent is very useful and will save you a lot of copy and past on an X-Tag application.

I won’t go throw all the details in this post, that’s not the objective, but instead I’ll give you an overview of the steps required to create your own yeoman X-Tag webcomponent generator.

The first thing you need to do is create the folder where you want to create the yeoman generator and then type:

$npm init

This command allows you to create the package.json file. You’ll be asked several questions, the first one is the name of your generator, and you have to name it generator-name-of-your-generator, this allows the generator to be indexed by the yeoman generators page when you publish the generator.

You’ll also be asked to give keywords to describe your generator, and you have to include at least the “yeoman-generator” keywords, for the same reason as the paragraph above.

After the creation of the package.json file you need to add the yeoman generator as a dependency for the module by typing:

npm install --save yeoman-generator

Now if you follow the tutorial on how to create yeoman generators, there’s a part about templating. This is the most important part because it’s the one that copies files and allows you to replace anchors inside those files with text such as the yeoman generator’s name and so on.

The template for the X-Tag WebComponent file in its simplest form will be something like:

import xtag from 'x-tag';
import './<%= filename %>.css';

(function () {
 xtag.register('<%= filename %>', {
          lifecycle: {
             // Fires when an instance of the element is created
             created: function () { },
             
             // Fires when an instance was inserted into the document
             inserted: function () { },
             
             // Fires when an instance was removed from the document
             removed: function () { },
             
             // Fires when an attribute was added, removed, or updated
             attributeChanged: function (attr, oldVal, newVal) { } 
          },
        events: { },
        accessors: { },
        methods: {}
 });
}());

Here <%= filename %> is an anchor that will be replaced by the webcomponent’s name. This might change depending one your own specific implementation.

Apart from the main webcomponent module file above, there are at least 3 or 4 files that should be included in the generator. A file to contain your unit tests, and as a good practice, this file should contain a failing test, so that you are sure that you’ll look at the tests :). A css, less or sass file depending on what you use, a template for the readme file and a small html file where you can test your webcomponent.

It’s also a good practice to use some kind of templating engine like handlbars or mustache so that you have your html in a different file and not inside the webcomponent itself.

Following these simple steps above, you can create your own yeoman generator, in this case, to generate an X-Tag webcomponent.

Feel free to have a look at the X-Tag webcomponent generator I built, and do a pull request if you want to do improvements on it:

https://github.com/VsLoureiro/x-tag-component-generator

From Requirejs to Webpack, the old and the new…

requirejswebpack

 

As you already figured out by the title, this post will try to show you why I and my team decided to move from requirejs to webpack. They are both widely used and requirejs is clearly the oldest of the two, hence, this is somehow comparing the old with the new.

And, for me at least, in this case, old doesn’t mean gold :). Don’t get me wrong, requirejs was a great library when it was built and set the standards for many of the similar bundlers that came after, like webpack.

But in my experience requirejs is not dealing well with how new web applications are evolving, and I’ll try to explain, according to my experience using the tool, why we decided to move to webpack.

Why move:

Well, we first started thinking about moving from requirejs to webpack after we started extracting modules from a big application we had into separate npm modules. Because requirejs doesn’t import node modules, we had to start “hacking” and we installed our private npm modules into a folder inside the source path of our application so that they could be bundled by requirejs.

Well this has a lot of problems, first we don’t want a separate folder inside our source folder just to have external dependencies imported by requirejs. Second, if any of these modules has a dependency on a module that is already installed in the outer “primary” node_modules folder you would end up with that dependency being installed twice.

Webpack was built to support NPM modules, so you don’t have to worry about placing node modules inside the application source folder.

Requirejs follows the AMD (Asynchronous Module Definition) proposal, which for anyone used to work with node and CJS (CommonJS) modules can be annoying. They provide a way to convert CJS into AMD, but is really not flexible, and you have to follow specific steps to make it work, and really why should we care about that anyway, it should be transparent to us.

Webpack supports both AMD and CJS, so you don’t have to worry about converting AMD to CJS or vice versa, it just works. You might think that this is not a big deal, but when you think that you can use any nodejs library in the browser out of the box, things start to get exciting.

Another problem with requirejs is the loaders plugins. I really don’t want to explicitly have to do something like this:

define(['css!styles/cssfile'], function() { /* .. */})

Applying processors explicitly is not a good idea, it should be a responsibility of the bundler to detect different types of files and process them in the background, and it should be transparent to you.

Webpack loaders are really amazing, configuring the loaders is really simple and the overall plugin system is more robust. Also, ES6 support is very easy to add with the babel-loader in webpack, while making ES6 to function in requirejs is a little bit of a battle.

Conclusion:

For all this, we decided to take the hit of converting a big application from requirejs to webpack, but I think it is the right thing to do and will undoubtedly pay off in the future.

 

 

A Gulp set up suited for most javascript projects

One of the most important things to think about when starting a new javascript project is which building tasks we want to create and automate to make sure we increase our development speed. This might not sound like a big thing, but it becomes evident when you think that a big portion of your time is spent doing building related tasks, like running unit tests, bundling components, transpiling less files, linting and so on.

I’ve done this process quite a few times now and I think I managed to get a pretty good automated building setup which definitely increases our productivity.

Depending on the javascript project you’re doing some of the tasks will vary. But I’ll explain that later.

But more to the point, if you’re thinking of starting a new React, Knockout, Angular or any of the fancy javascript libraries/frameworks projects, these are the bare minimum tasks you’ll have to automate:

  • Unit tests
    • Karma, webcomponents-tester and so on. This assumes you’re a TDD oriented developer, as you should 😉
  • Local development server
    • Local server that you’re going to use to test your application
  • Bundling
    • Bundles your application into small sized files for browser performance purposes.
  • Linting
    • To make sure your code doesn’t have errors or potential problems.
  • File Minification
    • To minify javascript, css and html files. This is normally an option on the bundling library, but for the sake of clarity I separate those.

These are, for me, the minimum building tasks every javascript project should have.

I’ll go through each one of them now, giving my preference about the library I normally use.

Unit tests:

Unit tests are one the most important parts of your application. They ensure your code does what is supposed to do and give you confidence to change your code.

If you’re not using a webcomponents library, my first choice to optimize your tests is Karma. Karma is maintained by the AngulaJs team, and it allows you to run your unit tests in an automated fashion.

gulp-karma is my favorite gulp task for this. It’s very simple to set up.

var gulp = require('gulp'); 
var Server = require('karma').Server; 

/* Run test once and exit  */ 

gulp.task('test', function (done) { 
            new Server(
                      { 
                         configFile: __dirname + '/karma.conf.js', 
                         singleRun: true 
                      }, 
                      done).start(); 
});

This code will run all your tests on your application. You can see more in the karma GitHub page. Combine karma with jasmine or mocha and you have all you need to unit test your application.

If you’re using webcomponents the web-component-tester library is the one to go. It was built by google for Polymer, but it can be used with other frameworks like x-tag and so on.

Local development server:

This is an absolute must have in every project. If you don’t want to spend all your time doing a release every time you change your code, a fast local development server is obligatory.

You have several options here, if you’re using webpack as your bundler, the webpack dev server is the best choice, is easy to configure and the hot module replacement is a very cool functionality. You can see more clicking here.

If you’re using requirejs or other bundlers, gulp-connect is one of my favorites. Is essentially a gulp plugin that allows you to use a webserver.

Bundling:

Modern web applications should be fast and responsive, and choosing the most suited bundler for your project goes a long way to achieve it. It helps to shrink  your application into one or more small chunks so that you can load them when your browser needs them. It also helps your application access node js libraries that would normally not work in the browser, only on the server.

Depending on the type of project you have, several options are available.

Requirejs is one of the oldest bundlers around and is still very used today. Although very good, I personally prefer webpack or browserify for the same type of projects. They are easy to set up, and webpack is so powerful that if you want you can basically substitute your gulp tasks with webpack plugins.

Webpack and browserify have the added benefit of allowing you to use node js libraries in the browser.

To see how you can use webpack with gulp click here, and for browserify click here.

If you’re using webcomponents the best and, as of the time of writing this post, the only bundler that supports html imports in an efficient manner is vulcanize developed by google for Polymer, but it works with other frameworks like x-tag and so on.

Linting: 

This is a very useful task to have if you don’t want to spend lots of time correcting errors in your javascript and doing potentially harm code.

gulp-jshint is perhaps my favorite due to the complete set of options you can use to configure it. You can also choose from a set of different reporters so you can choose the one you like the most.

var jshint = require('gulp-jshint');
var gulp   = require('gulp');

gulp.task('lint', function() {
  return gulp.src('./lib/*.js')
    .pipe(jshint())
    .pipe(jshint.reporter('YOUR_REPORTER_HERE'));
});

File Minification:

This is essential if you want to keep your release files small. Minifying html, css and javascript files can be done with several libraries, and bundlers like webpack or browserify can be set up with their own minification options.

But if you want to separate those tasks into different gulp tasks you can use gulp-cssnano, gulp-htmlmin and gulp-minify to minify css, html and javascript files respectively.

 

Conclusion:

These are, for me, the bare minimum tasks you should have to automate/streamline your building process.

All these tasks can be done using grunt as well, but I prefer gulp because it’s more javascript-ish like 🙂