justo-spy

    0.7.1 • Public • Published

    Build Status

    Test spy library.

    Proudly made with ♥ in Valencia, Spain, EU.

    Features:

    • Allow to create function spies.
    • Allow to create object spies.

    Test doubles

    A test double is an object that represents other, used to perform in unit testings. There are several types of test doubles:

    • Test dummies. Test double that responds to calls with no action.
    • Test stubs. Test double that responds to calls with predefined responses.
    • Test spies. Test double that monitors the calls to an object.

    Install

    npm install justo-spy
    

    Test spies

    A test spy is a test double that monitors the calls to an object.

    spy()

    The spy() function is used to create the function spies:

    const spy = require("justo-spy");
    

    Function spies

    A function spy represents a function that monitors another function. When the function is called, the spy registers the call info.

    Creating function spies

    To create a function spy, we must use the spy() function:

    spy(fn : function) : function
    

    Example:

    var sum = spy(function(x, y) {
      return x + y;
    });
    

    API spy

    The function returned by the spy() function contains a property, spy, which is used to access the spy.

    Example:

    sum.spy.called().must.be.eq(10);
    sum.spy.calledWith([1, 2]).must.be.eq(1);
    

    Call class

    Every call is represented as an instance of the Call class.

    Properties:

    • callNo (number). The number of call.
    • arguments (object[]). The arguments passed.
    • value (object). The value returned.
    • error (object). The error raised.

    Methods:

    • returned() : boolean. Did it return a value?
    • returned(value : object) : boolean. Did it return the specified value?
    • raised() : boolean. Did it throw an error?
    • raised(msg : string) : boolean. Did it throw an error with the specified message?
    • raised(error : object) : boolean. Did it throw the specified error?

    Querying the spy

    To query the monitoring performed by the spy, we can use the following methods.

    .spy.getCall()

    Returns a specified call:

    getCall() : Call
    getCall(i : number) : Call
    

    If no argument is passed, the only one call is returned; if several calls performed, the method throws an error.

    .spy.getArguments()

    Returns the arguments of a call, similar to getCall().arguments or getCall(i).arguments:

    getArguments() : object[]
    getArguments(i : number) : object[]
    

    .spy.getLastCall()

    Returns the last call:

    getLastCall() : Call
    

    .spy.called()

    Returns the number of calls:

    called() : number
    

    .spy.calledWith()

    Returns the number of calls that received the specified arguments:

    calledWith(args : object[]) : number
    

    .spy.alwaysCalledWith()

    Returns whether all calls were done with the passed arguments:

    alwaysCalledWith(args : object[]) : number
    

    .spy.returned()

    Returns the number of calls that returned value:

    returned() : number
    returned(value : object) : number
    

    .spy.alwaysReturned()

    Checks whether all calls returned a value:

    alwaysReturned() : boolean
    alwaysReturned(value : object) : boolean
    

    .spy.raised()

    Returns the number of calls that raised error:

    raised() : number
    raised(msg : string) : number
    raised(msg : RegExp) : number
    raised(error : object) : number
    

    .spy.alwaysRaised()

    Checks whether all calls raised error:

    alwaysRaised() : boolean
    alwaysRaised(msg : string) : boolean
    alwaysRaised(msg : RegExp) : boolean
    alwaysRaised(error : object) : boolean
    

    Dummy function spies

    We can define a dummy function spy using the following signature:

    spy() : function
    

    For example:

    var sum = spy();
    sum(1, 2);
    sum.spy.called().must.be.eq(1);
    

    Object spies

    An object spy monitors the calls of a member collection.

    Creating object spies

    To create an object spy, we must use the spy() function:

    spy(obj : object) : object
    spy(obj : object, member : string) : object
    spy(obj : object, members : string[]) : object
    

    Where the obj parameter is the object to spy and member and members indicate the members for spying.

    Example:

    user = spy(new User("user01", "pwd"));
    user = spy(new User("user01", "pwd"), "changePassword()");
    user = spy(new User("user01", "pwd"), ["changePassword()", "@username"]);
    

    API spy

    The object returned by the spy() function contains a property, spy, which is used to access the spy.

    Monitoring members

    Right now, an object spy can monitor members defined at class-level: methods and properties; it's not possible attributes.

    Monitoring methods

    To spy a method, we have to use the monitor() method:

    monitor(name : string)
    

    Where the name parameter must be the method name ended with ().

    Example:

    user.spy.monitor("changePassword()");
    

    If we need to monitor a method replacing this with a dummy method, we have to indicate the name as follows:

    name() {}
    

    Example:

    user.spy.monitor("changePassword() {}")
    

    Right now, we can only spy a method if the object hasn't defined an own member with the same name. However, if the method is defined in the class, we can do it.

    Monitoring properties

    To spy a property, we must also use the monitor() method, but the name parameter must start with @.

    Example:

    user.spy.monitor("@username");
    

    Querying the spy

    To query the monitoring performed by the spy, we can use the methods presented above in the function spies. The only thing we must remember is adding the member name as first parameter.

    Here are some examples:

    user.spy.getCall("username", 0).must.have({callNo: 0, accessor: "get", value: "user01", error: undefined});
    user.spy.raised("changePassword", "Password can't be undefined.").must.be.eq(2);
    

    To maintain the convention, we can also use the name used during the monitor() call:

    user.spy.getCall("@username", 0).must.have({callNo: 0, accessor: "get", value: "user01", error: undefined});
    user.spy.raised("changePassword()", "Password can't be undefined.").must.be.eq(2);
    

    Call objects

    The method calls contain the following fields:

    • callNo (number). The number of call.
    • arguments (object[]). The arguments passed to the call.
    • value (object). The value returned.
    • error (object). The error raised.

    Meanwhile, the property calls have the following:

    • callNo (number). The number of call.
    • accessor (string). Type of access: get or set.
    • value (object). Value returned or set.
    • error (object). Error raised.

    Additionally, both types contain the following methods:

    • returned() : boolean. Did it return a value?
    • returned(value : object) : boolean. Did it return the specified value?
    • raised() : boolean. Did it throw an error?
    • raised(msg : string) : boolean. Did it throw an error with the specified message?
    • raised(re : RegExp) : boolean. Idem.
    • raised(error : object) : boolean. Did it throw the specified error?

    Install

    npm i justo-spy

    DownloadsWeekly Downloads

    1

    Version

    0.7.1

    License

    none

    Last publish

    Collaborators

    • justojs