Matchers

Introduction

A matcher is a special object that can be used with expectThat and expectCall to match only particular kinds of values. This is most clear from some examples:

// Get a number from somewhere.
var someNumber = 17;

// Express some expectations about its value.
expectThat(someNumber, equals(17));       // Passes
expectThat(someNumber, lessOrEqual(17));  // Passes
expectThat(someNumber, greaterThan(17));  // Fails
expectThat(someNumber, isNull);           // Fails

// Expect calls to a mock function with values matching particular regular
// expressions. Return different numbers from each.
var myMockFunc = createMockFunction();

expectCall(myMockFunc)(containsRegExp(/^t.*o$/))
    .willOnce(returnWith(19));

expectCall(myMockFunc)(containsRegExp(/^b.*o$/))
    .willOnce(returnWith(23));

myMockFunc('taco');     // Returns 19
myMockFunc('burrito');  // Returns 23

In the example above, equals(17), lessOrEqual(17), isNull, containsRegExp(/^t.*o$/), and so on are all matchers.

Built-in matchers

Google JS Test comes with a large number of built-in matchers, documented below. For information on how to define your own matchers, see the section further down in this document.

Equality:

• _ (underscore) — Match anything. This does not include missing arguments to mock functions.
• isNull — Match null.
• isUndefined — Match undefined.
• equals(x) — Match values y where x === y. Note that this means matches must be of the same type, and if x is an object (or a function, etc) then matches must be a reference to x itself. Additionally, x and y are considered equal if they are of the same type, x has a gjstestEquals method, and x.gjstestEquals(y) is true.

Booleans:

• evalsToTrue — Match values which, when casted to a boolean, result in true.

• evalsToFalse — Match values which, when casted to a boolean, result in false.

Strings:

• containsRegExp(r) — Match strings that match the regular expression r.
• hasSubstr(s) — Match strings that contain the substring s.

Functions and function arguments:

• throwsError(r) — Match functions which, when executed with zero arguments, throw an error whose string form matches the regular expression r.
• notPresent — Match missing arguments to mock functions. (This is distinct from present arguments with a value of undefined.)
• maybePresent — Equivalent to anyOf([_, notPresent]).
• isMissingArgSentinel — Match gjstest.missingArgSentinel, for use in testing user-defined matchers. See the comments in missing_arg_matchers.js for more details.

Arrays and objects:

• elementsAre(A) — Given an array A of values and/or matchers, match arrays of the same length where each elements is equal to or matches the corresponding element in A.
• contains(x) — Match arrays that contain an element equal to x, or if x is a matcher, that contain an element that matches x.
• whenSorted(M) — Match arrays whose elements, when sorted, match the matcher M.
• recursivelyEquals(x) — Given an object or array x, match objects or arrays whose values are equal to the corresponding value in x, recursing into contained objects and arrays.

Combining matchers:

• not(x) — Invert the meaning of another matcher. If x is not a matcher, it is treated as the matcher equals(x).
• allOf([x1, x2, x3, ...]) — Match objects that match x1 and match x2 and … . If any xn is not a matcher, it is treated as equals(xn).
• anyOf([x1, x2, x3, ...]) — Match objects that match x1 or match x2 or … . If any xn is not a matcher, it is treated as equals(xn).

Numbers:

• greaterOrEqual(x)
• greaterThan(x)
• lessOrEqual(x)
• lessThan(x)
• isNearNumber(x, err) — Given a number x, match numbers y such that |x - y| <= err.

There are also some convenient shorthands:

• expectEq(expected, actual) — equivalent to expectThat(actual, equals(expected))

• expectNe(x, actual) — equivalent to expectThat(actual, not(equals(x)))

• expectGe(a, b) — equivalent to expectThat(a, greaterOrEqual(b))

• expectGt(a, b) — equivalent to expectThat(a, greaterThan(b))

• expectLe(a, b) — equivalent to expectThat(a, lessOrEqual(b))

• expectLt(a, b) — equivalent to expectThat(a, lessThan(b))

• expectTrue(x) — equivalent to expectThat(x, equals(true))

• expectFalse(x) — equivalent to expectThat(x, equals(false))

Defining your own matchers

A matcher is simply an instance of gjstest.Matcher, which requires the following parameters to construct:

• A description of the values matched, used in forming readable error messages.
• An inverted description of the values matched, used in forming readable error messages when the not matcher is involved.
• A function that decides whether any give value should be matched, used for evaluating expectations.

For more information on defining your own matchers see the documentation in matcher_types.js, and use the built-in matchers as examples.