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)

  • @param { Object } ctx object to which the method is added
  • @param { String } name of method to add
  • @param { Function } method function to be used for `name`, when called
  • @param { Function } chainingBehavior function to be called every time the property is accessed

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)

  • @param { Object } ctx object to which the method is added
  • @param { String } name of method to add
  • @param { Function } method function to be used for name

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)

  • @param { Object } ctx object to which the property is added
  • @param { String } name of property to add
  • @param { Function } getter function to be used for name

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)

  • @param { Mixed } obj constructed Assertion
  • @param { Array } type A list of allowed types for this assertion

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

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

flag(object, key, [value])

  • @param { Object } object constructed Assertion
  • @param { String } key
  • @param { Mixed } value (optional)

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])

  • @param { Object } object (constructed Assertion)
  • @param { Arguments } chai.Assertion.prototype.assert arguments

Returns the actual value for an Assertion

.getEnumerableProperties(object)

  • @param { Object } object

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

.getMessage(object, message, negateMessage)

  • @param { Object } object (constructed Assertion)
  • @param { Arguments } chai.Assertion.prototype.assert arguments

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)

  • @param { Function } a function (usually a constructor)

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

.getPathInfo(path, object)

  • @param { String } path
  • @param { Object } 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)

  • @param { String } path
  • @param { Object } 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)

  • @param { Object } object

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

.hasProperty(object, name)

  • @param { Objuect } object
  • @param { String | Number } 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.

  • @param { Object } obj The object to print out.
  • @param { Boolean } showHidden Flag that shows hidden (not enumerable) properties of objects.
  • @param { Number } depth Depth in which to descend in object. Default is 2.
  • @param { Boolean } colors Flag to turn on ANSI escape codes to color the output. Default is false (no coloring).

.objDisplay (object)

  • @param { Mixed } javascript object to inspect

Determines if an object or an array matches criteria to be inspected in-line for error messages or should be truncated.

overwriteChainableMethod (ctx, name, method, chainingBehavior)

  • @param { Object } ctx object whose method / property is to be overwritten
  • @param { String } name of method / property to overwrite
  • @param { Function } method function that returns a function to be used for name
  • @param { Function } chainingBehavior function that returns a function to be used for property

Overwites an already existing chainable method and provides access to the previous function or property. Must return functions to be used for name.

utils.overwriteChainableMethod(chai.Assertion.prototype, 'length',
  function (_super) {
  }
, function (_super) {
  }
);

Can also be accessed directly from chai.Assertion.

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

Then can be used as any other assertion.

expect(myFoo).to.have.length(3);
expect(myFoo).to.have.length.above(3);

overwriteMethod (ctx, name, fn)

  • @param { Object } ctx object whose method is to be overwritten
  • @param { String } name of method to overwrite
  • @param { Function } method function that returns a function to be used for name

Overwites an already existing method and provides access to previous function. Must return function to be used for name.

utils.overwriteMethod(chai.Assertion.prototype, 'equal', function (_super) {
  return function (str) {
    var obj = utils.flag(this, 'object');
    if (obj instanceof Foo) {
      new chai.Assertion(obj.value).to.equal(str);
    } else {
      _super.apply(this, arguments);
    }
  }
});

Can also be accessed directly from chai.Assertion.

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

Then can be used as any other assertion.

expect(myFoo).to.equal('bar');

overwriteProperty (ctx, name, fn)

  • @param { Object } ctx object whose property is to be overwritten
  • @param { String } name of property to overwrite
  • @param { Function } getter function that returns a getter function to be used for name

Overwites an already existing property getter and provides access to previous value. Must return function to use as getter.

utils.overwriteProperty(chai.Assertion.prototype, 'ok', function (_super) {
  return function () {
    var obj = utils.flag(this, 'object');
    if (obj instanceof Foo) {
      new chai.Assertion(obj.name).to.equal('bar');
    } else {
      _super.call(this);
    }
  }
});

Can also be accessed directly from chai.Assertion.

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

Then can be used as any other assertion.

expect(myFoo).to.be.ok;

test(object, expression)

  • @param { Object } object (constructed Assertion)
  • @param { Arguments } chai.Assertion.prototype.assert arguments

Test and object for expression.

transferFlags(assertion, object, includeAll = true)

  • @param { Assertion } assertion the assertion to transfer the flags from
  • @param { Object } object the object to transfer the flags to; usually a new assertion
  • @param { Boolean } includeAll

Transfer all the flags for assertion to object. If includeAll is set to false, then the base Chai assertion flags (namely object, ssfi, and message) will not be transferred.

var newAssertion = new Assertion();
utils.transferFlags(assertion, newAssertion);

var anotherAsseriton = new Assertion(myObj);
utils.transferFlags(assertion, anotherAssertion, false);