Must.js API Documentation

Must.js is included in Unit.JS, you can use Must.js with Unit.js:

var test = require('unit.js');

// test 'string' type
test.must('foobar').be.a.string();

// then that actual value '==' expected value
test.must('foobar' == 'foobar').be.true();

// then that actual value '===' expected value
test.must('foobar').be.equal('foobar');

// Must.js library (alternative style)
var must = test.must;

// test 'string' type
('foobar').must.be.a.string();

// then that actual value '==' expected value
('foobar' == 'foobar').must.be.true();

// then that actual value '===' expected value
('foobar').must.be.equal('foobar');

// this shortcut works also like this

// test 'string' type
must('foobar').be.a.string();

// then that actual value '==' expected value
must('foobar' == 'foobar').be.true();

// then that actual value '===' expected value
must('foobar').be.equal('foobar');

Must.js adds a non enumerable property in Object.prototype.must to be able to make assertions like myVar.must.be.string();.

This does not affect the signature of objects because the property is invisible (not enumerable).
If necessary you can cancel it:

delete Object.prototype.must;

Subsequently Must.js can be used in this way:

test.must(myVar).be.string();

Should.js done the same, so to remove the 2 monkey patches:

var test = require('unit.js');

delete Object.prototype.must;
delete Object.prototype.should;

This documentation below is written by Andri Möll (Must.js author).

Must

Must.js API Documentation

Object

AssertionError

Must(actual, [message])

The main class that wraps the asserted object and that you call matchers on.

To include a custom error message for failure cases, pass a string as the second argument.

Most of the time you'll be using Object.prototype.must to create this wrapper, but occasionally you might want to assert nulls or undefineds and in those cases assigning Must to something like expect or demand works nicely.

Examples:

true.must.be.true()
[].must.be.empty()

var expect = require("must")
expect(null).to.be.null()

var demand = require("must")
demand(undefined, "The undefined undefineds").be.undefined()

Must.prototype.a(class)

Alias of instanceof. Can also be used a pass-through property for a fluent chain.

Examples:

"Hello".must.be.a.string()
new Date().must.be.a(Date)

Must.prototype.above(expected)

Assert that an object is above and greater than (>) expected. Uses > for comparison, so it'll also work with value objects (those implementing valueOf) like Date.

Examples:

(69).must.be.above(42)

Must.prototype.after(expected)

Alias of above. Works well with dates where saying after is more natural than above or greater than.

To assert that a date is equivalent to another date, use eql. For regular numbers, equal is fine.

Examples:

(1337).must.be.after(42)
new Date(2030, 5, 18).must.be.after(new Date(2013, 9, 23))

Must.prototype.an(class)

Alias of instanceof. Can also be used a pass-through property for a fluent chain.

Examples:

[1, 2].must.be.an.array()
new AwesomeClass().must.be.an(AwesomeClass)

Must.prototype.array()

Assert object is an array.

Examples:

[42, 69].must.be.an.array()

Must.prototype.at

Pass-through property for a fluent chain.

Examples:

(42).must.be.at.most(69)
(1337).must.be.at.least(1337)

Must.prototype.be(expected)

Alias of equal. Can also be used as a pass-through property for a fluent chain.

Examples:

true.must.be.true()
(42).must.be(42)

Must.prototype.before(expected)

Alias of below. Works well with dates where saying before is more natural than below or less than.

To assert that a date is equivalent to another date, use eql. For regular numbers, equal is fine.

Examples:

(42).must.be.before(1337)
new Date(2000, 5, 18).must.be.before(new Date(2001, 0, 1))

Must.prototype.below(expected)

Assert that an object is below and less than (<) expected. Uses < for comparison, so it'll also work with value objects (those implementing valueOf) like Date.

Examples:

(42).must.be.below(69)

Must.prototype.between(begin, end)

Assert that an object is between begin and end (inclusive). Uses < for comparison, so it'll also work with value objects (those implementing valueOf) like Date.

Examples:

(13).must.be.between(13, 69)
(42).must.be.between(13, 69)
(69).must.be.between(13, 69)

Must.prototype.boolean()

Assert object is a boolean (true or false). Boxed boolean objects (new Boolean) are not considered booleans.

Examples:

true.must.be.a.boolean()

Must.prototype.contain(expected)

Alias of include.

Must.prototype.date()

Assert object is a date.

Examples:

new Date().must.be.a.date()

Must.prototype.empty()

Assert that an object is empty. Checks either the length for arrays and strings or the count of enumerable keys. Inherited keys also counted.

Examples:

"".must.be.empty()
[].must.be.empty()
({}).must.be.empty()

Must.prototype.endWith(expected)

Assert a string ends with the given string.

Examples:

"Hello, John".must.endWith("John")

Must.prototype.enumerable(property)

Assert that an object has an enumerable property property. It will fail if the object lacks the property entirely.

This also checks inherited properties in the prototype chain, something which Object.prototype.propertyIsEnumerable itself does not do.

For checking if a property exists and is non-enumerable, see nonenumerable.

Examples:

({life: 42, love: 69}).must.have.enumerable("love")

Must.prototype.enumerableProperty(property)

Alias of enumerable.

Must.prototype.eql(expected)

Assert object equality by content and if possible, recursively. Also handles circular and self-referential objects.

For most parts it asserts strict equality (===), but:

  • RegExp objects are compared by their pattern and flags.
  • Date objects are compared by their value.
  • Array objects are compared recursively.
  • NaNs are considered equivalent.
  • Instances of the same class with a valueOf function are compared by its output.
  • Plain objects and instances of the same class are compared recursively.

Does not coerce types so mismatching types fail. Inherited enumerable properties are also taken into account.

Instances are objects whose prototype's constructor property is set. E.g. new MyClass. Others, like {} or Object.create({}), are plain objects.

Examples:

/[a-z]/.must.eql(/[a-z]/)
new Date(1987, 5, 18).must.eql(new Date(1987, 5, 18))
["Lisp", 42].must.eql(["Lisp", 42])
({life: 42, love: 69}).must.eql({life: 42, love: 69})
NaN.must.eql(NaN)

function Answer(answer) { this.answer = answer }
new Answer(42).must.eql(new Answer(42))

Must.prototype.equal(expected)

Assert object strict equality or identity (===).

To compare value objects (like Date or RegExp) by their value rather than identity, use eql. To compare arrays and objects by content, also use eql.

Examples:

(42).must.equal(42)

var date = new Date
date.must.equal(date)

Must.prototype.error([constructor], [expected])

Assert that an object is an error (instance of Error by default). Optionally assert it matches expected (and/or is of instance constructor). When you have a function that's supposed to throw, use throw.

Given expected, the error is asserted as follows:

  • A string is compared with the exception's message property.
  • A regular expression is matched against the exception's message property.
  • A function (a.k.a. constructor) is used to check if the error is an instanceof that constructor.
  • All other cases of expected are left unspecified for now.

Examples:

var err = throw new RangeError("Everything's amazing and nobody's happy") }
err.must.be.an.error()
err.must.be.an.error("Everything's amazing and nobody's happy")
err.must.be.an.error(/amazing/)
err.must.be.an.error(Error)
err.must.be.an.error(RangeError)
err.must.be.an.error(RangeError, "Everything's amazing and nobody's happy")
err.must.be.an.error(RangeError, /amazing/)

Must.prototype.eventually

Alias of resolve.

Examples:

Promise.resolve(42).must.eventually.equal(42)

Must.prototype.exist()

Assert object is exists and thereby is not null or undefined.

Examples:

0..must.exist()
"".must.exist()
({}).must.exist()

Must.prototype.false()

Assert object is false. A boxed boolean object (new Boolean(false) is not considered false.

Examples:

false.must.be.false()

Must.prototype.falsy()

Assert object is falsy (!obj).

Only null, undefined, 0, false and "" are falsy in JavaScript. Everything else is truthy.

Examples:

0..must.be.falsy()
"".must.be.falsy()

Must.prototype.frozen()

Assert that an object is frozen with Object.isFrozen.

Examples:

Object.freeze({}).must.be.frozen()

Must.prototype.function()

Assert object is a function.

Examples:

(function() {}).must.be.a.function()

Must.prototype.gt(expected)

Alias of above.

Must.prototype.gte(expected)

Alias of least.

Must.prototype.have

Pass-through property for a fluent chain.

Examples:

[1, 2].must.have.length(2)

Must.prototype.include(expected)

Assert object includes expected.

For strings it checks the text, for arrays it checks elements and for objects the property values. Everything is checked with strict equals (===).

Examples:

"Hello, John!".must.include("John")
[1, 42, 3].must.include(42)
({life: 42, love: 69}).must.include(42)

Must.prototype.instanceOf(class)

Alias of instanceof.

Must.prototype.instanceof(class)

Assert that an object is an instance of something. Uses obj instanceof expected.

Examples:

new Date().must.be.an.instanceof(Date)

Must.prototype.is(expected)

Alias of equal. Can also be used as a pass-through property for a fluent chain.

Examples:

var claim = require("must")
claim(true).is.true()
claim(42).is(42)

Must.prototype.keys(keys)

Assert that an object has only the expected enumerable keys. Pass an array of strings as keys.

Takes inherited properties into account. To not do so, see ownKeys.

Examples:

({life: 42, love: 69}).must.have.keys(["life", "love"])
Object.create({life: 42}).must.have.keys(["life"])

Must.prototype.least(expected)

Assert that an object is at least, greater than or equal to (>=), expected. Uses >= for comparison, so it'll also work with value objects (those implementing valueOf) like Date.

Examples:

(69).must.be.at.least(42)
(42).must.be.at.least(42)

Must.prototype.length(expected)

Assert that an object has a length property equal to expected.

Examples:

"Something or other".must.have.length(18)
[1, 2, 3, "Four o'clock rock"].must.have.length(4)

Must.prototype.lt(expected)

Alias of below.

Must.prototype.lte(expected)

Alias of most.

Must.prototype.match(regexp)

Assert object matches the given regular expression.

If you pass in a non regular expression object, it'll be converted to one via new RegExp(regexp).

Examples:

"Hello, John!".must.match(/john/i)
"Wei wu wei".must.match("wu")

Must.prototype.most(expected)

Assert that an object is at most, less than or equal to (<=), expected. Uses <= for comparison, so it'll also work with value objects (those implementing valueOf) like Date.

Examples:

(42).must.be.at.most(69)
(42).must.be.at.most(42)

Must.prototype.must

Pass-through property for a fluent chain.

Examples:

(42).must.must.must.must.equal(42)

Must.prototype.nan()

Assert object is NaN.

Examples:

NaN.must.be.nan()

Must.prototype.nonenumerable(property)

Assert that an object has a non-enumerable property property. It will fail if the object lacks the property entirely.

This also checks inherited properties in the prototype chain, something which Object.prototype.propertyIsEnumerable itself does not do.

It's the inverse of enumerable.

Examples:

(function() {}).must.have.nonenumerable("call")
Object.create({}, {love: {enumerable: 0}}).must.have.nonenumerable("love")

Must.prototype.nonenumerableProperty(property)

Alias of nonenumerable.

Must.prototype.not

Inverse the assertion. Use it multiple times to create lots of fun! true.must.not.not.be.true() :-)

Examples:

true.must.not.be.true()
[].must.not.be.empty()

Must.prototype.null()

Assert object is null.

Because JavaScript does not allow method calls on null, you'll have to wrap an expected null with Must. Assigning require("must") to expect or demand works well.

If you want to assert that an object's property is null, see property.

Examples:

var demand = require("must")
demand(null).be.null()

Must.prototype.number()

Assert object is a number. Boxed number objects (new Number) are not considered numbers.

Examples:

(42).must.be.a.number()

Must.prototype.object()

Assert object is an.. object.

Examples:

({}).must.be.an.object()

Must.prototype.own(property, [value])

Alias of ownProperty.

Must.prototype.ownKeys(keys)

Assert that an object has only the expected enumerable keys of its own. Pass an array of strings as keys.

Does not take inherited properties into account. To do so, see keys.

Examples:

({life: 42, love: 69}).must.have.ownKeys(["life", "love"])

Must.prototype.ownProperties(properties)

Assert that an object has all of the properties given in properties with equal (===) values and that they're own properties. In other words, asserts that the given object is a subset of the one asserted against.

Does not take inherited properties into account. To do so, see properties.

Examples:

var john = {name: "John", age: 42, sex: "male"}
john.must.have.ownProperties({name: "John", sex: "male"})

Must.prototype.ownProperty(property, [value])

Assert that an object has own property property. Optionally assert it equals (===) to value.

Does not take inherited properties into account. To do so, see property.

Examples:

({life: 42, love: 69}).must.have.ownProperty("love", 69)

Must.prototype.permutationOf(expected)

Assert that an array is a permutation of the given array.

An array is a permutation of another if they both have the same elements (including the same number of duplicates) regardless of their order. Elements are checked with strict equals (===).

Examples:

[1, 1, 2, 3].must.be.a.permutationOf([3, 2, 1, 1])
[7, 8, 8, 9].must.not.be.a.permutationOf([9, 8, 7])

Must.prototype.properties(properties)

Assert that an object has all of the properties given in properties with equal (===) values. In other words, asserts that the given object is a subset of the one asserted against.

Takes inherited properties into account. To not do so, see ownProperties.

Examples:

var john = {name: "John", age: 42, sex: "male"}
john.must.have.properties({name: "John", sex: "male"})

Must.prototype.property(property, [value])

Assert that an object has property property. Optionally assert it equals (===) to value.

Takes inherited properties into account. To not do so, see ownProperty.

Examples:

(function() {}).must.have.property("call")
({life: 42, love: 69}).must.have.property("love", 69)

Must.prototype.regexp()

Assert object is a regular expression.

Examples:

/[a-z]/.must.be.a.regexp()

Must.prototype.reject

Makes any matcher following the use of reject wait till a promise is rejected before asserting. Returns a new promise that will either resolve if the assertion passed or fail with AssertionError.

Promises are transparent to matchers, so everything will also work with customer matchers you've added to Must.prototype. Internally Must just waits on the promise and calls the matcher function once it's rejected.

With Mocha, using this will look something like:

it("must pass", function() {
  return Promise.reject(42).must.reject.to.equal(42)
})

Using CoMocha, it'll look like:

it("must pass", function*() {
  yield Promise.reject(42).must.reject.to.equal(42)
  yield Promise.reject([1, 2, 3]).must.reject.to.not.include(42)
})

Examples:

Promise.reject(42).must.reject.to.equal(42)
Promise.reject([1, 2, 3]).must.reject.to.not.include(42)

Must.prototype.resolve

Makes any matcher following the use of resolve wait till a promise resolves before asserting. Returns a new promise that will either resolve if the assertion passed or fail with AssertionError.

Promises are transparent to matchers, so everything will also work with customer matchers you've added to Must.prototype. Internally Must just waits on the promise and calls the matcher function once it's resolved.

With Mocha, using this will look something like:

it("must pass", function() {
  return Promise.resolve(42).must.resolve.to.equal(42)
})

Using CoMocha, it'll look like:

it("must pass", function*() {
  yield Promise.resolve(42).must.resolve.to.equal(42)
  yield Promise.resolve([1, 2, 3]).must.resolve.to.not.include(42)
})

Examples:

Promise.resolve(42).must.resolve.to.equal(42)
Promise.resolve([1, 2, 3]).must.resolve.to.not.include(42)

Must.prototype.startWith(expected)

Assert a string starts with the given string.

Examples:

"Hello, John".must.startWith("Hello")

Must.prototype.string()

Assert object is a string. Boxed string objects (new String) are not considered strings.

Examples:

"Hello".must.be.a.string()

Must.prototype.symbol()

Assert object is a symbol.

Examples:

Symbol().must.be.a.symbol()

Must.prototype.the

Pass-through property for a fluent chain.

Examples:

(42).must.be.the.number()

Must.prototype.then

Alias of resolve.

Examples:

Promise.resolve(42).must.then.equal(42)

Must.prototype.throw([constructor], [expected])

Assert that a function throws. Optionally assert it throws expected (and/or is of instance constructor). When you already have an error reference, use error.

Given expected, the error is asserted as follows:

  • A string is compared with the exception's message property.
  • A regular expression is matched against the exception's message property.
  • A function (a.k.a. constructor) is used to check if the error is an instanceof that constructor.
  • All other cases of expected are left unspecified for now.

Because of how JavaScript works, the function will be called in null context (this). If you want to test an instance method, bind it: obj.method.bind(obj).must.throw().

Examples:

function omg() {
  throw new RangeError("Everything's amazing and nobody's happy")
}

omg.must.throw()
omg.must.throw("Everything's amazing and nobody's happy")
omg.must.throw(/amazing/)
omg.must.throw(Error)
omg.must.throw(RangeError)
omg.must.throw(RangeError, "Everything's amazing and nobody's happy")
omg.must.throw(RangeError, /amazing/)

Must.prototype.to

Pass-through property for a fluent chain.

Examples:

var expect = require("must")
expect(true).to.be.true()

var wish = require("must")
wish(life).to.be.truthy()

Must.prototype.true()

Assert object is true. A boxed boolean object (new Boolean(true) is not considered true.

Examples:

true.must.be.true()

Must.prototype.truthy()

Assert object is truthy (!!obj).

Only null, undefined, 0, false and "" are falsy in JavaScript. Everything else is truthy.

Examples:

(42).must.be.truthy()
"Hello".must.be.truthy()

Must.prototype.undefined()

Assert object is undefined.

Because JavaScript does not allow method calls on undefined, you'll have to wrap an expected undefined with Must. Assigning require("must") to expect or demand works well.

If you want to assert that an object's property is undefined, see property.

Examples:

var demand = require("must")
demand(undefined).be.undefined()

Must.prototype.with

Pass-through property for a fluent chain.

Examples:

Promise.resolve(42).must.resolve.with.number()

Object

Object.prototype.must

Creates an instance of Must with the current object for asserting and calling matchers on.

This property is non-enumerable just like built-in properties, so it'll never interfere with any regular usage of objects.

Please note that JavaScript does not allow method calls on null or undefined, so you'll sometimes have to call Must on them by hand. Assigning require("must") to expect or demand works well with those cases.

Examples:

true.must.be.true()
[].must.be.empty()

AssertionError(message, [options])

Error object thrown when an assertion fails.

assertionError.actual

The asserted object.

assertionError.diffable

Whether it makes sense to compare objects granularly or even show a diff view of the objects involved.

Most matchers (e.g. empty and string) are concrete, strict and atomic and don't lend themselves to be compared property by property. Others however, like eql, are more granular and comparing them line by line helps understand how they differ.

assertionError.expected

If the matcher took an argument or asserted against something (like foo.must.be.true()), then this is the expected value.

assertionError.showDiff

Alias of diffable. Some test runners (like Mocha) expect this property instead.

assertionError.stack

The stack trace starting from the code that called must.