Trigger

Trigger

A Trigger determines what expect or action calls get run in real-time on a wrapped function or property, so that a wrapped function or property can be evaluated as it is being run (through expect calls) or modify the behavior of a wrapped function or property (through the use of action calls).

Triggers usally get created by calling a trigger function on the Wrapper, such as triggerAlways or triggerOnCallArgs. Note that triggers are always run in the order that they are added to a Wrapper, and any expectations or actions on a trigger are run in the order they were added to the Trigger. It is important to realize that Triggers are not very interesting by themselves -- without any associated action or expectation they do nothing.

Every time a wrapped function is called or a property is touched, triggers will be evaluated twice: once just before the wrapped function is executed or property is modified, and once after. This provides the opportunity to modify arguments or context that will be used before the wrapper is executed, and provides the opportunity to change return values or errors after the wrapper is executed. Any actions or expectations associated with the trigger will run each time it is evaluated and successfully determines that it should execute. This means that expectations are evaluated in real-time as the code is running. By default expectations will throw an error if they are not met when triggered (unless configExpectThrowsOnTrigger is called with false for the Wrapper).

While most useful 'Triggers' and the associated actions and exceptions have been defined, it may be useful to define your own. For that purpose, triggerCustom and actionCustom have been defined.

Constructor

new Trigger(wrapper, triggerFn)

Source:

Creates a new Trigger

Example
var wrapper = new Wrapper(something);
wrapper.triggerAlways()          // every time the wrapper is called...
    .expectArgs("abc", 123)      // ...throws error if the wrong args are not `"abc"` and `123`...
    .actionReturn(true);         // ...and always change the return value of the function to `true`
Parameters:
Name Type Description
wrapper Wrapper

The Wrapper that created this Trigger and that will evaluate the trigger conditions when the wrapper is executed.
triggerFn function

The function that will be called to determine whether or not the actions and expectations associated with this trigger should be executed.

Methods

(static) expectCallArgs(…args) → {Trigger|Boolean}

Source:

Evaluates whether the arguments to a function match the ...args.

Parameters:
Name Type Attributes Description
args any <repeatable>

The list of arguments to validate for the function call.
Throws:

  • If called with more or less than one argument

    Type
    TypeError

  • If called by a Trigger that doesn't match the expected return value

    Type
    ExpectError
Returns:

When called on a Trigger, the expectation is stored for future evaluation and the Trigger value is returned to make this chainable. When called on a Operation, the expectation is evaluated immediately and true is returned if the expectation passed; false if it failed.

Type
Trigger | Boolean

(static) expectCallContext(context) → {Trigger|Boolean}

Source:

Evaluates whether the context (this) of a function call matches the context parameter.

Parameters:
Name Type Description
context Object

The expected this for the function. Is compared by a strict deep-equals.
Throws:

  • If called on a wrapped function, or with more or less than one argument

    Type
    TypeError

  • If called by a Trigger that doesn't match the expected call context (this value)

    Type
    ExpectError
Returns:

When called on a Trigger, the expectation is stored for future evaluation and the Trigger value is returned to make this chainable. When called on a Operation, the expectation is evaluated immediately and true is returned if the expectation passed; false if it failed.

Type
Trigger | Boolean

(static) expectCustom(cb) → {Trigger|Boolean}

Source:

Evaluates the callback function

Parameters:
Name Type Description
cb Operation~customExpectCallback

Callback function that will determine whether the expecation passes or fails. See customExpectCallback for more details.
Throws:

  • If called with more or less than one argument, or the first argument isn't a Function

    Type
    TypeError

  • If called by a Trigger and the custom function returns an Error or a String

    Type
    ExpectError
Returns:

When called on a Trigger, the expectation is stored for future evaluation and the Trigger value is returned to make this chainable. When called on a Operation, the expectation is evaluated immediately and true is returned if the expectation passed; false if it failed.

Type
Trigger | Boolean

(static) expectException(exception) → {Trigger|Boolean}

Source:

Expects that the function call or property set / get threw an Error that strictly matches the exception arguemnt.

Parameters:
Name Type Description
exception Error | null

The Error (or class that inherits from Error) that is expected to strictly match. A strict comparison between errors evaluates that the Error.name and Error.message are the exact same. If exception is null, it will expecct that there was no Error thrown.
Throws:

  • If called with more or less than one argument, or with an argument that isn't an Error or null

    Type
    TypeError

  • If called by a Trigger that doesn't throw the expected exception (Error) or throwns an unexpected exception (if the expected exception was null)

    Type
    ExpectError
Returns:

When called on a Trigger, the expectation is stored for future evaluation and the Trigger value is returned to make this chainable. When called on a Operation, the expectation is evaluated immediately and true is returned if the expectation passed; false if it failed.

Type
Trigger | Boolean

(static) expectReturn(retVal) → {Trigger|Boolean}

Source:

Evaluates whether the call or get returned the value retVal.

Parameters:
Name Type Description
retVal any

The value that is expected to be returned from the function call or property getter.
Throws:

  • If called with more or less than one argument

    Type
    TypeError

  • If called by a Trigger that doesn't match the expected return value

    Type
    ExpectError
Returns:

When called on a Trigger, the expectation is stored for future evaluation and the Trigger value is returned to make this chainable. When called on a Operation, the expectation is evaluated immediately and true is returned if the expectation passed; false if it failed.

Type
Trigger | Boolean

(static) expectSetVal(setVal) → {Trigger|Boolean}

Source:

Evaluates the value that is set on a property during assignment (e.g. - obj.prop = setVal) and expects the value to strictly equal the setVal argument.

Parameters:
Name Type Description
setVal any

The value that is expected to be set on the property. An undefined value is allowed, but the value undefined must be passed explicitly to expectSetVal.
Throws:

  • If called with more or less than one argument

    Type
    TypeError

  • If called by a Trigger that doesn't receive the expected set argument

    Type
    ExpectError
Returns:

When called on a Trigger, the expectation is stored for future evaluation and the Trigger value is returned to make this chainable. When called on a Operation, the expectation is evaluated immediately and true is returned if the expectation passed; false if it failed.

Type
Trigger | Boolean

actionCallArgs(…args) → {Trigger}

Source:

When triggered, sets the call args to the function to the arguments specified by args

Parameters:
Name Type Attributes Description
args any <repeatable>

The arguments to be passed to the wrapped function
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionCallbackArgs(…args) → {Trigger}

Source:

When triggered, this action sets the arguments of the callback function. If no callback function is specified, this action has no meaningful impact.

Parameters:
Name Type Attributes Description
args any <repeatable>

The arguments to pass to the callback function.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionCallbackContext(context) → {Trigger}

Source:

When triggered, this action sets the this context of the callback function. If no callback function is specified, this action has no meaningful impact.

Parameters:
Name Type Description
context any

The this context to use when calling the callback function.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionCallbackFunction(fn) → {Trigger}

Source:

When triggered, this action will callback the function specified by fn. It may be combined with actionCallbackContext and actionCallbackArgs to specify the this context and arguments to pass to the callback.

Parameters:
Name Type Description
fn function

The function to be called as a callback. This function is called after the completion of all Triggers.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionCallbackToArg(num) → {Trigger}

Source:

Similar to actionCallbackFunction, but treats one the arguments specified by the index num as the callback function. It will throw an Error if the argument at num is not a function. It may be combined with actionCallbackContext and actionCallbackArgs to specify the this context and arguments to pass to the callback.

Parameters:
Name Type Description
num Number

The index into the array of arguments, where the resulting argument will be treated as a callback function. This function is called after the completion of all Triggers.
Throws:

If the argument at num is not a function.

Type
Error
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionCallContext(args) → {Trigger}

Source:

When triggered, sets the context (this value) of the function to the object specified by ctx

Parameters:
Name Type Description
args ctx

The context to be passed to the wrapped function
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionCustom(fn) → {Trigger}

Source:

Specifies a custom action that will be run when triggered.

Parameters:
Name Type Description
fn Trigger~customActionCallback

The function to be run when this action is triggered.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionReturn(retVal) → {Trigger}

Source:

When triggered, this action will change the return value of a function call or property get to the value specified by retVal.

Parameters:
Name Type Description
retVal any

The value that will be returned by the function or property when this action is triggered.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionReturnContext() → {Trigger}

Source:

When triggered, this action sets the return value to the this value of the function.

Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionReturnFromArg(num) → {Trigger}

Source:

When triggered this action will set the return value to the value of the argumennt list specified by the index num

Example
var anon = new Wrapper();

w.triggerAlways().actionReturnFromArg(2);

var ret = anon("I", "like", "sleeping");
console.log (ret); // "sleeping"
Parameters:
Name Type Description
num Number

The index of the argument list to return when the wrapper is called. As an index, this 0 represents the first value, 1 the second, etc.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionReturnFromContext(prop) → {Trigger}

Source:

When triggered, this action sets the return value to a property on the this value that is specified by the prop value.

Parameters:
Name Type Description
prop String

The property on the this context that should be returned when the Wrapper is called.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionReturnRejectedPromise(err) → {Trigger}

Source:

Similar to actionReturnPromise, this action causes the Wrapper to return a Promise, but in this case the Promise is one that has been rejected (that is, failed).

Parameters:
Name Type Description
err Error | null

An instance of Error, or inheriting from Error, that will be the error the Promise resolves to. This will appear as the error argument that is passed to the .catch() call on the Promise.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionReturnResolvedPromise(retValopt) → {Trigger}

Source:

When triggered, this action causes the Wrapper to return a resolved (that is, successful) Promise. If a retVal argument is provided, it will be the value that the Promise resolves to. If no retVal is provided, then whatever value the Wrapper would have returned is wrapped in a promise.

Parameters:
Name Type Attributes Description
retVal any <optional>

The optional return value to wrap. If this is not specified, the value that is returned by the Wrapper will be used.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionSetVal(setVal) → {Trigger}

Source:

When triggered, this action behaves as if assigning the value setVal to the property.

Parameters:
Name Type Description
setVal any

The value to be assigned to the property. May be undefined, but requires undefined to be explicitly passed as an argument to the function.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

actionThrowException(err) → {Trigger}

Source:

When triggered, this action throws the error specified by the err argument.

Parameters:
Name Type Description
err Error | null

An instance of Error, or some class inheriting from Error, that will be thrown when this action is triggered. If null is used instead of an Error then nothing will be thrown and it has the effect of clearing any errors that would have been thrown.
Returns:

Returns this Trigger, so that further actions or expectations can be chained.

Type
Trigger

Type Definitions

customActionCallback(current)

Source:

This is the callback for actionCustom. Note that actions get called every time a Trigger executes, which will usually be twice for everytime a Wrapper is called -- once before the call, to modify arguments and context, and once after the call to modify exceptions and return values. Use the current.preCall and current.postCall properties to determine which half of the Wrapper call is occuring.

Parameters:
Name Type Description
current Operation

The currently executing function or property set / get.

triggerCustomCallback(curr) → {Boolean}

Source:

This is the callback that is passed to triggerOnCustom. The most obvious thing to point out is that it returns true when the Trigger should execute, and false when the Trigger shouldn't execute; however, there are some unexpected behaviors with this callback that should be observed.

First, every Trigger callback is called twice for every time the Wrapper is executed. The callback is called once just before the Wrapper executes the wrapped function / setter / getter providing the callback with the opportunity to evaluate arguments and context before they are used. The callback is called again just after the wrapped function / setter / getter is called, giving the callback the opportunity to evaluate return values and exceptions.

The first argument to the callback is curr, which is a Operation. curr has the property preCall set to true if the callback is being called before the function / getter / setter; and has the property postCall that is set to true if the callback is being called after the function / getter / setter. curr also has the property curr.wrapper, which references the Wrapper.

Also note that throwing an exception in a custom trigger is not advised since it may adversely effect the behavior of the Wrapper and the running of any subsequent Triggers. If you want the wrapper to throw an exception, set single.exception to a new Error(); however, this is best done through an actionThrowException anyway.

Parameters:
Name Type Description
curr Operation

The current function call or property set / get.
Returns:

Returns true if the actions and expectations associated with the Trigger should run. Returns false if this Trigger should not be executed.

Type
Boolean