JsHamcrest.Matchers — Built-in Matchers

Built-in matcher library.

Collection Matchers

JsHamcrest.Matchers.empty()

The length of the actual value must be zero:

assertThat([], empty());
assertThat('', empty());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.everyItem(matcherOrValue)

The actual value should be an array and matcherOrValue must match all items:

assertThat([1,2,3], everyItem(greaterThan(0)));
assertThat([1,'1'], everyItem(1));

Parameters:matcherOrValue – Instance of JsHamcrest.SimpleMatcher or a value. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.hasItem(matcherOrValue)

The actual value should be an array and it must contain at least one value that matches matcherOrValue:

assertThat([1,2,3], hasItem(equalTo(3)));
assertThat([1,2,3], hasItem(3));

Parameters:matcherOrValue – Instance of JsHamcrest.SimpleMatcher or a value. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.hasItems(MatchersOrValues...)

The actual value should be an array and matchersOrValues must match at least one item:

assertThat([1,2,3], hasItems(2,3));
assertThat([1,2,3], hasItems(greaterThan(2)));
assertThat([1,2,3], hasItems(1, greaterThan(2));

Parameters:MatchersOrValues – Matchers and/or values. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.hasSize(matcherOrValue)

The length of the actual value value must match matcherOrValue:

assertThat([1,2,3], hasSize(3));
assertThat([1,2,3], hasSize(lessThan(5)));
assertThat('string', hasSize(6));
assertThat('string', hasSize(greaterThan(3)));
assertThat({a:1, b:2}, hasSize(equalTo(2)));

Parameters:matcherOrValue – Instance of JsHamcrest.SimpleMatcher or a value. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.isIn(item...)

The given array or arguments must contain the actual value:

assertThat(1, isIn([1,2,3]));
assertThat(1, isIn(1,2,3));

Parameters:item... – Array or list of values. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.oneOf()

Alias to isIn() function.

Core Matchers

JsHamcrest.Matchers.allOf(matchersOrValues...)

All matchesOrValues must match the actual value. This matcher behaves pretty much like the JavaScript && (and) operator:

assertThat(5, allOf([greaterThan(0), lessThan(10)]));
assertThat(5, allOf([5, lessThan(10)]));
assertThat(5, allOf(greaterThan(0), lessThan(10)));
assertThat(5, allOf(5, lessThan(10)));

Parameters:matchersOrValues – Instances of JsHamcrest.SimpleMatcher and/or values. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.anyOf(matchersOrValues)

At least one of the matchersOrValues should match the actual value. This matcher behaves pretty much like the || (or) operator:

assertThat(5, anyOf([even(), greaterThan(2)]));
assertThat(5, anyOf(even(), greaterThan(2)));

Parameters:matchersOrValues – Instances of JsHamcrest.SimpleMatcher and/or values. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.anything()

Useless always-match matcher:

assertThat('string', anything());
assertThat(null, anything());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.both(matcherOrValue)

Combinable matcher where the actual value must match all the given matchers or values:

assertThat(10, both(greaterThan(5)).and(even()));

Parameters:matcherOrValue – Instance of JsHamcrest.SimpleMatcher or a value. Returns:Instance of JsHamcrest.CombinableMatcher.

JsHamcrest.Matchers.either(matcherOrValue)

Combinable matcher where the actual value must match at least one of the given matchers or values:

assertThat(10, either(greaterThan(50)).or(even()));

Parameters:matcherOrValue – Instance of JsHamcrest.SimpleMatcher or a value. Returns:Instance of JsHamcrest.CombinableMatcher.

JsHamcrest.Matchers.equalTo(expected)

The actual value must be equal to expected:

assertThat('10', equalTo(10));

Parameters:expected – Expected value. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.is(matcherOrValue)

Delegate-only matcher frequently used to improve readability:

assertThat('10', is(10));
assertThat('10', is(equalTo(10)));

Parameters:matcherOrValue – Instance of JsHamcrest.SimpleMatcher or a value. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.nil()

The actual value must be null or undefined:

var undef;
assertThat(undef, nil());
assertThat(null, nil());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.not(matcherOrValue)

The actual value must not match matcherOrValue:

assertThat(10, not(20));
assertThat(10, not(equalTo(20)));

Parameters:matcherOrValue – Instance of JsHamcrest.SimpleMatcher or a value. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.raises(exceptionName)

The actual value is a function and, when invoked, it should thrown an exception with the given name:

var MyException = function(message) {
    this.name = 'MyException';
    this.message = message;
};

var myFunction = function() {
    // Do something dangerous...
    throw new MyException('Unexpected error');
};

assertThat(myFunction, raises('MyException'));

Parameters:exceptionName – Name of the expected exception. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.raisesAnything()

The actual value is a function and, when invoked, it should raise any exception:

var myFunction = function() {
    // Do something dangerous...
    throw 'Some unexpected error';
};

assertThat(myFunction, raisesAnything());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.sameAs(expected)

The actual value must be the same as expected:

var number = 10, anotherNumber = number;
assertThat(number, sameAs(anotherNumber));

Parameters:expected – Expected value. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.truth()

The actual value must be any value considered truth by the JavaScript engine:

var undef;
assertThat(10, truth());
assertThat({}, truth());
assertThat(0, not(truth()));
assertThat('', not(truth()));
assertThat(null, not(truth()));
assertThat(undef, not(truth()));

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.equivalentMap(expected)

The actual value must be equivalent to expected. This works for maps with nested arrays and maps:

var firstMap = {"key" : 1, "key2" : "String"};
var equivMap = {"key" : 1, "key2" : "String"};

assertThat(firstMap, equivalentMap(equivMap));

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.equivalentArray(expected)

The actual value must be equivalent to expected. This works for arrays with nested arrays and maps:

var firstArray = [ 1, "String"];
var equivArray = [ 1, "String"];

assertThat(firstArray, equivalentArray(equivArray));

Returns:Instance of JsHamcrest.SimpleMatcher.

Number Matchers

JsHamcrest.Matchers.between(start)

The actual number must be between the given range (inclusive):

assertThat(5, between(4).and(7));

Parameters:start – Range start. Returns:Builder object with an end() method, which returns a JsHamcrest.SimpleMatcher instance and thus should be called to finish the matcher creation.

JsHamcrest.Matchers.closeTo(expected[, delta])

The actual number must be close enough to expected, that is, the actual number is equal to a value within some range of acceptable error:

assertThat(0.5, closeTo(1.0, 0.5));
assertThat(1.0, closeTo(1.0, 0.5));
assertThat(1.5, closeTo(1.0, 0.5));
assertThat(2.0, not(closeTo(1.0, 0.5)));

Parameters:

• expected – Expected number.
• delta – (Optional, default=0) Expected difference delta.

Returns:

Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.divisibleBy(divisor)

The actual value must be divisible by divisor:

assertThat(21, divisibleBy(3));

Parameters:divisor – Divisor. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.even()

The actual number must be even:

assertThat(4, even());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.greaterThan(expected)

The actual number must be greater than expected:

assertThat(10, greaterThan(5));

Parameters:expected – Expected number. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.greaterThanOrEqualTo(expected)

The actual number must be greater than or equal to expected:

assertThat(10, greaterThanOrEqualTo(5));

Parameters:expected – Expected number. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.lessThan(expected)

The actual number must be less than expected:

assertThat(5, lessThan(10));

Parameters:expected – Expected number. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.lessThanOrEqualTo(expected)

The actual number must be less than or equal to expected:

assertThat(5, lessThanOrEqualTo(10));

Parameters:expected – Expected number. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.notANumber()

The actual value must not be a number:

assertThat(Math.sqrt(-1), notANumber());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.odd()

The actual number must be odd:

assertThat(5, odd());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.zero()

The actual number must be zero:

assertThat(0, zero());
assertThat('0', not(zero()));

Returns:Instance of JsHamcrest.SimpleMatcher.

Object Matchers

JsHamcrest.Matchers.bool()

The actual value must be a boolean:

assertThat(true, bool());
assertThat(false, bool());
assertThat("text" not(bool()));

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.func()

The actual value must be a function:

assertThat(function() {}, func());
assertThat("text", not(func()));

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.hasFunction(functionName)

The actual value has a function with the given name:

var greeter = {
    sayHello: function(name) {
        alert('Hello, ' + name);
    }
};

assertThat(greeter, hasFunction('sayHello'));

Parameters:functionName – Function name. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.hasMember(memberName[, matcherOrValue])

The actual value has an attribute with the given name:

var greeter = {
    marco: 'polo',
    sayHello: function(name) {
        alert('Hello, ' + name);
    }
};

assertThat(greeter, hasMember('marco'));
assertThat(greeter, hasMember('sayHello'));

It’s also possible to match the member’s value if necessary:

assertThat(greeter, hasMember('marco', equalTo('polo')));

Parameters:

• memberName – Member name.
• matcherOrValue – Matcher used to match the member’s value.

Returns:

Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.instanceOf(clazz)

The actual value must be an instance of clazz:

assertThat([], instanceOf(Array));

Parameters:clazz – Constructor function. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.number()

The actual value must be a number:

assertThat(10, number());
assertThat('10', not(number()));

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.object()

The actual value must be an object:

assertThat({}, object());
assertThat(10, not(object()));

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.string()

The actual value must be an string:

assertThat('10', string());
assertThat(10, not(string());

Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.typeOf(typeName)

The actual value must be of the given type:

assertThat(10, typeOf('number'));
assertThat({}, typeOf('object'));
assertThat('10', typeOf('string');
assertThat(function(){}, typeOf('function'));

Parameters:typeName – Name of the type. Returns:Instance of JsHamcrest.SimpleMatcher.

Text Matchers

JsHamcrest.Matchers.containsString(str)

The actual string must have a substring equals to str:

assertThat('string', containsString('tri'));

Parameters:str – Substring. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.emailAddress()

The actual string must look like an e-mail address:

assertThat('[email protected]', emailAddress());

Returns:Instance of JsHamcrest.SimpleMatcher.

Warning

This matcher is not fully compliant with RFC2822 due to its complexity.

JsHamcrest.Matchers.endsWith(str)

The actual string must end with str:

assertThat('string', endsWith('ring'));

Parameters:str – String. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.equalIgnoringCase(str)

The actual string must be equal to str, ignoring case:

assertThat('str', equalIgnoringCase('Str'));

Parameters:str – String. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.matches(regex)

The actual string must match regex:

assertThat('0xa4f2c', matches(/\b0[xX][0-9a-fA-F]+\b/));

Parameters:regex – Regular expression. Returns:Instance of JsHamcrest.SimpleMatcher.

JsHamcrest.Matchers.startsWith(str)

The actual string must start with str:

assertThat('string', startsWith('str'));

Parameters:str – String. Returns:Instance of JsHamcrest.SimpleMatcher.

See also

JsHamcrest API Reference