exception

Exception asserter.

Assert that the actual value is an exception. The exception() asserter provides adapted assertions for works on an exception.

See also the spec of "exception" asserter for more examples.

Example

var trigger = function(){
  throw new Error('Whoops !');
};

test.exception(trigger);

Methods

is(expected)


Assert actual exception equality by content and if possible, recursively.

Also handles circular and self-referential objects.

For most parts it asserts strict equality (===), but:

  • Boolean objects are compared to boolean literals.
  • Number objects are compared to number literals.
  • String objects are compared to string literals.
  • RegExp objects are compared by their pattern and flags.
  • Date objects are compared by their value.
  • Array objects are compared recursively.
  • NaNs are considered equivalent.
  • Instances of the same class with a valueOf function are compared by its output.
  • Plain objects and instances of the same class are compared recursively.

Does not coerce types so mismatching types fail. Inherited enumerable properties are also taken into account.

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example
var error = new Error('Whoops !');
var trigger = function(){ 
  throw error; 
}; 
 
test 
  .exception(trigger)
    .is(error)
    .is(new Error('Whoops !'))
;
 

See also

isNot(expected)


Assert actual exception to the negative equality by content and if possible, recursively.

Also handles circular and self-referential objects.

For most parts it asserts strict (!==), but:

  • Boolean objects are compared to boolean literals.
  • Number objects are compared to number literals.
  • String objects are compared to string literals.
  • RegExp objects are compared by their pattern and flags.
  • Date objects are compared by their value.
  • Array objects are compared recursively.
  • NaNs are considered equivalent.
  • Instances of the same class with a valueOf function are compared by its output.
  • Plain objects and instances of the same class are compared recursively.

Does not coerce types so mismatching types fail. Inherited enumerable properties are also taken into account.

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example
var error = new Error('Whoops !');
var trigger = function(){ 
  throw error; 
}; 

test.exception(trigger).isNot({message: 'Whoops !'});
 

See also

isIdenticalTo(expected)


Assert that the actual exception is identical to (===) expected value.

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example
var error = new Error('Whoops !'); 
var trigger = function(){
 throw error;
}; 

test.exception(trigger).isIdenticalTo(error);

See also

isNotIdenticalTo(expected)


Assert that the actual exception is not identical to (!==) expected value.

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example
var error = new Error('Whoops !'); 
var trigger = function(){
 throw error;
}; 

test.exception(trigger).isNotIdenticalTo(new Error('Whoops !'));

See also

isEqualTo(expected)


Assert that the actual exception is equal to (==) the expected value.

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example
var error = new Error('Whoops !'); 
var trigger = function(){
 throw error;
}; 

test.exception(trigger).isEqualTo(error);

See also

isNotEqualTo(expected)


Assert that the actual exception is not equal to (!=) the expected value.

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example

var error = new Error('Whoops !'); 
var trigger = function(){
 throw error;
}; 

test.exception(trigger).isNotEqualTo(new Error('Whoops !'));

See also

match(expected)


Assert actual exception to match the expected value.

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected matches

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops!');
  })
  .match('Whoops!')
  .match(/Whoops/)
  .match(function(exception){ 
    return (exception instanceof Error) && /whoops/i.test(exception); 
  })
;

See also

notMatch(expected)


Assert actual exception to not match the expected value.

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected value that must not match

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops!');
  })
  .notMatch('Yeah an error')
  .notMatch(/Yeah/)
  .notMatch(function(exception){ 
    return /yeah/.test(exception);
  })
;
 

See also

isValid(expected)


Alias of match().

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected matches

Returns
Type Description
Object

The current instance

Example
test
 .exception(function(){
   throw new Error('Whoops!');
 })
 .isValid('Whoops!')
 .isValid(/Whoops/)
 .isValid(function(exception){ 
   return (exception instanceof Error) && /whoops/i.test(exception); 
 })
;

See also

isNotValid(expected)


Alias of notMatch().

Parameters
Name Type Description
expected
String
Number
RegExp
function

Expected matches

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops!');
  })
  .isNotValid('Yeah an error')
  .isNotValid(/Yeah/)
  .isNotValid(function(exception){ 
    return /yeah/.test(exception);
  })
;

See also

isType(expected)


Assert that the type of actual exception is the given expected value (using typeof operator).

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isType('object')
  
  .exception(function(){
    throw 'Whoops !';
  })
  .isType('string')
;

See also

isNotType(expected)


Assert that the type of actual exception is not the given expected value (using typeof operator).

Parameters
Name Type Description
expected
mixed

Expected value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isNotType('string')
  
  .exception(function(){
    throw 'Whoops !';
  })
  .isNotType('object')
;
 

See also

isObject()


Assert that the type of actual exception is object (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isObject()
;
 

See also

isArray()


Assert that the type of actual exception is array (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw ['error'];
  })
  .isArray()
;

See also

isString()


Assert that the type of actual exception is string (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw 'error';
  })
  .isString()
;

See also

isNumber()


Assert that the type of actual exception is number (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw 0;
  })
  .isNumber()
;

See also

isBool()


Alias of isBoolean().

Assert that the type of actual exception is boolean (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw false;
  })
  .isBool()
;

See also

isBoolean()


Assert that the type of actual exception is boolean (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw false;
  })
  .isBoolean()
;

See also

isNull()


Assert that the type of actual exception is null (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw null;
  })
  .isNull()
;

See also

isUndefined()


Assert that the type of actual exception is undefined (using typeof operator).

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw undefined;
  })
  .isUndefined()
;

See also

isRegExp()


Assert that the actual exception is an instance of RegExp.

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new RegExp('whoops');
  })
  .isRegExp()
;

See also

isNotRegExp()


Assert that the actual exception is not an instance of RegExp.

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isNotRegExp()
;

See also

isDate()


Assert that the actual exception is an instance of Date.

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Date();
  })
  .isDate()
;

See also

isNotDate()


Assert that the actual exception is not an instance of Date.

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isNotDate()
;

See also

isArguments()


Assert that the actual exception is the arguments object provided in a function.

Returns
Type Description
Object

The current instance

Example
var error = function(){
  return arguments;
}; 

test
  .exception(function(){
    throw error(1, 2, 3);
  })
  .isArguments()
;

See also

isNotArguments()


Assert that the actual exception is not the arguments object provided in a function.

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isNotArguments()
;

See also

isEmpty()


Assert that the actual exception is empty.

Checks either the length for arrays or the count of enumerable keys. Inherited keys also counted. Note: an instance of Error has no enumerable properties.

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw '';
  })
  .isEmpty()
  
  .exception(function(){
    throw [];
  })
  .isEmpty()
  
  .exception(function(){
    throw {};
  })
  .isEmpty() 
  
  // Indeed, an instance of `Error` has no enumerable properties. 
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isEmpty()
;

See also

isNotEmpty()


Assert that the actual exception is not empty.

Checks either the length for arrays or the count of enumerable keys. Inherited keys also counted. Note: an instance of Error has no enumerable properties.

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw 'Whoops !';
  })
  .isNotEmpty()
;

See also

isError()


Assert that the actual exception is an Error instance.

Returns
Type Description
Object

The current instance

Example
// trigger
var trigger = function(){
  throw new Error("I'm a ninja !") 
};

test.exception(trigger).isError();

hasLength(expected)


Assert that the actual exception has a length property equal to expected number.

Parameters
Name Type Description
expected
number

Expected length

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasLength(2)
;

See also

hasNotLength(expected)


Assert that the actual exception has not a length property equal to expected number.

Parameters
Name Type Description
expected
number

Expected length

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasNotLength(1)
  .hasNotLength(3)
;

See also

isEnumerable(property)


Assert that the actual exception has an enumerable property. It will fail if the actual value lacks the property entirely.

This also checks inherited properties in the prototype chain, something which Object.prototype.propertyIsEnumerable itself does not do.

For checking if a property exists and is non-enumerable, see isNotEnumerable().

Parameters
Name Type Description
property
String

The property name

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .isEnumerable('message')
  .isEnumerable('code')
;

See also

isNotEnumerable(property)


Assert that the actual exception has a non-enumerable property. It will fail if the actual value lacks the property entirely.

This also checks inherited properties in the prototype chain, something which Object.prototype.propertyIsEnumerable itself does not do.

It's the inverse of isEnumerable().

Parameters
Name Type Description
property
String

The property name

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isNotEnumerable('message')
;

See also

isFrozen()


Assert that the actual exception is frozen with Object.isFrozen.

Returns
Type Description
Object

The current instance

Example
var frozenError = {message: 'error', code: 42};

Object.freeze(frozenError);

test
  .exception(function(){
    throw frozenError;
  })
  .isFrozen()
;

See also

isNotFrozen()


Assert that the actual exception is not frozen with Object.isFrozen.

Returns
Type Description
Object

The current instance

Example

test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isNotFrozen()
;

See also

isInstanceOf(expected)


Assert that the actual exception is an instance of expected value.

Uses actual instanceof expected.

Parameters
Name Type Description
expected
Object

Expected instance

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new TypeError('Whoops !');
  })
  .isInstanceOf(TypeError)
;

See also

isNotInstanceOf(expected)


Assert that the actual exception is not an instance of expected value.

Uses actual instanceof expected === false.

Parameters
Name Type Description
expected
Object

Expected instance

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .isNotInstanceOf(TypeError)
;
 

See also

hasProperty(property, value)


Assert that the actual tested exception has property. Optionally assert it equals (===) to value argument.

Takes inherited properties into account. To not do so, see hasOwnProperty().

Parameters
Name Type Argument Description
property
String

The property name

value
mixed
optional 

The property value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasProperty('message')
  .hasProperty('code', 42)
  
  .exception(function(){
    throw new Error('Whoops !');
  })
  .hasProperty('message')
  .hasProperty('message', 'Whoops !')
  .hasProperty('constructor')
; 

See also

hasNotProperty(property, value)


Assert that the actual tested exception has not a property. Optionally assert it not equals (!==) to value argument.

Takes inherited properties into account. To not do so, see hasNotOwnProperty().

Parameters
Name Type Argument Description
property
String

The property name

value
mixed
optional 

The property value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasNotProperty('foo')
  .hasNotProperty('code', 1) 
;

See also

hasOwnProperty(property, value)


Assert that the actual tested exception has own property. Optionally assert it equals (===) to value argument.

Does not take inherited properties into account. To do so, see hasProperty().

Parameters
Name Type Argument Description
property
String

The property name

value
mixed
optional 

The property value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  }) 
  .hasOwnProperty('message')
  .hasOwnProperty('message', 'Whoops !') 
;

See also

hasNotOwnProperty(property, value)


Assert that the actual tested exception has not own property. Optionally assert it not equals (!==) to value argument.

Does not take inherited properties into account. To do so, see hasNotProperty().

Parameters
Name Type Argument Description
property
String

The property name

value
mixed
optional 

The property value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops !');
  })
  .hasNotOwnProperty('foo')
  .hasNotOwnProperty('message', 'Grrrr !')
  .hasNotOwnProperty('constructor') 
;

See also

hasProperties(properties)


Assert that the actual exception has only the expected enumerable properties. Pass an array of strings as properties.

Takes inherited properties into account. To not do so, see hasOwnProperties().

Parameters
Name Type Description
properties
Array

An array of expected properties

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasProperties(['message', 'code']) 
;

See also

hasNotProperties(properties)


Assert that the actual exception has not the enumerable properties. Pass an array of strings as properties.

Takes inherited properties into account. To not do so, see hasNotOwnProperties().

Parameters
Name Type Description
properties
Array

An array of properties

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasNotProperties(['foo', 'bar'])
  .hasNotProperties(['foo', 'code', 'bar']) 
;

See also

hasOwnProperties(properties)


Assert that the actual exception has only the expected enumerable properties of its own. Pass an array of strings as properties.

Does not take inherited properties into account. To do so, see hasProperties.

Parameters
Name Type Description
properties
Array

An array of expected properties

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasOwnProperties(['message', 'code'])
;
 

See also

hasKey(key, value)


Alias of hasProperty()

Assert that the actual tested exception has a key. Optionally assert it equals (===) to value argument.

Takes inherited properties into account. To not do so, see hasOwnProperty().

Parameters
Name Type Argument Description
key
String

The key name

value
mixed
optional 

The key value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasKey('message')
  .hasKey('code', 42)
  
  .exception(function(){
    throw new Error('Whoops !');
  })
  .hasKey('message')
  .hasKey('message', 'Whoops !')
  .hasKey('constructor')
;

See also

notHasKey(key, value)


Alias of hasNotProperty()

Assert that the actual tested exception has not a key. Optionally assert it not equals (!==) to value argument.

Takes inherited properties into account. To not do so, see hasNotOwnProperty().

Parameters
Name Type Argument Description
key
String

The key name

value
mixed
optional 

The key value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .notHasKey('foo')
  .notHasKey('code', 1) 
;

See also

hasKeys(keys)


Alias of hasProperties()

Assert that the actual exception has only the expected enumerable keys. Pass an array of strings as keys.

Takes inherited properties into account. To not do so, see hasOwnProperties().

Parameters
Name Type Description
keys
Array

An array of expected keys

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasKeys(['message', 'code']) 
;

See also

notHasKeys(keys)


Alias of hasNotProperties()

Assert that the actual exception has not the enumerable keys. Pass an array of strings as keys.

Takes inherited properties into account. To not do so, see hasNotOwnProperties().

Parameters
Name Type Description
keys
Array

An array of keys

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .notHasKeys(['foo', 'bar'])
  .notHasKeys(['foo', 'code', 'bar']) 
;

See also

hasValue(expected)


Assert that the actual tested exception has expected value.

For strings it checks the text, for arrays it checks elements and for objects the property values. Everything is checked with strict equals (===).

Parameters
Name Type Description
expected
mixed

The expected value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasValue('error')
  .hasValue(42)
;

See also

notHasValue(expected)


Assert that the actual tested exception not has expected value.

For strings it checks the text, for arrays it checks elements and for objects the property values. Everything is checked with strict equals (!==).

Parameters
Name Type Description
expected
mixed

The expected value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .notHasValue('err')
  .notHasValue(2)
;

See also

hasValues(expected)


Assert that the actual tested exception has several expected values passed in an array of expected values.

Parameters
Name Type Description
expected
Array

An array of expected values

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .hasValues(['error'])
  .hasValues(['error', 42]) 
;

See also

notHasValues(expected)


Assert that the actual tested exception not has several expected values passed in an array of expected values.

Parameters
Name Type Description
expected
Array

An array of expected values

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw {message: 'error', code: 42};
  })
  .notHasValues(['code'])
  .notHasValues(['message', 'code', 'foo'])
;

See also

contains(expected)


Assert that the actual exception to contain something (===) to expected within depth.

Parameters
Name Type Description
expected
Array

[, other_excepted_values] The expected value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops');
  })
  .contains({message: 'Whoops'}) 
;

See also

notContains(expected)


Assert that the actual exception to not contain something (!==) to expected within depth.

Parameters
Name Type Description
expected
Array

[, other_excepted_values] The expected value

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops');
  })
  .notContains({message: 'foo'}) 
;

See also

startsWith(str)


Assert that the actual exception (string) starts with str.

Parameters
Name Type Description
str
String

Expected string value

Returns
Type Description
Object

The current instance

Example
test 
  .exception(function(){
    throw 'An error occured';
  })
  .startsWith('An error')
;

See also

notStartsWith(str)


Assert that the actual exception (string) not starts with str.

Parameters
Name Type Description
str
String

Expected string value

Returns
Type Description
Object

The current instance

Example
test 
  .exception(function(){
    throw 'An error occured';
  })
  .notStartsWith('error')
;

See also

endsWith(str)


Assert that the actual exception (string) ends with str.

Parameters
Name Type Description
str
String

Expected string value

Returns
Type Description
Object

The current instance

Example
test 
  .exception(function(){
    throw 'An error occured';
  })
  .endsWith('occured')
;

See also

notEndsWith(str)


Assert that the actual exception (string) not ends with str.

Parameters
Name Type Description
str
String

Expected string value

Returns
Type Description
Object

The current instance

Example
test 
 .exception(function(){
   throw 'An error occured';
 })
 .notEndsWith('error')
  ;
  

See also

hasMessage(expected)


Alias of match().

Assert that the actual exception has an expected message.

Parameters
Name Type Description
expected
String
RegExp

Expected message

Returns
Type Description
Object

The current instance

Example
test
  .exception(function(){
    throw new Error('Whoops!');
  })
  .hasMessage('Whoops!')
  .hasMessage(/Whoops/)
;

See also