Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 

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.

About

a lightweight javascript stubbing framework

Resources

Releases

No releases published

Packages

No packages published
You can’t perform that action at this time.