Sinon Tutorial: JavaScript Testing with Mocks, Spies & Stubs

This article was peer reviewed by Mark Brown and MarcTowler. Thanks to all of SitePoint's peer reviewers for making SitePoint content the best it can be!

One of the biggest stumbling blocks when writing unit tests is what to do when you have code that's non-trivial.

[author_more]

In real life projects, code often does all kinds of things that make testing hard. Ajax requests, timers, dates, accessing other browser features... or if you're using Node.js, databases are always fun, and so is network or file access.

All of these are hard to test because you can't control them in code. If you're using Ajax, you need a server to respond to the request, so as to make your tests pass. If you use setTimeout, your test will have to wait. With databases or networking, it's the same thing — you need a database with the correct data, or a network server.

Real-life isn't as easy as many testing tutorials make it look. But did you know there is a solution?

By using Sinon, we can make testing non-trivial code trivial!

Let's find out how.

What Makes Sinon so Important and Useful?

Put simply, Sinon allows you to replace the difficult parts of your tests with something that makes testing simple.

When testing a piece of code, you don't want to have it affected by anything outside the test. If something external affects a test, the test becomes much more complex and could fail randomly.

If you want to test code making an Ajax call, how can you do that? You need to run a server and make sure it gives the exact response needed for your test. It's complicated to set up, and makes writing and running unit tests difficult.

And what if your code depends on time? Let's say it waits one second before doing something. What now? You could use a setTimeout in your test to wait one second, but that makes the test slow. Imagine if the interval was longer, for example five minutes. I'm going to guess you probably don't want to wait five minutes each time you run your tests.

By using Sinon, we can take both of these issues (plus many others), and eliminate the complexity.

How Does Sinon Work?

Sinon helps eliminate complexity in tests by allowing you to easily create so called test-doubles.

Test-doubles are, like the name suggests, replacements for pieces of code used in your tests. Looking back at the Ajax example, instead of setting up a server, we would replace the Ajax call with a test-double. With the time example, we would use test-doubles to allow us to "travel forwards in time".

It may sound a bit weird, but the basic concept is simple. Because JavaScript is very dynamic, we can take any function and replace it with something else. Test-doubles just take this idea a little bit further. With Sinon, we can replace any JavaScript function with a test-double, which can then be configured to do a variety of things to make testing complex things simple.

Sinon splits test-doubles into three types:

• Spies, which offer information about function calls, without affecting their behavior
• Stubs, which are like spies, but completely replace the function. This makes it possible to make a stubbed function do whatever you like — throw an exception, return a specific value, etc
• Mocks, which make replacing whole objects easier by combining both spies and stubs

In addition, Sinon also provides some other helpers, although these are outside the scope of this article:

• Fake timers, which can be used to travel forwards in time, for example triggering a setTimeout
• Fake XMLHttpRequest and server, which can be used to fake Ajax requests and responses

With these features, Sinon allows you to solve all of the difficult problems external dependencies cause in your tests. If you learn the tricks for using Sinon effectively, you won't need any other tools.

Installing Sinon

First off we need to install Sinon.

For Node.js testing:

1. Install Sinon via npm using npm install sinon
2. Require Sinon in your test with var sinon = require('sinon');

For browser based testing:

1. You can either install Sinon via npm with npm install sinon, use a CDN, or download it from Sinon's website
2. Include sinon.js in your test runner page.

Getting Started

Sinon has a lot of functionality, but much of it builds on top of itself. You learn about one part, and you already know about the next one. This makes Sinon easy to use once you learn the basics and know what each different part does.

We usually need Sinon when our code calls a function which is giving us trouble.

With Ajax, it could be $.get or XMLHttpRequest. With time, the function might be setTimeout. With databases, it could be mongodb.findOne.

To make it easier to talk about this function, I'm going to call it the dependency. The function we are testing depends on the result of another function.

We can say, the basic use pattern with Sinon is to replace the problematic dependency with a test-double.

• When testing Ajax, we replace XMLHttpRequest with a test-double which pretends to make an Ajax request
• When testing time, we replace setTimeout with a pretend timer
• When testing database access, we could replace mongodb.findOne with a test-double which immediately returns some fake data

Let's see how that works in practice.

Spies

Spies are the simplest part of Sinon, and other functionality builds on top of them.

The primary use for spies is to gather information about function calls. You can also use them to help verify things, such as whether a function was called or not.

var spy = sinon.spy();

//We can call a spy like a function
spy('Hello', 'World');

//Now we can get information about the call
console.log(spy.firstCall.args); //output: ['Hello', 'World']

The function sinon.spy returns a Spy object, which can be called like a function, but also contains properties with information on any calls made to it. In the example above, the firstCall property has information about the first call, such as firstCall.args which is the list of arguments passed.

Although you can create anonymous spies as above by calling sinon.spy with no parameters, a more common pattern is to replace another function with a spy.

var user = {
  ...
  setName: function(name){
    this.name = name;
  }
}

//Create a spy for the setName function
var setNameSpy = sinon.spy(user, 'setName');

//Now, any time we call the function, the spy logs information about it
user.setName('Darth Vader');

//Which we can see by looking at the spy object
console.log(setNameSpy.callCount); //output: 1

//Important final step - remove the spy
setNameSpy.restore();

Replacing another function with a spy works similarly to the previous example, with one important difference: When you've finished using the spy, it's important to remember to restore the original function, as in the last line of the example above. Without this your tests may misbehave.

Spies have a lot of different properties, which provide different information on how they were used. Sinon's spy documentation has a comprehensive list of all available options.

In practice, you might not use spies very often. You're more likely to need a stub, but spies can be convenient for example to verify a callback was called:

function myFunction(condition, callback){
  if(condition){
    callback();
  }
}

describe('myFunction', function() {
  it('should call the callback function', function() {
    var callback = sinon.spy();

    myFunction(true, callback);

    assert(callback.calledOnce);
  });
});

Continue reading %Sinon Tutorial: JavaScript Testing with Mocks, Spies & Stubs%

by Jani Hartikainen via SitePoint