custom_matcher.js

Often a project will want to encapsulate custom matching code for use across multiple specs. Here is how to create a Jasmine-compatible custom matcher.

A custom matcher at its root is a comparison function that takes an actual value and expected value. This factory is passed to Jasmine, ideally in a call to beforeEach and will be in scope and available for all of the specs inside a given call to describe. Custom matchers are torn down between specs. The name of the factory will be the name of the matcher exposed on the return value of the call to expect.

Matcher Factories

Custom matcher factories are passed two parameters: util, which has a set of utility functions for matchers to use (see: matchersUtil.js for the current list) and customEqualityTesters which needs to be passed in if util.equals is ever called. These parameters are available for use when the matcher is called.

Result

The compare function must return a result object with a pass property that is a boolean result of the matcher. The pass property tells the expectation whether the matcher was successful (true) or unsuccessful (false). If the expectation is called/chained with .not, the expectation will negate this to determine whether the expectation is met.

Custom negative comparators

If you need more control over the negative comparison (the not case) than the simple boolean inversion above, you can also have your matcher factory include another key, negativeCompare alongside compare, for which the value is a function to invoke when .not is used. This function/key is optional.

Once a custom matcher is registered with Jasmine, it is available on any expectation.

it("is available on an expectation",function(){expect({hyuk:'gawrsh'}).toBeGoofy();});it("can take an 'expected' parameter",function(){expect({hyuk:'gawrsh is fun'}).toBeGoofy(' is fun');});it("can be negated",function(){expect({hyuk:'this is fun'}).not.toBeGoofy();});});