jasmine-stealth

jasmine-stealth is a Jasmine helper that adds a little sugar to Jasmine's spies.

Download the latest version here.

Conditional Stubbing

"when" + "thenReturn"

One annoyance with Jasmine spies is the default semantics of Spy#andReturn limits you to a single return value, regardless of which arguments a spy is invoked with. However, the arguments a spy is called with usually matter to the spec. None of your out-of-the-box options are great:

1. You could instead use Spy#andCallFake to return conditionally. But this isn't very expressive, and may grow fatter if more conditions are added.

2. You could write an additional it that uses toHaveBeenCalledWith, but then we're verifying the same call that we're stubbing, which requires the spec to be redundant in order to be complete.

3. You could just leave the arguments unspecified and leave the spec as incomplete.

Enter jasmine-stealth, which adds a #when method to Jasmine's spies. It lets you specify a conditional stubbing by chaining thenReturn. Example:

describe("multiple stubbings", function() {
  var someSpy;
  beforeEach(function() {
    someSpy = jasmine.createSpy();
    someSpy.when("pirate", { booty: ["jewels",jasmine.any(String)]}).thenReturn("argh!");
    someSpy.when("panda",1).thenReturn("sad");
  });

  it("stubs the first accurately", function() {
    expect(someSpy("pirate",{ booty: ["jewels","coins"]})).toBe("argh!");
  });

  it("stubs the second too", function() {
    expect(someSpy("panda",1)).toBe("sad");
  });

  it("doesn't return anything when a stubbing isn't satisfied",function(){
    expect(someSpy("anything else at all")).not.toBeDefined();
  });
});

It's worth noting that Jasmine matchers will work with when-thenReturn (see the usage of jasmine#any above).

"whenContext"

Sometimes you want conditional stubbing, but based on the value of this as opposed to the arguments passed to a method. Specifying interactions with jQuery plugins is where I seem to need this most. For that case, you can use whenContext in place of when, like so:

spyOn($.fn,'show');

$.fn.show.whenContext($('body')).thenReturn("a completely contrived example.")

thenCallFake

You can also use thenCallFake (just like jasmine's andCallFake on vanilla spies).

someSpy.when("correct","params").thenCallFake(function(){ window.globalsRock = true; });

someSpy("correct","params");

expect(window.globalsRock).toBe(true);

Custom matchers

The problem: Jasmine currently only comes with one matcher out-of-the-box, jasmine.any(). You can pass a type to it (a la jasmine.any(Number)) in any situation where a variable is going to be evaluated with Jasmine's internal deep-equals function, such as with expect().toEqual() or expect().toHaveBeenCalledWith().

Here's an passing example that uses jasmine.any():

var panda = {
  name: "Lulu"
}

expect(panda).toEqual({
  name: jasmine.any(String)
});

jasmine-stealth adds a couple of my favorite custom matchers from other test double libraries: jasmine.argThat() and jasmine.captor()

argThat matcher

What if we wanted to specify more than just the type of the argument, but we didn't want (or weren't able) to specify the argument's exact value? That's why jasmine-stealth includes a new matcher: jasmine.argThat().

Say that we wanted the panda's name was shorter than 5 characters? Well, now we can:

expect(panda).toEqual({
  name: jasmine.argThat(function(arg){ return arg.length < 5; })
})

Of course, this looks a little nicer in terser CoffeeScript:

expect(panda).toEqual
  name: jasmine.argThat((arg) -> arg.length < 5)

jasmine.argThat() will also work in a spy's toHaveBeenCalledWith expectation, like so:

spy = jasmine.createSpy()

spy(54)

expect(spy).toHaveBeenCalledWith jasmine.argThat (arg) -> arg < 100
expect(spy).not.toHaveBeenCalledWith jasmine.argThat (arg) -> arg > 60

Argument Captors

A different approach to the same problem as above is to use argument captors. It's just another style that may read better in some specs than jasmine.argThat().

Here's a contrived example of the captor API:

//In our spec code's setup
var captor = jasmine.captor()
var save = jasmine.createSpy()

//Meanwhile, in our production code
save({ name: "foo", phone: "123"});

//Back in our spec
expect(save).toHaveBeenCalledWith(captor.capture())
expect(captor.value.name).toBe("foo")

So, when you want to capture an argument value, you first create a captor with jasmine.captor(), then in your expectation on the call to the spy, you use jasmine.capture(), and then the captured value will be available on the captor's value property.

Argument captors are useful in situations where your spec is especially concerned with the details of what gets passed to some method your code depends on. They're a very handy tool in the toolbox, but keep in mind that if you find yourself frequently relying on argument captors to specify your code, it may be a smell that your code is in the (bad) habit of breaking command-query separation.

Summarizing matchers

To summarize, you now have several ways to get at the values that your code passes to your spec's spies:

1. You could interrogate the spy with Jasmine's built-in properties (a la mySpy.calls[0].args[0] === "foo")
2. You could use jamine.argThat() and write a callback function that implies some expectation
3. You could use jasmine-stealth's jasmine.captor() to capture the value during your normal toHaveBeenCalledWith expectation and set up any number of expectations against it.

Other goodies jasmine-stealth adds

mostRecentCallThat

Sometimes it's helpful to look for a certain call based on some arbitrary criteria (usually the arguments it was passed with).

jasmine-stealth adds the method mostRecentCallThat(truthTest,context) to each spy, and it can be used to nab the call you want by passing in a truth test.

See this example:

spy = jasmine.createSpy();
spy('foo',function(){});
spy('bar',function(){});
spy('baz',function(){});

var barCall = spy.mostRecentCallThat(function(call) {
  return call.args[0] === 'bar';
}); //returns the invocation passing 'bar'

barCall.args[1]() //invoke the function argument on that call (presumably to test its behavior)

You can also pass mostRecentCallThat a context (a value for this if the truth test needs access to a this object.)

#createStubObj

Sometimes you want a fake object that stubs multiple functions. Jasmine provides jasmine.createSpyObj, which takes a name and an array of function names as parameters, but it doesn't make it any easier to set up stubbings for each of those passed functions.

Here's an example:

var person = jasmine.createStubObj('person',{
  name: "Steve",
  salary: 1.00,
  stealAnIdea: function(){ throw "I'm going to sue you!"; }
});

Following the above, person.name() is a normal jasmine spy configured to return steve (with andReturn). Likewise, invoking person.salary() will return 1.00. You can also pass in functions as stubs, which will be passed to andCallFake; therefore, invoking person.stealAnIdea() will throw an exception.

Disclaimer: If you find yourself setting up many functions on a stub, beware: complex stubs are smell that there's excessive coupling between the code under test and the dependency being faked.

Other stub aliases

I can often be found complaining about the nomenclature of test doubles. One reason: when test double libraries conflate stubbing and verifying, developers not versed in Test Double Science™ get confused more frequently.

I love spies (over mocks) for verification. But most of the time I don't need verification; I only want to stub behavior.

So in jasmine-stealth, I've added a couple aliases to Jasmine's spy creation to allow spec authors to discriminate their intent. They are:

jasmine.createStub("a stub for #myMethod");

And

stubFor(myObject,"bestMethodEver");

Both will create spies, but now the spec's intent will be a tad more clear. Especially when building a heavy-weight dependency in a beforeEach like this one:

var subject,dependency;
beforeEach(function(){
  dependency = {
    query: jasmine.createStub("#query"),
    count: jasmine.createStub("#count"),
    save: jasmine.createSpy("#save")
  }
  subject = Subject(dependency);
});

That might help the reader figure out your intent, but obviously you're free to take it or leave it.