Plugin Utilities

The plugin utilities are for those who want to extand 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

type(object)

  • @param{ Mixed }objectto detect type of

Better implementation of typeof detection that can be used cross-browser. Handles the inconsistencies of Array, null, and undefined detection. 

utils.type({}) // 'object'
utils.type(null) // `null'
utils.type(undefined) // `undefined`
utils.type([]) // `array`

.addMethod (ctx, name, method)

  • @param{ Object }ctxobject to which the method is added
  • @param{ String }nameof method to add
  • @param{ Function }methodfunction 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 }ctxobject to which the property is added
  • @param{ String }nameof property to add
  • @param{ Function }getterfunction 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;

overwriteMethod (ctx, name, fn)

  • @param{ Object }ctxobject whose method is to be overwritten
  • @param{ String }nameof method to overwrite
  • @param{ Function }methodfunction 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');

addChainableMethod (ctx, name, method, chainingBehavior)

  • @param{ Object }ctxobject to which the method is added
  • @param{ String }nameof method to add
  • @param{ Function }methodfunction to be used for `name`, when called
  • @param{ Function }chainingBehaviorfunction 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');

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`

transferFlags(assertion, object, includeAll = true)

  • @param{ Assertion }assertionthe assertion to transfer the flags from
  • @param{ Object }objectthe object to transfer the flags too; 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);

.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

overwriteProperty (ctx, name, fn)

  • @param{ Object }ctxobject whose property is to be overwritten
  • @param{ String }nameof property to overwrite
  • @param{ Function }getterfunction 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;