JavaScript
Latest commit ad935bc Mar 10, 2017 @JamieMason chore(release): 3.7.0

README.md

Jasmine-Matchers

NPM version NPM downloads Build Status Dependency Status Join the chat at https://gitter.im/JamieMason/Jasmine-Matchers Code Climate Analytics

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

Sponsored by BrowserStack

Contents

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);
toHaveUndefined expect(object).toHaveUndefined(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.