Plugin Utilities

The plugin utilities are for those who want to extend Chai with their own set of assertions. The Code Plugin Concepts and Building a Helper guide tutorials are a great reference on how to get started with your own assertions.

API Reference

addChainableMethod (ctx, name, method, chainingBehavior)

Adds a method to an object, such that the method can also be chained.

utils.addChainableMethod(chai.Assertion.prototype, 'foo', function (str) {
  var obj = utils.flag(this, 'object');
  new chai.Assertion(obj).to.be.equal(str);
});

Can also be accessed directly from chai.Assertion.

chai.Assertion.addChainableMethod('foo', fn, chainingBehavior);

The result can then be used as both a method assertion, executing both method and chainingBehavior, or as a language chain, which only executes chainingBehavior.

expect(fooStr).to.be.foo('bar');
expect(fooStr).to.be.foo.equal('foo');

.addMethod (ctx, name, method)

Adds a method to the prototype of an object.

utils.addMethod(chai.Assertion.prototype, 'foo', function (str) {
  var obj = utils.flag(this, 'object');
  new chai.Assertion(obj).to.be.equal(str);
});

Can also be accessed directly from chai.Assertion.

chai.Assertion.addMethod('foo', fn);

Then can be used as any other assertion.

expect(fooStr).to.be.foo('bar');

addProperty (ctx, name, getter)

Adds a property to the prototype of an object.

utils.addProperty(chai.Assertion.prototype, 'foo', function () {
  var obj = utils.flag(this, 'object');
  new chai.Assertion(obj).to.be.instanceof(Foo);
});

Can also be accessed directly from chai.Assertion.

chai.Assertion.addProperty('foo', fn);

Then can be used as any other assertion.

expect(myFoo).to.be.foo;

expectTypes(obj, types)

Ensures that the object being tested against is of a valid type.

utils.expectTypes(this, ['array', 'object', 'string']);

flag(object, key, [value])

Get or set a flag value on an object. If a value is provided it will be set, else it will return the currently set value or undefined if the value is not set.

utils.flag(this, 'foo', 'bar'); // setter
utils.flag(this, 'foo'); // getter, returns `bar`

getActual(object, [actual])

Returns the actual value for an Assertion

.getEnumerableProperties(object)

This allows the retrieval of enumerable property names of an object, inherited or not.

.getMessage(object, message, negateMessage)

Construct the error message based on flags and template tags. Template tags will return a stringified inspection of the object referenced.

Message template tags: - #{this} current asserted object - #{act} actual value - #{exp} expected value

getName(func)

Gets the name of a function, in a cross-browser way.

.getPathInfo(path, object)

This allows the retrieval of property info in an object given a string path.

The path info consists of an object with the following properties:

  • parent - The parent object of the property referenced by path
  • name - The name of the final property, a number if it was an array indexer
  • value - The value of the property, if it exists, otherwise undefined
  • exists - Whether the property exists or not

.getPathValue(path, object)

This allows the retrieval of values in an object given a string path.

var obj = {
    prop1: {
        arr: ['a', 'b', 'c']
      , str: 'Hello'
    }
  , prop2: {
        arr: [ { nested: 'Universe' } ]
      , str: 'Hello again!'
    }
}

The following would be the results.

getPathValue('prop1.str', obj); // Hello
getPathValue('prop1.att[2]', obj); // b
getPathValue('prop2.arr[0].nested', obj); // Universe

.getProperties(object)

This allows the retrieval of property names of an object, enumerable or not, inherited or not.

.hasProperty(object, name)

This allows checking whether an object has named property or numeric array index.

Basically does the same thing as the in operator but works properly with natives and null/undefined values.

var obj = {
    arr: ['a', 'b', 'c']
  , str: 'Hello'
}

The following would be the results.

hasProperty('str', obj);  // true
hasProperty('constructor', obj);  // true
hasProperty('bar', obj);  // false

hasProperty('length', obj.str); // true
hasProperty(1, obj.str);  // true
hasProperty(5, obj.str);  // false

hasProperty('length', obj.arr);  // true
hasProperty(2, obj.arr);  // true
hasProperty(3, obj.arr);  // false

Echos the value of a value. Trys to print the value out in the best way possible given the different types.