jasmine-expect

Jasmine-Matchers

What	A huge library of test matchers for a range of common use-cases, compatible with all versions of Jasmine and Jest.
Why	Custom Matchers make tests easier to read and produce relevant and useful messages when they fail.
How	By avoiding vague messages such as "expected false to be true" in favour of useful cues such as "expected 3 to be even number" and avoiding implementation noise such as expect(cycleWheels % 2 === 0).toEqual(true) in favour of simply stating that you expect(cycleWheels).toBeEvenNumber().

Jasmine Matchers is written using the add-matchers library. If you have some useful matchers of your own that you could share with other Jest and Jasmine users, please give it a try.

Sponsors

Contents

• Installation
• Matchers
  • Jasmine's Default Matchers
  • Arrays
  • Booleans
  • Dates
  • Functions and Errors
  • Numbers
  • Strings
  • Objects
  • Regular Expressions
  • Members, Properties, Methods
• Asymmetric Matchers
  • Jasmine's Default Asymmetric Matchers
  • Arrays
  • Dates
  • Numbers
  • Strings
  • Objects
• Integration
  • Browser
  • Jest
  • Karma
  • Node.js
  • Sublime Text
  • Tern
• Browser Support

Installation

Platform	Instructions
npm	npm install jasmine-expect --save-dev
Bower	bower install jasmine-expect --save-dev
Manual	Downloads are available on the releases page.

Matchers

Jasmine's Default Matchers

The Jasmine testing framework from Pivotal Labs comes with this default set of matchers;

expect(array).toContain(member);
expect(fn).toThrow(string);
expect(fn).toThrowError(string);
expect(instance).toBe(instance);
expect(mixed).toBeDefined();
expect(mixed).toBeFalsy();
expect(mixed).toBeNull();
expect(mixed).toBeTruthy();
expect(mixed).toBeUndefined();
expect(mixed).toEqual(mixed);
expect(mixed).toMatch(pattern);
expect(number).toBeCloseTo(number, decimalPlaces);
expect(number).toBeGreaterThan(number);
expect(number).toBeLessThan(number);
expect(number).toBeNaN();
expect(spy).toHaveBeenCalled();
expect(spy).toHaveBeenCalledTimes(number);
expect(spy).toHaveBeenCalledWith(...arguments);

Arrays

Matcher	Example
toBeArray	expect(array).toBeArray();
toBeArrayOfBooleans	expect(array).toBeArrayOfBooleans();
toBeArrayOfNumbers	expect(array).toBeArrayOfNumbers();
toBeArrayOfObjects	expect(array).toBeArrayOfObjects();
toBeArrayOfSize	expect(array).toBeArrayOfSize(number);
toBeArrayOfStrings	expect(array).toBeArrayOfStrings();
toBeEmptyArray	expect(array).toBeEmptyArray();
toBeNonEmptyArray	expect(array).toBeNonEmptyArray();

Booleans

Matcher	Example
toBeBoolean	expect(boolean).toBeBoolean();
toBeFalse	expect(boolean).toBeFalse();
toBeTrue	expect(boolean).toBeTrue();

Dates

Matcher	Example
toBeAfter	expect(date).toBeAfter(date);
toBeBefore	expect(date).toBeBefore(date);
toBeDate	expect(date).toBeDate();
toBeValidDate	expect(date).toBeValidDate()

Functions and Errors

Matcher	Example
toBeFunction	expect(fn).toBeFunction();
toThrowAnyError	expect(fn).toThrowAnyError();
toThrowErrorOfType	expect(fn).toThrowErrorOfType(constructorName);

Numbers

Matcher	Example
toBeCalculable	expect(mixed).toBeCalculable();
toBeEvenNumber	expect(number).toBeEvenNumber();
toBeGreaterThanOrEqualTo	expect(number).toBeGreaterThanOrEqualTo(number);
toBeLessThanOrEqualTo	expect(number).toBeLessThanOrEqualTo(number);
toBeNear	expect(number).toBeNear(value, epsilon)
toBeNumber	expect(number).toBeNumber();
toBeOddNumber	expect(number).toBeOddNumber();
toBeWholeNumber	expect(number).toBeWholeNumber();
toBeWithinRange	expect(number).toBeWithinRange(floor, ceiling);

Strings

Matcher	Example
toBeEmptyString	expect(string).toBeEmptyString();
toBeHtmlString	expect(string).toBeHtmlString();
toBeIso8601	expect(string).toBeIso8601();
toBeJsonString	expect(string).toBeJsonString();
toBeLongerThan	expect(string).toBeLongerThan();
toBeNonEmptyString	expect(string).toBeNonEmptyString();
toBeSameLengthAs	expect(string).toBeSameLengthAs();
toBeShorterThan	expect(string).toBeShorterThan();
toBeString	expect(string).toBeString();
toBeWhitespace	expect(string).toBeWhitespace();
toEndWith	expect(string).toEndWith(string);
toStartWith	expect(string).toStartWith(string);

Objects

Matcher	Example
toBeEmptyObject	expect(object).toBeEmptyObject();
toBeNonEmptyObject	expect(object).toBeNonEmptyObject();
toBeObject	expect(object).toBeObject();

Regular Expressions

Matcher	Example
toBeRegExp	expect(regexp).toBeRegExp();

Members, Properties, Methods

Matcher	Example
toHaveArray	expect(object).toHaveArray(memberName);
toHaveArrayOfBooleans	expect(object).toHaveArrayOfBooleans(memberName);
toHaveArrayOfNumbers	expect(object).toHaveArrayOfNumbers(memberName);
toHaveArrayOfObjects	expect(object).toHaveArrayOfObjects(memberName);
toHaveArrayOfSize	expect(object).toHaveArrayOfSize(memberName, size);
toHaveArrayOfStrings	expect(object).toHaveArrayOfStrings(memberName);
toHaveBoolean	expect(object).toHaveBoolean(memberName);
toHaveCalculable	expect(object).toHaveCalculable(memberName);
toHaveDate	expect(object).toHaveDate(memberName);
toHaveDateAfter	expect(object).toHaveDateAfter(memberName, date);
toHaveDateBefore	expect(object).toHaveDateBefore(memberName, date);
toHaveEmptyArray	expect(object).toHaveEmptyArray(memberName);
toHaveEmptyObject	expect(object).toHaveEmptyObject(memberName);
toHaveEmptyString	expect(object).toHaveEmptyString(memberName);
toHaveEvenNumber	expect(object).toHaveEvenNumber(memberName);
toHaveFalse	expect(object).toHaveFalse(memberName);
toHaveHtmlString	expect(object).toHaveHtmlString(memberName);
toHaveIso8601	expect(object).toHaveIso8601(memberName);
toHaveJsonString	expect(object).toHaveJsonString(memberName);
toHaveMember	expect(object).toHaveMember(memberName);
toHaveMethod	expect(object).toHaveMethod(memberName);
toHaveNonEmptyArray	expect(object).toHaveNonEmptyArray(memberName);
toHaveNonEmptyObject	expect(object).toHaveNonEmptyObject(memberName);
toHaveNonEmptyString	expect(object).toHaveNonEmptyString(memberName);
toHaveNumber	expect(object).toHaveNumber(memberName);
toHaveNumberWithinRange	expect(object).toHaveNumberWithinRange(memberName, floor, ceiling);
toHaveObject	expect(object).toHaveObject(memberName);
toHaveOddNumber	expect(object).toHaveOddNumber(memberName);
toHaveString	expect(object).toHaveString(memberName);
toHaveStringLongerThan	expect(object).toHaveStringLongerThan(memberName, string);
toHaveStringSameLengthAs	expect(object).toHaveStringSameLengthAs(memberName, string);
toHaveStringShorterThan	expect(object).toHaveStringShorterThan(memberName, string);
toHaveTrue	expect(object).toHaveTrue(memberName);
toHaveWhitespaceString	expect(object).toHaveWhitespaceString(memberName);
toHaveWholeNumber	expect(object).toHaveWholeNumber(memberName);

Asymmetric Matchers

Jasmine's Default Asymmetric Matchers

The Jasmine testing framework from Pivotal Labs comes with this default set of asymmetric matchers;

jasmine.any(Constructor);
jasmine.anything(mixed);
jasmine.arrayContaining(mixed);
jasmine.objectContaining(mixed);
jasmine.stringMatching(pattern);

Arrays

Matcher	Example
any.arrayOfBooleans	expect(spy).toHaveBeenCalledWith(any.arrayOfBooleans());
any.arrayOfNumbers	expect(spy).toHaveBeenCalledWith(any.arrayOfNumbers());
any.arrayOfObjects	expect(spy).toHaveBeenCalledWith(any.arrayOfObjects());
any.arrayOfSize	expect(spy).toHaveBeenCalledWith(any.arrayOfSize(number));
any.arrayOfStrings	expect(spy).toHaveBeenCalledWith(any.arrayOfStrings());
any.emptyArray	expect(spy).toHaveBeenCalledWith(any.emptyArray());
any.nonEmptyArray	expect(spy).toHaveBeenCalledWith(any.nonEmptyArray());

Dates

Matcher	Example
any.after	expect(spy).toHaveBeenCalledWith(any.after(date));
any.before	expect(spy).toHaveBeenCalledWith(any.before(date));

Numbers

Matcher	Example
any.calculable	expect(spy).toHaveBeenCalledWith(any.calculable());
any.evenNumber	expect(spy).toHaveBeenCalledWith(any.evenNumber());
any.greaterThanOrEqualTo	expect(spy).toHaveBeenCalledWith(any.greaterThanOrEqualTo(number));
any.lessThanOrEqualTo	expect(spy).toHaveBeenCalledWith(any.lessThanOrEqualTo(number));
any.oddNumber	expect(spy).toHaveBeenCalledWith(any.oddNumber());
any.wholeNumber	expect(spy).toHaveBeenCalledWith(any.wholeNumber());
any.withinRange	expect(spy).toHaveBeenCalledWith(any.withinRange(floor, ceiling));

Strings

Matcher	Example
any.endingWith	expect(spy).toHaveBeenCalledWith(any.endingWith(string));
any.iso8601	expect(spy).toHaveBeenCalledWith(any.iso8601());
any.jsonString	expect(spy).toHaveBeenCalledWith(any.jsonString());
any.longerThan	expect(spy).toHaveBeenCalledWith(any.longerThan(string));
any.nonEmptyString	expect(spy).toHaveBeenCalledWith(any.nonEmptyString());
any.sameLengthAs	expect(spy).toHaveBeenCalledWith(any.sameLengthAs(string));
any.shorterThan	expect(spy).toHaveBeenCalledWith(any.shorterThan(string));
any.startingWith	expect(spy).toHaveBeenCalledWith(any.startingWith(string));
any.whitespace	expect(spy).toHaveBeenCalledWith(any.whitespace());

Objects

Matcher	Example
any.emptyObject	expect(spy).toHaveBeenCalledWith(any.emptyObject());
any.nonEmptyObject	expect(spy).toHaveBeenCalledWith(any.nonEmptyObject());

Regular Expressions

Matcher	Example
any.regExp	expect(spy).toHaveBeenCalledWith(any.regExp());

Integration

Browser

Embed jasmine-matchers.js after Jasmine but before your tests.

Jest

Include the following in your package.json;

"unmockedModulePathPatterns": ["jasmine-expect"]

And the following at the top of your test suite;

import JasmineExpect from 'jasmine-expect';

Karma

Integration is easy with the karma-jasmine-matchers plugin.

Node.js

Use the Jasmine CLI and include the path to where Jasmine Matchers is installed in the helpers array of your spec/support/jasmine.json.

{
  "spec_dir": "spec",
  "spec_files": ["../src/**/*.spec.js"],
  "helpers": ["../node_modules/jasmine-expect/index.js"],
  "stopSpecOnExpectationFailure": false,
  "random": false
}

Sublime Text

Jasmine-Matchers-Snippets or Jasmine-Matchers-ES6-Snippets can be installed with Package Control to ease development with Jasmine Matchers in Sublime Text.

Tern

There is a Plugin for Tern to auto-complete matchers in your Text Editor.

Browser Support

Jasmine-Matchers is tested on Travis CI and BrowserStack against the following environments.

Browser	Version Range
Android	4.0 - 5.1
Chrome	26 - 52
Firefox	4 - 48
Internet Explorer	9 - Edge
iOS	6.0 - 9.3*
Opera	11 - 12
Safari	6 - 9*

* Safari 5.1 and iOS 5.1 are actually fully supported except for toBeIso8601.

Changelog

3.5.0 (2017-01-18)

Features

• dates: add toBeValidDate matcher (47691cf), closes #49
• jest: add compatibility with jest (0654bcc)
• numbers: add toBeNear matcher (ffac1f5), closes #58