README.md
# Jasmine-Matchers
> Write Beautiful Specs with Custom Matchers
[](https://www.npmjs.com/package/jasmine-expect) [](https://www.npmjs.com/package/jasmine-expect) [](https://travis-ci.org/JamieMason/Jasmine-Matchers) [](https://codeclimate.com/github/JamieMason/Jasmine-Matchers/maintainability)
## Table of Contents
- [Overview](#overview)
- [🌩 Installation](#-installation)
- [📝 API](#-api)
- [🕹 Usage](#-usage)
- [🌍 Browser Support](#-browser-support)
- [🙋🏽♂️ Getting Help](#♂️-getting-help)
- [👀 Other Projects](#-other-projects)
- [🤓 Author](#-author)
## Overview
##### What
A huge library of test matchers for a range of common use-cases, compatible with all versions of [Jasmine](http://jasmine.github.io/) and [Jest](http://facebook.github.io/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()`.
##### Sponsors
<a href="https://browserstack.com">
<img alt="Sponsored by BrowserStack" src="https://cdn.rawgit.com/JamieMason/Jasmine-Matchers/ad1ea0e6/browserstack.svg" height="40" />
</a>
## 🌩 Installation
##### npm
npm install jasmine-expect --save-dev
##### Bower
bower install jasmine-expect --save-dev
##### Manual
Downloads are available on the [releases](https://github.com/JamieMason/Jasmine-Matchers/releases) page.
## 📝 API
The [Jasmine testing framework](http://jasmine.github.io/) from [Pivotal Labs](http://pivotallabs.com/) comes with this [default set of matchers](http://jasmine.github.io/edge/introduction.html#section-Expectations):
```js
expect().nothing()
expect().toBe(expected)
expect().toBeCloseTo(expected, precisionopt)
expect().toBeDefined()
expect().toBeFalse()
expect().toBeFalsy()
expect().toBeGreaterThan(expected)
expect().toBeGreaterThanOrEqual(expected)
expect().toBeInstanceOf(expected)
expect().toBeLessThan(expected)
expect().toBeLessThanOrEqual(expected)
expect().toBeNaN()
expect().toBeNegativeInfinity()
expect().toBeNull()
expect().toBePositiveInfinity()
expect().toBeTrue()
expect().toBeTruthy()
expect().toBeUndefined()
expect().toContain(expected)
expect().toEqual(expected)
expect().toHaveBeenCalled()
expect().toHaveBeenCalledBefore(expected)
expect().toHaveBeenCalledOnceWith()
expect().toHaveBeenCalledTimes(expected)
expect().toHaveBeenCalledWith()
expect().toHaveClass(expected)
expect().toHaveSize(expected)
expect().toMatch(expected)
expect().toThrow(expectedopt)
expect().toThrowError(expectedopt, messageopt)
expect().toThrowMatching(predicate)
expect().withContext(message)
```
and this [default set of asymmetric matchers](http://jasmine.github.io/2.4/introduction.html#section-Matching_Anything_with_%3Ccode%3Ejasmine.any%3C/code%3E);
```js
jasmine.any(Constructor);
jasmine.anything(mixed);
jasmine.arrayContaining(mixed);
jasmine.objectContaining(mixed);
jasmine.stringMatching(pattern);
```
### Matchers
[Jasmine-Matchers](https://github.com/JamieMason/Jasmine-Matchers) adds the following matchers:
```js
expect(array).toBeArray();
expect(array).toBeArrayOfBooleans();
expect(array).toBeArrayOfNumbers();
expect(array).toBeArrayOfObjects();
expect(array).toBeArrayOfSize(number);
expect(array).toBeArrayOfStrings();
expect(array).toBeEmptyArray();
expect(array).toBeNonEmptyArray();
expect(boolean).toBeBoolean();
expect(date).toBeAfter(otherDate);
expect(date).toBeBefore(otherDate);
expect(date).toBeDate();
expect(date).toBeValidDate();
expect(fn).toBeFunction();
expect(fn).toThrowAnyError();
expect(fn).toThrowErrorOfType(constructorName);
expect(mixed).toBeCalculable();
expect(number).toBeEvenNumber();
expect(number).toBeGreaterThanOrEqualTo(otherNumber);
expect(number).toBeLessThanOrEqualTo(otherNumber);
expect(number).toBeNear(otherNumber, epsilon);
expect(number).toBeNumber();
expect(number).toBeOddNumber();
expect(number).toBeWholeNumber();
expect(number).toBeWithinRange(floor, ceiling);
expect(object).toBeEmptyObject();
expect(object).toBeNonEmptyObject();
expect(object).toBeObject();
expect(object).toHaveArray(memberName);
expect(object).toHaveArrayOfBooleans(memberName);
expect(object).toHaveArrayOfNumbers(memberName);
expect(object).toHaveArrayOfObjects(memberName);
expect(object).toHaveArrayOfSize(memberName, size);
expect(object).toHaveArrayOfStrings(memberName);
expect(object).toHaveBoolean(memberName);
expect(object).toHaveCalculable(memberName);
expect(object).toHaveDate(memberName);
expect(object).toHaveDateAfter(memberName, date);
expect(object).toHaveDateBefore(memberName, date);
expect(object).toHaveEmptyArray(memberName);
expect(object).toHaveEmptyObject(memberName);
expect(object).toHaveEmptyString(memberName);
expect(object).toHaveEvenNumber(memberName);
expect(object).toHaveFalse(memberName);
expect(object).toHaveHtmlString(memberName);
expect(object).toHaveIso8601(memberName);
expect(object).toHaveJsonString(memberName);
expect(object).toHaveMember(memberName);
expect(object).toHaveMethod(memberName);
expect(object).toHaveNonEmptyArray(memberName);
expect(object).toHaveNonEmptyObject(memberName);
expect(object).toHaveNonEmptyString(memberName);
expect(object).toHaveNumber(memberName);
expect(object).toHaveNumberWithinRange(memberName, floor, ceiling);
expect(object).toHaveObject(memberName);
expect(object).toHaveOddNumber(memberName);
expect(object).toHaveString(memberName);
expect(object).toHaveStringLongerThan(memberName, string);
expect(object).toHaveStringSameLengthAs(memberName, string);
expect(object).toHaveStringShorterThan(memberName, string);
expect(object).toHaveTrue(memberName);
expect(object).toHaveUndefined(memberName);
expect(object).toHaveWhitespaceString(memberName);
expect(object).toHaveWholeNumber(memberName);
expect(regexp).toBeRegExp();
expect(string).toBeEmptyString();
expect(string).toBeHtmlString();
expect(string).toBeIso8601();
expect(string).toBeJsonString();
expect(string).toBeLongerThan(otherString);
expect(string).toBeNonEmptyString();
expect(string).toBeSameLengthAs(otherString);
expect(string).toBeShorterThan(otherString);
expect(string).toBeString();
expect(string).toBeWhitespace();
expect(string).toEndWith(substring);
expect(string).toStartWith(substring);
```
### Asymmetric Matchers
```js
any.after(date);
any.arrayOfBooleans();
any.arrayOfNumbers();
any.arrayOfObjects();
any.arrayOfSize(number);
any.arrayOfStrings();
any.before(date);
any.calculable();
any.emptyArray();
any.emptyObject();
any.endingWith(string);
any.evenNumber();
any.greaterThanOrEqualTo(number);
any.iso8601();
any.jsonString();
any.lessThanOrEqualTo(number);
any.longerThan(string);
any.nonEmptyArray();
any.nonEmptyObject();
any.nonEmptyString();
any.oddNumber();
any.regExp();
any.sameLengthAs(string);
any.shorterThan(string);
any.startingWith(string);
any.whitespace();
any.wholeNumber();
any.withinRange(floor, ceiling);
```
## 🕹 Usage
### Browser
Embed [jasmine-matchers.js](https://github.com/JamieMason/Jasmine-Matchers/blob/master/dist/jasmine-matchers.js) after Jasmine but before your tests.
### Jest
Include the following in your `package.json`:
```json
"unmockedModulePathPatterns": ["jasmine-expect"]
```
And the following at the top of your test suite:
```js
import JasmineExpect from "jasmine-expect";
```
### Karma
Integration is easy with the [karma-jasmine-matchers](https://github.com/JamieMason/karma-jasmine-matchers) plugin.
### Node.js
Use the [Jasmine CLI](https://www.npmjs.com/package/jasmine) and include the path to where Jasmine Matchers is installed in the `helpers` array of your `spec/support/jasmine.json`.
```json
{
"spec_dir": "spec",
"spec_files": ["../src/**/*.spec.js"],
"helpers": ["../node_modules/jasmine-expect/index.js"],
"stopSpecOnExpectationFailure": false,
"random": false
}
```
### TypeScript and Angular CLI Projects
If you are using TypeScript, you might want to `npm install @types/jasmine-expect --save-dev` in order to prevent your IDE from complaining about the new Matchers.
Also, if you run into TypeScript compilation errors when running your tests, add `"jasmine-expect"` to the `"types"` array in your tests' `tsconfig` file.
As an example, for an Angular CLI based project, this would be your `tsconfig.spec.json` file:
```json
{
"extends": "../tsconfig.json",
"compilerOptions": {
"outDir": "../out-tsc/spec",
"baseUrl": "./",
"module": "commonjs",
"target": "es5",
"types": ["jasmine", "node", "jasmine-expect"]
},
"files": ["test.ts"],
"include": ["**/*.spec.ts", "**/*.d.ts"]
}
```
### Sublime Text
[Jasmine-Matchers-Snippets](https://github.com/JamieMason/Jasmine-Matchers-Snippets) or [Jasmine-Matchers-ES6-Snippets](https://github.com/JamieMason/Jasmine-Matchers-ES6-Snippets) can be installed with [Package Control](https://packagecontrol.io/packages/Jasmine%20Matchers%20Snippets) to ease development with Jasmine Matchers in Sublime Text.
### Tern
There is a [Plugin](https://github.com/ik9999/tern-jasminematchers) for [Tern](https://github.com/ternjs/tern) to auto-complete matchers in your Text Editor.
## 🌍 Browser Support
Jasmine-Matchers is tested on [Travis CI](https://travis-ci.org/JamieMason/Jasmine-Matchers) and [BrowserStack](https://browserstack.com) against the following environments.
| Browser | Version Range |
| :---------------- | ------------: |
| Android | 9 - 11 |
| Chrome | 80 - 85 |
| Edge | 80 - 85 |
| Firefox | 76 - 80 |
| iOS | 10 - 14 |
| Safari | 10 - 13 |
## 🙋🏽♂️ Getting Help
Get help with issues by creating a [Bug Report] or discuss ideas by opening a [Feature Request].
[bug report]: https://github.com/JamieMason/Jasmine-Matchers/issues/new?template=bug_report.md
[feature request]: https://github.com/JamieMason/Jasmine-Matchers/issues/new?template=feature_request.md
## 👀 Other Projects
If you find my Open Source projects useful, please share them ❤️
- [**eslint-formatter-git-log**](https://github.com/JamieMason/eslint-formatter-git-log)<br>ESLint Formatter featuring Git Author, Date, and Hash
- [**eslint-plugin-move-files**](https://github.com/JamieMason/eslint-plugin-move-files)<br>Move and rename files while keeping imports up to date
- [**eslint-plugin-prefer-arrow-functions**](https://github.com/JamieMason/eslint-plugin-prefer-arrow-functions)<br>Convert functions to arrow functions
- [**ImageOptim-CLI**](https://github.com/JamieMason/ImageOptim-CLI)<br>Automates ImageOptim, ImageAlpha, and JPEGmini for Mac to make batch optimisation of images part of your automated build process.
- [**karma-benchmark**](https://github.com/JamieMason/karma-benchmark)<br>Run Benchmark.js over multiple Browsers, with CI compatible output
- [**self-help**](https://github.com/JamieMason/self-help#readme)<br>Interactive Q&A Guides for Web and the Command Line
- [**syncpack**](https://github.com/JamieMason/syncpack#readme)<br>Manage multiple package.json files, such as in Lerna Monorepos and Yarn Workspaces
## 🤓 Author
<img src="https://www.gravatar.com/avatar/acdf106ce071806278438d8c354adec8?s=100" align="left">
I'm [Jamie Mason] from [Leeds] in England, I began Web Design and Development in 1999 and have been Contracting and offering Consultancy as Fold Left Ltd since 2012. Who I've worked with includes [Sky Sports], [Sky Bet], [Sky Poker], The [Premier League], [William Hill], [Shell], [Betfair], and Football Clubs including [Leeds United], [Spurs], [West Ham], [Arsenal], and more.
<div align="center">
[![Follow JamieMason on GitHub][github badge]][github] [![Follow fold_left on Twitter][twitter badge]][twitter]
</div>
<!-- images -->
[github badge]: https://img.shields.io/github/followers/JamieMason.svg?style=social&label=Follow
[twitter badge]: https://img.shields.io/twitter/follow/fold_left.svg?style=social&label=Follow
<!-- links -->
[arsenal]: https://www.arsenal.com
[betfair]: https://www.betfair.com
[github]: https://github.com/JamieMason
[jamie mason]: https://www.linkedin.com/in/jamiemasonleeds
[leeds united]: https://www.leedsunited.com/
[leeds]: https://www.instagram.com/visitleeds
[premier league]: https://www.premierleague.com
[shell]: https://www.shell.com
[sky bet]: https://www.skybet.com
[sky poker]: https://www.skypoker.com
[sky sports]: https://www.skysports.com
[spurs]: https://www.tottenhamhotspur.com
[twitter]: https://twitter.com/fold_left
[west ham]: https://www.whufc.com
[william hill]: https://www.williamhill.com