Matchers

Aaron Jacobs edited this page Aug 26, 2014 · 4 revisions

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.