插件工具

插件工具是为那些希望用自己的断言集扩展 Chai 的人准备的。核心插件概念和构建一个帮助器指南教程是关于如何开始使用自己的断言的绝佳参考。

API 参考

.addChainableMethod(ctx, name, method, chainingBehavior)

@param { Object } ctx 要添加方法的对象
@param { String } name 要添加的方法名称
@param { Function } method 在调用 `name` 时要使用的函数
@param { Function } chainingBehavior 每次访问属性时要调用的函数

向对象添加一个方法，以便该方法也可以被链式调用。

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

也可以直接从 chai.Assertion 访问。

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

然后，结果可以既用作方法断言，执行 method 和 chainingBehavior，也可以用作语言链，只执行 chainingBehavior。

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

.addLengthGuard(fn, assertionName, isChainable)

@param { Function } fn
@param { String } assertionName
@param { Boolean } isChainable

在给定的未调用方法断言上定义 length 作为 getter。getter 充当对直接在未调用方法断言上链式调用 length 的保护，这是一个问题，因为它引用了 function 的内置 length 属性，而不是 Chai 的 length 断言。当 getter 发现用户犯了这个错误时，它会抛出一个包含有帮助信息的错误。

犯这个错误有两种方式。第一种方式是直接在未调用的可链式方法上链式调用 length 断言。在这种情况下，Chai 建议用户使用 lengthOf 替代。第二种方式是直接在未调用的不可链式方法上链式调用 length 断言。不可链式方法必须在链式调用之前被调用。在这种情况下，Chai 建议用户查阅给定断言的文档。

如果函数的 length 属性不可配置，那么返回 fn 而不进行修改。

请注意，在 ES6 中，函数的 length 属性是可配置的，因此一旦放弃对遗留环境的支持，Chai 的 length 属性就可以替换内置函数的 length 属性，并且这个长度保护将不再需要。在此期间，维护所有环境的一致性是优先事项。

.addMethod(ctx, name, method)

@param { Object } ctx 要添加方法的对象
@param { String } name 要添加的方法名称
@param { Function } method 要用于名称的函数

向对象原型添加一个方法。

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

也可以直接从 chai.Assertion 访问。

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

然后可以像任何其他断言一样使用。

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

.addProperty(ctx, name, getter)

@param { Object } ctx 要添加属性的对象
@param { String } name 要添加的属性名称
@param { Function } getter 要用于名称的函数

向对象原型添加一个属性。

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

也可以直接从 chai.Assertion 访问。

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

然后可以像任何其他断言一样使用。

expect(myFoo).to.be.foo;

.compareByInspect(mixed, mixed)

@param { Mixed } first 要比较的第一个元素
@param { Mixed } second 要比较的第二个元素

用作 Array.prototype.sort 的 compareFunction。使用 inspect 而不是使用 toString 的默认行为来比较元素，以便 Symbols 和具有不规则/缺失 toString 的对象仍然可以在没有 TypeError 的情况下进行排序。

.expectTypes(obj, types)

@param { Mixed } obj 构造的断言
@param { Array } type 此断言允许的类型列表

确保要测试的对象是有效的类型。

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

.flag(object, key, [value])

@param { Object } object 构造的断言
@param { String } key
@param { Mixed } value (可选)

获取或设置对象的标志值。如果提供了值，则会设置该值，否则会返回当前设置的值，如果未设置该值，则返回 undefined。

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

.getActual(object, [actual])

@param { Object } object (构造的断言)
@param { Arguments } chai.Assertion.prototype.assert 参数

返回断言的 actual 值。

.getMessage(object, message, negateMessage)

@param { Object } object (构造的断言)
@param { Arguments } chai.Assertion.prototype.assert 参数

根据标志和模板标签构造错误消息。模板标签将返回对引用对象的字符串化检查。

消息模板标签

#{this} 当前断言对象
#{act} 实际值
#{exp} 预期值

.getOperator(message)

@param { Object } object (构造的断言)
@param { Arguments } chai.Assertion.prototype.assert 参数

从错误消息中提取运算符。定义的运算符基于以下链接 https://node.org.cn/api/assert.html#assert_assert。

返回断言的 operator 或 undefined 值。

.getOwnEnumerableProperties(object)

@param { Object } object

这允许检索对象的直接拥有的可枚举属性名称和符号。此函数是必要的，因为 Object.keys 仅返回可枚举属性名称，而不返回可枚举属性符号。

.getOwnEnumerablePropertySymbols(object)

@param { Object } object

这允许检索对象的直接拥有的可枚举属性符号。此函数是必要的，因为 Object.getOwnPropertySymbols 返回可枚举和不可枚举的属性符号。

.getProperties(object)

@param { Object } object

这允许检索对象的属性名称，无论是否可枚举，无论是否继承。

.inspect(obj, [showHidden], [depth], [colors])

@param { Object } obj 要打印的对象。
@param { Boolean } showHidden 显示对象的隐藏（不可枚举）属性的标志。默认为 false。
@param { Number } depth 在对象中下降的深度。默认为 2。
@param { Boolean } colors 开启 ANSI 转义码以使输出着色的标志。默认为 false（无着色）。

回显值的价值。尝试以尽可能最好的方式打印出该值，方法是根据不同的类型。

.isProxyEnabled()

帮助函数，用于检查 Chai 的代理保护功能是否已启用。如果代理不受支持或通过用户的 Chai 配置被禁用，则返回 false。否则，返回 true。

.objDisplay(object)

@param { Mixed } javascript 要检查的 object

确定对象或数组是否匹配要在线检查以生成错误消息的标准，或者是否应该被截断。

.overwriteChainableMethod(ctx, name, method, chainingBehavior)

@param { Object } ctx 要覆盖其方法/属性的对象
@param { String } name 要覆盖的方法/属性的名称
@param { Function } method 返回一个函数，用于 `name`
@param { Function } chainingBehavior 返回一个函数，用于属性

覆盖已存在的可链式方法，并提供对先前函数或属性的访问。必须返回要用于名称的函数。

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

也可以直接从 chai.Assertion 访问。

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

然后可以像任何其他断言一样使用。

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

.overwriteMethod(ctx, name, fn)

@param { Object } ctx 要覆盖其方法的对象
@param { String } name 要覆盖的方法名称
@param { Function } method 返回一个函数，用于 `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);
    }
  }
});

也可以直接从 chai.Assertion 访问。

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

然后可以像任何其他断言一样使用。

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

.overwriteProperty(ctx, name, fn)

@param { Object } ctx 要覆盖其属性的对象
@param { String } name 要覆盖的属性名称
@param { Function } getter 返回要用于名称的 getter 函数的函数

覆盖已存在的属性 getter，并提供对先前值的访问。必须返回用作 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);
    }
  }
});

也可以直接从 chai.Assertion 访问。

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

然后可以像任何其他断言一样使用。

expect(myFoo).to.be.ok;

.proxify(object)

@param { Object } obj
@param { String } nonChainableMethodName

返回给定对象的代理，当读取不存在的属性时会抛出错误。默认情况下，根本原因被认为是拼写错误的属性，因此会尝试从现有属性列表中提供合理的建议。但是，如果提供了 nonChainableMethodName，则根本原因是未能调用非可链式方法，然后读取不存在的属性。

如果代理不受支持或通过用户 Chai 配置被禁用，则返回未修改的对象。

.test(object, expression)

@param { Object } object (构造的断言)
@param { Arguments } chai.Assertion.prototype.assert 参数

测试对象是否符合表达式。

.transferFlags(assertion, object, includeAll = true)

@param { Assertion } assertion 要从中传输标志的断言
@param { Object } object 要传输标志到的对象；通常是一个新的断言
@param { Boolean } includeAll

将 assertion 的所有标志传输到 object。如果 includeAll 设置为 false，则基本 Chai 断言标志（即 object、ssfi、lockSsfi 和 message）将不会被传输。

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

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

.compatibleInstance(thrown, errorLike)

@param { Error } thrown 错误
@param { Error | ErrorConstructor } errorLike 要比较的对象

检查两个实例是否兼容（严格相等）。如果 errorLike 不是 Error 的实例，则返回 false，因为实例只有在两者都是错误实例时才能兼容。

.compatibleConstructor(thrown, errorLike)

@param { Error } thrown 错误
@param { Error | ErrorConstructor } errorLike 要比较的对象

检查两个构造函数是否兼容。此函数可以接收错误构造函数或错误实例作为 errorLike 参数。如果构造函数相同，或者一个构造函数是另一个构造函数的实例，则构造函数兼容。

.compatibleMessage(thrown, errMatcher)

@param { Error } thrown 错误
@param { String | RegExp } errMatcher 要在消息中查找的内容

检查错误消息是否与匹配器（字符串或正则表达式）兼容。如果消息包含字符串或通过正则表达式测试，则被认为兼容。

.getConstructorName(errorLike)

@param { Error | ErrorConstructor } errorLike

获取 Error 实例或构造函数本身的构造函数名称。

.getMessage(errorLike)

@param { Error | String } errorLike

从错误中获取错误消息。如果 err 本身是字符串，我们返回它。如果错误没有消息，我们返回空字符串。

.getFuncName(constructorFn)

@param { Function } funct

返回函数的名称。当传递非函数实例时，返回 null。这也包括一个 polyfill 函数，如果 aFunc.name 未定义。

.getFuncName(constructorFn)

@param { Function } funct

返回函数的名称。当传递非函数实例时，返回 null。这也包括一个 polyfill 函数，如果 aFunc.name 未定义。

.hasProperty(object, name)

@param { Object } object
@param { String | Symbol } name

这允许检查对象是否具有自身或从原型链继承的命名属性。

基本上与 in 运算符做同样的事情，但对 null/undefined 值和其他基本类型有效。

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

以下是结果。

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

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

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

.getPathInfo(object, path)

@param { Object } object
@param { String } path

这允许在给定字符串路径的情况下检索对象中的属性信息。

路径信息包含一个具有以下属性的对象

parent - 由 path 引用属性的父对象
name - 最后一个属性的名称，如果它是数组索引器，则为数字
value - 属性的值，如果存在，否则为 undefined
exists - 属性是否存在

.getPathValue(object, path)

@param { Object } object
@param { String } path

这允许在给定字符串路径的情况下检索对象中的值。

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

以下是结果。

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