Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
785 lines (632 sloc) 22.433 kb

Must.js API Documentation

Must

Object

AssertionError

Must(actual)

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

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).be.null()

var demand = require("must")
demand(undefined).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).
Considers boxed boolean objects (new Boolean) also 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.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:

  • Boolean objects are compared to boolean literals.
  • Number objects are compared to number literals.
  • String objects are compared to string literals.
  • 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.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 or new Boolean(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.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.
Considers boxed number objects (new Number) also 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.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.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.string()

Assert object is a string.
Considers boxed string objects (new String) also strings.

Examples:

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

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

Assert that a function throws.
Optionally assert it throws expected (of possibly instance constructor).

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 Error("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(Error, "Everything's amazing and nobody's happy")
omg.must.throw(Error, /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 or new Boolean(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()

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.

Jump to Line
Something went wrong with that request. Please try again.