外掛程式工具

外掛程式工具適用於想要使用自己的一組斷言來擴展 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 的預設行為來比較元素，以便即使是具有不規則/遺失 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.dev.org.tw/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 的 Proxy 保護功能。如果代理伺服器不受支援或透過使用者的 Chai 設定停用，則傳回 false。否則，傳回 true。

.objDisplay(object)

@param { Mixed } javascript 要檢查的物件

判斷物件或陣列是否符合在錯誤訊息中內嵌檢查或截斷的條件。

.overwriteChainableMethod(ctx, name, method, chainingBehavior)

@param { Object } ctx 要覆寫其方法/屬性的物件
@param { String } name 要覆寫的方法/屬性的名稱
@param { Function } method 回傳一個將用於名稱的方法的函式
@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 回傳一個將用於名稱的方法的函式

覆寫已存在的方法，並提供對先前函式的存取。必須回傳將用於名稱的函式。

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