Filter

Filter

The Wrapper#historyList on a Wrapper contains all the information about the previous operations perfomed by a wrapper. Being able to easily assess this information is one of the important features of candy-wrapper, and so the historyList is a Filter that allows for easily selecting the parts of the operation history that you are interested in.

Filters have two parts: first, the ability to select the operation records you care about using the filter calls; and second, the ability to perform expect operations on one or more of the operations in the Filter.

The ability to filter the historyList using the filter functions is essentially just syntactic sugar on top of the Array.map() and Array.filter() classes. The methods such as filterByCallArgs and filterByException simply select the elements of the Filter that match the desired attributes. The get methods on the Filter, such as getAllCallArgs or getAllExceptions are just doing a map to create an Array of the features you care about.

There are two different ways of performing expect calls on Filters. The first is to filter down to a single Operation, and perform expectations on that operation. This can be done using filter methods that return a single Operation, such as filterFirst, filterLast or filterByNumber. The other way to perform expect calls on a Filter is by performing an expect on the whole list at once, such as using expectCount.

Note that many of the Filter operations are chainable and combinable to make unique and powerful combinations out of the Filter methods.

Constructor

new Filter()

Source:
Throws:

If first argument isn't a valid Wrapper

Type
TypeError

Extends

  • Array

Methods

expectAll() → {ExpectIterator}

Source:

Expects that all Operation records in the Filter pass the expect function that is chained off this method.

Example
new Wrapper(obj, "method");

// call the method twice with the argument "good"
obj.method("good");
obj.method("good");

// expect that all method calls had the argument "good"
obj.method.historyList.expectAll().expectCallArgs("good"); // true
obj.method.expectReportAllFailure(); // no failures, doesn't throw

// call the method one more time with the argument "bad"
obj.method("bad");

// expect that all method calls had the argument "good"
obj.method.historyList.expectAll().expectCallArgs("good"); // false
obj.method.expectReportAllFailure(); // throws an error
Returns:

Returns an ExpectIterator that applies the next expect call to all the operation records in this Filter. If no expect call is performed, this method effectively does nothing.

Type
ExpectIterator

expectCount(num) → {Boolean}

Source:

Expects that Filter has count members.

Parameters:
Name Type Description
num Number

How many members are expected to be in the Filter
Throws:

If more or less than a single argument, or if the argument received isn't a number

Type
TypeError
Returns:

Returns true if Filter has count Operation records, false otherwise

Type
Boolean

expectCountMax(max) → {Boolean}

Source:

Expects that Filter has at most max members.

Parameters:
Name Type Description
max Number

The maximum number of members that are expected to be in the Filter
Throws:

If first argument isn't of type Number

Type
TypeError
Returns:

Returns true if Filter has less than count members, false otherwise

Type
Boolean

expectCountMin(min) → {Boolean}

Source:

Expects that Filter has at least min members.

Parameters:
Name Type Description
min Number

How least number of members that are expected to be in the Filter
Throws:

If first argument isn't of type Number

Type
TypeError
Returns:

Returns true if arr has at least count Operation records, false otherwise

Type
Boolean

expectCountRange(min, max) → {Boolean}

Source:

Expects that Filter has count members.

Parameters:
Name Type Description
min Number

How the miniumum number of members expected to be in the Filter
max Number

The maximum number of members expected to be in the Filter
Throws:

If min or max arguments aren't of type Number.

Type
TypeError
Returns:

Returns true if Filter has count Operation records, false otherwise

Type
Boolean

expectNone() → {ExpectIterator}

Source:

Similar to expectAll, but the expect function is expected to never be successful.

Example
new Wrapper(obj, "method");

// call the method twice with the argument "good"
obj.method("good");
obj.method("good");

// expect that none of the method calls had the argument "bad"
obj.method.historyList.expectNever().expectCallArgs("bad"); // true
obj.method.expectReportAllFailure(); // no failures, doesn't throw

// call the method one more time with the argument "bad"
obj.method("bad");

// expect that none of the method calls had the argument "bad"
obj.method.historyList.expectNever().expectCallArgs("bad"); // false
obj.method.expectReportAllFailure(); // throws an error
Returns:

Returns an ExpectIterator that applies the next expect call to all the operation records in this Filter. If no expect call is performed, this method effectively does nothing.

Type
ExpectIterator

expectSome() → {ExpectIterator}

Source:

Similar to expectAll, but the expect function is only expected to pass at least once.

Example
new Wrapper(obj, "method");

// call the method twice with the argument "bad"
obj.method("bad");
obj.method("bad");

// expect that some method calls had the argument "good"
obj.method.historyList.exepctSome().expectCallArgs("good"); // false
obj.method.expectReportAllFailure(true); // throws

// call the method one more time with the argument "good"
obj.method("good");

// expect that all method calls had the argument "good"
obj.method.historyList.exepctSome().expectCallArgs("good"); // true
obj.method.expectReportAllFailure(); // no failures, doesn't throw
Returns:

Returns an ExpectIterator that applies the next expect call to all the operation records in this Filter. If no expect call is performed, this method effectively does nothing.

Type
ExpectIterator

filterByCallArgs(…args) → {Filter}

Source:

Returns the members of the Filter that were function calls with arguments matching ...args.

Example
new Wrapper(obj, someMethod); // create a new wrapper

// do some function calls
obj.someMethod("drink", "beer");
obj.someMethod("store", "wine");
obj.someMethod("drink", "beer");
obj.someMethod("store", "beer");
obj.someMethod("martini");

// returns a Filter with the two calls above that match `args[0] === "drink"` and `args[1] === "beer"`
obj.someMethod.historyList.filterByCallArgs("drink", "beer");
Parameters:
Name Type Attributes Description
args any <repeatable>

The function arguments that will be matched
Throws:

If called on a wrapped property

Type
TypeError
Returns:

A Filter continaing the function calls where the function was called with arguments that match ...args.

Type
Filter

filterByCallContext(context) → {Filter}

Source:

Returns the members of the Filter that were function calls with a this context that matches the context argument.

Parameters:
Name Type Description
context Object

The context that the this value of the function will be evaluated against.
Throws:

If called on a wrapped property, or with more than one argument

Type
TypeError
Returns:

A Filter containing the function calls where the this strictly and deeply matched context.

Type
Filter

filterByException(exception) → {Filter}

Source:

Returns the members of the Filter that threw exceptions that exactly matched exception.

Parameters:
Name Type Description
exception Error | null

An Error (or any class that inherits from Error) that will be strictly matched. If exception is null the filter will include all Operation records that did not throw an Error.
Throws:

If called with more or less than one argument, or if the argument passed is not an Error or null

Type
TypeError
Returns:

A Filter containing the function calls or property set / get that threw an Error that matches exception.

Type
Filter

filterByNumber(num) → {Operation}

Source:

Returns the Operation at the position num in the Filter

Parameters:
Name Type Description
num Number

A number indicating the index of the Operation record to be returned. These are "programming numbers" not "counting numbers", so if num is zero it returns the first Operation record, one for the second record, etc.
Throws:

If num is less than zero or larger than the size of the Filter; or if the Filter is empty.

Type
RangeError
Returns:

The operation record at position num in the filter. Same as historyList[num] or historyList[num] but with some light error checking.

Type
Operation

filterByReturn(retVal) → {Filter}

Source:

Returns the members of the Filter that are function calls or property set / get where their return value matches retVal.

Parameters:
Name Type Description
retVal any

The value that will be matched against. May be undefined, but the value undefined must be explicitly passed to filterByReturn.
Throws:

If called with more or less than one argument

Type
TypeError
Returns:

A Filter containing the function calls or property set / get that returned a value stictly matching retVal.

Type
Filter

filterFifth() → {Operation}

Source:
See:

Gets the fifth Operation from the filter. Is the same as filterByNumber(4).

Returns:

The fifth operation record in the Filter

Type
Operation

filterFirst() → {Operation}

Source:
See:

Gets the first Operation from the filter. Is the same as filterByNumber(0).

Returns:

The first operation record in the Filter

Type
Operation

filterFourth() → {Operation}

Source:
See:

Gets the fourth Operation from the filter. Is the same as filterByNumber(3).

Returns:

The fourth operation record in the Filter

Type
Operation

filterLast() → {Operation}

Source:

Similar to filterFirst, but returns the last Operation record in the Filter.

Throws:

If the Filter is empty

Type
RangeError
Returns:

Returns the last operation record in the Filter

Type
Operation

filterOnly() → {Operation}

Source:

Similar to filterFirst, this returns the first member of the Filter; however, it also asserts that it is the ONLY member of the filter and will throw TypeError if there is more than one member in the Filter.

Throws:

If there is more than one member in the Filter.

Type
TypeError
Returns:

Returns the first member of the Filter.

Type
Operation

filterPropGet() → {Filter}

Source:

Returns the members of the Filter that were occurances of when the property was retrieved (i.e. get). Only works for properties.

Throws:

If called on a wrapped property

Type
TypeError
Returns:

Returns a Filter containing just the Operation records when the property was gotten.

Type
Filter

filterPropSet() → {Filter}

Source:

Returns the members of the Filter that were occurances of when the property was set. Only works for properties.

Throws:

If called on a wrapped property

Type
TypeError
Returns:

Returns a Filter containing just the Operation records where a property was set.

Type
Filter

filterPropSetByVal(setVal) → {Filter}

Source:

Returns the members of the Filter that were occurances of when the property was set to setVal

Parameters:
Name Type Description
setVal any

If setVal strictly matches the value of a Operation where the property was set, the record will be included in the results.
Throws:

If called on a wrapped property, or if called with more than one argument

Type
TypeError
Returns:

Returns a Filter containing just the Operation records that are of type set and have a matching setVal.

Type
Filter

filterSecond() → {Operation}

Source:
See:

Gets the second Operation from the filter. Is the same as filterByNumber(1).

Returns:

The second operation record in the Filter

Type
Operation

filterThird() → {Operation}

Source:
See:

Gets the third Operation from the filter. Is the same as filterByNumber(2).

Returns:

The third operation record in the Filter

Type
Operation

getAllCallArgs() → {Array}

Source:

Returns an Array of all the arguments passed to the functions in the Filter

Example
new Wrapper(obj, someMethod); // create a new wrapper

// do some function calls
obj.someMethod("drink", "beer");
obj.someMethod("store", "wine");
obj.someMethod("martini");
obj.someMethod();

var list = obj.someMethod.historyList.getAllCallArgs();
// list is: [["drink", "beer"], ["store", "wine"], ["martini"], [undefined]]
Throws:

If called on a wrapped property an Array of the arguments that were passed to that call. If a function was called without arguments the array will empty (length of 0).

Type
TypeError
Returns:

An Array of argument lists, where each argument list is

Type
Array

getAllCallContexts() → {Array}

Source:

Returns an Array of all the call contexts (this values) that the functions in the Filter were called with

Throws:

If called on a wrapped property

Type
TypeError
Returns:

An Array of call contexts / this values

Type
Array

getAllExceptions() → {Array}

Source:

Returns an Array of all the exceptions (e.g. throw Error()) that the functions in the Filter threw.

Returns:

An Array of exceptions. If no exception was thrown, the value at that position in the array will be null.

Type
Array

getAllReturns() → {Array}

Source:

Returns an Array of all the returnValues from function calls or property set / get.

Returns:

An Array of all return values. If a function call didn't return a value, the value at that location in the array will be undefined.

Type
Array

getAllSetVals() → {Array}

Source:

Returns an Array of all the values a property was set to.

Throws:

If called on a wrapped function

Type
TypeError
Returns:

An Array of the values the property was set to.

Type
Array