Node.js module providing helpers that add a little sugar to Jasmine's spies.
jasmine-stealth-node is a Jasmine helper that adds a little sugar to Jasmine's spies.
This is a one-time port of Jasmine-Stealth to be leveraged easily in the node.js environment. Hopefully someone finds this useful.
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:
You could instead use
Spy#andCallFake to return conditionally. But this isn't very expressive, and may grow fatter if more conditions are added.
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.
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
It's worth noting that Jasmine matchers will work with when-thenReturn (see the usage of
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:
You can also use
thenCallFake (just like jasmine's
andCallFake on vanilla spies).
jasmine-stealth adds a facility to spy on a constructor. That way, when your subject code that's under test instantiates a collaborator, you can access its methods as a collection of spies.
Say we have a
view that instantiates a
model. Here's an example spec that uses
spyOnConstructor to isolate the view from the model.
#source: ->model: toJSON#specsdescribe "View"->describe "#serialize"->Given -> @modelSpies = spyOnConstructorwindow"Model""toJSON"Given -> @subject =Given -> @modelSpiestoJSONandReturn"some json"When -> @result = @subjectserializeThen -> expect@resulttoEqualmodel: "some json"
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
Here's an passing example that uses jasmine.any():
var panda =name: "Lulu";
jasmine-stealth adds a couple of my favorite custom matchers from other test double libraries:
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:
Say that we wanted the panda's name was shorter than 5 characters? Well, now we can:
Of course, this looks a little nicer in terser CoffeeScript:
expectpandatoEqualname: jasmineargThat arglength < 5
jasmine.argThat() will also work in a spy's
toHaveBeenCalledWith expectation, like so:
spy = jasminecreateSpyspy54expectspytoHaveBeenCalledWith jasmineargThat arg < 100expectspynottoHaveBeenCalledWith jasmineargThat arg > 60
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
Here's a contrived example of the captor API:
//In our spec code's setupvar captor = jasminevar save = jasmine//Meanwhile, in our production code;//Back in our spec
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 call the captor's
capture() function in place of the argument you want to capture. The captured value will be available on the captor's
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.
To summarize, you now have several ways to get at the values that your code passes to your spec's spies:
mySpy.calls.args === "foo")
jamine.argThat()and write a callback function that implies some expectation
jasmine.captor()to capture the value during your normal
toHaveBeenCalledWithexpectation and set up any number of expectations against it.
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;;;;var barCall = spy; //returns the invocation passing 'bar'barCallargs1 //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
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;
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.
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");
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:
That might help the reader figure out your intent, but obviously you're free to take it or leave it.