Permalink
Fetching contributors…
Cannot retrieve contributors at this time
1013 lines (819 sloc) 29.1 KB

Must.js API Documentation

Must

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`](#Must.prototype.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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf)) like `Date`.

Examples:

(69).must.be.above(42)
### Must.prototype.after(expected) Alias of [`above`](#Must.prototype.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`](#Must.prototype.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`](#Must.prototype.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`](#Must.prototype.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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/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.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.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`](#Must.prototype.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`](#Must.prototype.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.above). ### Must.prototype.gte(expected) Alias of [`least`](#Must.prototype.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). ### 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`](#Must.prototype.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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/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.below). ### Must.prototype.lte(expected) Alias of [`most`](#Must.prototype.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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/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.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.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`](#Must.prototype.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`](#Must.prototype.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`](#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`](#assertionError.diffable). Some test runners (like [Mocha](http://visionmedia.github.io/mocha/)) expect this property instead. ### assertionError.stack The stack trace starting from the code that called `must`.