プラグインユーティリティ

プラグインユーティリティは、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をゲッターとして定義します。ゲッターは、呼び出されていないメソッドアサーションからlengthを直接チェーンすることのガードとして機能します。これは、Chaiのlengthアサーションではなく、functionの組み込みlengthプロパティを参照するため、問題となります。ゲッターがユーザーがこのミスを犯していることを検出すると、役に立つメッセージとともにエラーをスローします。

この間違いは2つの方法で発生する可能性があります。1つ目は、lengthアサーションを、呼び出されていないチェーン可能なメソッドから直接チェーンすることです。この場合、ChaiはユーザーにlengthOfを使用することを提案します。2つ目は、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 比較する2番目の要素

Array.prototype.sort で compareFunction として使用されます。toString を使用するデフォルトの動作ではなく、inspect を使用して要素を比較します。そのため、不規則/欠落している 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.dokyumento.jp/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 オブジェクトの hidden (列挙不可) なプロパティを表示するフラグ。デフォルトは false です。
@param { Number } depth オブジェクトを下降する深さ。デフォルトは 2 です。
@param { Boolean } colors 出力をカラー化する ANSI エスケープコードをオンにするフラグ。デフォルトは false (カラーなし) です。

値の値をエコーします。さまざまなタイプを考慮して、可能な限り最良の方法で値を出力しようとします。

.isProxyEnabled()

Chai のプロキシ保護機能が有効になっているかどうかを確認するヘルパー関数。プロキシがサポートされていないか、ユーザーの 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 プロパティに使用される関数を返す関数

既存のチェーン可能なメソッドを上書きし、以前の関数またはプロパティへのアクセスを提供します。 name に使用される関数を返却する必要があります。

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 name に使用されるゲッター関数を返す関数

既存のプロパティゲッターを上書きし、以前の値へのアクセスを提供します。ゲッターとして使用する関数を返却する必要があります。

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 フラグを転送元の Assertion
@param { Object } object フラグを転送先のオブジェクト。通常は新しい Assertion
@param { Boolean } includeAll 全てのフラグを含むかどうか

assertion のすべてのフラグを object に転送します。 includeAll が false に設定されている場合、基本的な Chai assertion フラグ（つまり 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 比較対象のオブジェクト

2 つのインスタンスに互換性があるか（厳密に等しいか）を確認します。 errorLike が Error のインスタンスでない場合は false を返します。インスタンスは、両方ともエラーインスタンスの場合にのみ互換性があります。

.compatibleConstructor(thrown, errorLike)

@param { Error } thrown エラー
@param { Error | ErrorConstructor } errorLike 比較対象のオブジェクト

2 つのコンストラクタに互換性があるかを確認します。この関数は、errorLike 引数としてエラーコンストラクタまたはエラーインスタンスのいずれかを受け取ることができます。コンストラクタは、同じであるか、一方が他方のインスタンスである場合に互換性があります。

.compatibleMessage(thrown, errMatcher)

@param { Error } thrown エラー
@param { String | RegExp } errMatcher メッセージ内で検索する対象

エラーメッセージがマッチャー（String または RegExp）と互換性があるかどうかを確認します。メッセージに文字列が含まれているか、RegExp テストに合格した場合、互換性があると見なされます。

.getConstructorName(errorLike)

@param { Error | ErrorConstructor } errorLike エラーまたはエラーコンストラクタ

Error インスタンスまたはコンストラクタ自体のコンストラクタ名を取得します。

.getMessage(errorLike)

@param { Error | String } errorLike エラーまたはエラーメッセージ

エラーからエラーメッセージを取得します。err が文字列自体の場合、それを返します。エラーにメッセージがない場合は、空の文字列を返します。

.getFuncName(constructorFn)

@param { Function } funct 関数

関数の名前を返します。関数以外のインスタンスが渡された場合は、null を返します。 aFunc.name が定義されていない場合は、ポリフィル関数も含まれます。

.getFuncName(constructorFn)

@param { Function } funct 関数

.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