Skip to content
a lightweight javascript stubbing framework
JavaScript
Find file
Latest commit 43979c4 Apr 23, 2011 Karl Seguin fixed bugs
Failed to load latest commit information.
support initial commit Sep 23, 2010
README.textile fixed missing closing tag Sep 23, 2010
jstub.js fixed bugs Apr 23, 2011
jstub_tests.html added support for named callbacks Sep 23, 2010

README.textile

jstub

jstub is a lightweight javascript stubbing framework. jstub has no dependencies, although it will leverage
qunit if available. The jstub_tests.html file, which uses jquery and qunit to run, is the best place to look for real world usage example.

usage

You stub a method call via the $.stub function. In its simplest form, $.stub is called with 4 parameters.
The first is the object in which the function is define (global function live in @code@window@code@), the string name of the method, an array of expected parameters, and a return value. For example, say we wanted to test the following function:

//the internal implementation doesn't matter since we are mocking the getNewNotifications method
function getNewNotifications(level)
{
  var count = TODO;//hit the server and return the number of new notifications
  return count;
}

We would call:

$.stub(window, 'getNewNotifications', [1], 10);

Any subsequent calls to getNewNotifications(1); would return 10.

non ‘window’ methods

Stubbing a method that does not exist globally is equally as easy. Given:

$.blockUI =
{
  show: function(text)
  {
    //todo block the UI
    return $blockElement;
  }
}

We would call:

$.stub($.blockUI, 'show', ['Processing, Please Wait'], $('<div>'));

any matcher

Passing a parameter of $.jstub.any will create a wildcard match for a parameter:

$.stub(window, 'someFunction', [1, $.jstub.any, 'somethingElse'], 'was stubbed!');
someFunction(1, null, 'somethingElse); //will return 'was stubbed!'
someFunction(1, 213, 'somethingElse); //will return 'was stubbed!'
someFunction(1, new Object(), 'somethingElse); //will return 'was stubbed!'

Furthermore, you can match any parameters by specifying $.jstub.anyAll:

$.stub(window, 'someFunction', $.jstub.anyAll, 'was stubbed!');
someFunction(1, null, null); //will return 'was stubbed!'
someFunction(null, null, null); //will return 'was stubbed!'
someFunction({}, {}, {}); //will return 'was stubbed!'

single parameter

In the case where your method expects a single parameter (be it a simple value, or a more complex one), you do not have to pass the expected parameters in as an array:

$.stub($, 'post', {url: '/some/url', ...}, 'was stubbed!');

callbacks

Rather than having a stub return a value, you can make it invoke a callback from the original list of arguments. To do say the returnValue argument turns into the parameters to pass into the callback, and a new argument is added to specify the callback argument index. Think of the $.post and $.get jquery ajax method:

function doDelete(id)
{
  $.post('/url/delete', {id: id}, function(response, status)
    {
      $('tr[rel=' + response.deletedId + ']').remove();
    }, 'json');
}

In order to accurately stub our code we want to stub $.post yet make sure the callback is properly executed:

$.stub($, 'post', ['/url/delete', {id: 1}, $.jstub.any, 'json'], [1, 'ok'], 2);
doDelete(1);

ok($('tr[rel=1]').length == 0, "row was deleted");

In the above example the returnValue (the 4th argument to $.stub) will be passed to our callback. And the
callback that’ll be executed is the 2 (0-based) parameter of the original (unstubbed) call.

named callbacks

In some cases your callback will be embedded in an object literal – such as when you use the $.ajax method. Stubbing such a scenario requires one additional parameter – the name:

$.stub($, 'ajax', {url: '/url/delete', data:{id: 1}, success: $.jstub.any}, 'deleted response!!', 0, 'success');
doDelete(1);

failures

If a match cannot be found for a method which is being stubbed, an error will be thrown. If qunit is installed, a failed assertion with a error message will be displayed. If qunit is not installed, an exception will be raised.

resetting

All stubs can be reset by calling $.resetStubs()

expectations

jstub supports limited support for expectation checking. $.stub returns an object which has an invoked member which can be queried to count the number of times it was called:

var stub = $.stub($.blockUI, 'show', ['please wait'], null);
$.blockUI.show('please wait');
$.blockUI.show('something else');
$.blockUI.show('please wait');

The stub.invoked will be equal to 2

compatibility

jstub has been tested on IE 6, firefox 3.6 and Chrome 6.

Something went wrong with that request. Please try again.