Skip to content
This repository

Jasmine has several built-in matchers. Here are a few:

expect(x).toEqual(y); compares objects or primitives x and y and passes if they are equivalent

expect(x).toBe(y); compares objects or primitives x and y and passes if they are the same object

expect(x).toMatch(pattern); compares x to string or regular expression pattern and passes if they match

expect(x).toBeDefined(); passes if x is not undefined

expect(x).toBeUndefined(); passes if x is undefined

expect(x).toBeNull(); passes if x is null

expect(x).toBeTruthy(); passes if x evaluates to true

expect(x).toBeFalsy(); passes if x evaluates to false

expect(x).toContain(y); passes if array or string x contains y

expect(x).toBeLessThan(y); passes if x is less than y

expect(x).toBeGreaterThan(y); passes if x is greater than y

expect(function(){fn();}).toThrow(e); passes if function fn throws exception e when executed

The old matchers toNotEqual, toNotBe, toNotMatch, and toNotContain have been deprecated and will be removed in a future release. Please change your specs to use not.toEqual, not.toBe, not.toMatch, and not.toContain respectively.

Every matcher's criteria can be inverted by prepending .not:

expect(x).not.toEqual(y); compares objects or primitives x and y and passes if they are not equivalent

Writing New Matchers

We've provided a small set of matchers that cover many common situations. However, we recommend that you write custom matchers when you want to assert a more specific sort of expectation. Custom matchers help to document the intent of your specs, and can help to remove code duplication in your specs.

It's easy to add new matchers for your app. A matcher function receives the actual value as a parameter, and zero or more additional arguments may be passed in the function call. The function should return on object with a pass attribute set to true if the actual value passes the matcher's requirements, and false if it does not. The matcher function should be set as the compare property of an object returned by an enclosing function.

Here's the definition of toBeLessThan():

toBeLessThan: function() {
  return {
    compare: function(actual, expected) {
      return {
        pass: actual < expected
      };
    }
  };
}

To add the matcher to your suite, call jasmine.addMatchers() from within a before or it block. Call it with an object mapping matcher name to function:

beforeEach(function() {
  jasmine.addMatchers({
    toBeExponentiallyLessThan: function() {
      return {
        compare: function(actual, expected, scaleFactor) {
          return {
            pass: actual < (expected / (10 || scaleFactor))
          };
        }
      };
    }
  });
});

The default failure message is Expected [actual.toString()] [matcher name converted from camel-case to space-separated] [values of additional parameters]. To customize the success/failure messages, inside the matching function assign a message property on the returned object:

beforeEach(function() {
  jasmine.addMatchers({

    toBeExponentiallyLessThan: function() {
      return {
        compare: function(actual, expected, scaleFactor) {
          var result = {
            pass: actual < (expected / (10 || scaleFactor))
          };
          if (result.pass) {
            result.message = actual + ' is exponentially less than ' + expected;
          } else {
            result.message = actual + ' is not exponentially less than ' + expected;
          }
          return result;
        }
      };
    }
  });
});
Something went wrong with that request. Please try again.