BDD
BDDスタイルはexpectとshouldです。どちらも同じチェーン可能な言語を使用してアサーションを構築しますが、アサーションの初期構築方法が異なります。スタイルガイドで比較してください。
APIリファレンス
言語チェーン
アサーションの可読性を向上させるために、次のものがチェーン可能なゲッターとして提供されています。
チェーン
- to
- be
- been
- is
- that
- which
- and
- has
- have
- with
- at
- of
- same
- but
- does
- still
- also
.not
チェーンに続くすべてのアサーションを否定します。
expect(function () {}).to.not.throw();
expect({a: 1}).to.not.have.property('b');
expect([1, 2]).to.be.an('array').that.does.not.include(3);
.notで任意のアサーションを否定できるからといって、そうすべきとは限りません。大きな力には大きな責任が伴います。無数の予期しない出力が生成されなかったことを主張するのではなく、1つの期待される出力が生成されたことを主張するのが最適な場合が多いです。具体的なガイダンスについては、個々のアサーションを参照してください。
expect(2).to.equal(2); // Recommended
expect(2).to.not.equal(1); // Not recommended
.deep
チェーンに続くすべてのアサーション.equal、.include、.members、.keys、および.propertyで、厳密な(===)等価性ではなく、深層等価性が使用されるようになります。deep-eqlプロジェクトページで、深層等価性アルゴリズムに関する情報を確認してください: https://github.com/chaijs/deep-eql。
// Target object deeply (but not strictly) equals `{a: 1}`
expect({a: 1}).to.deep.equal({a: 1});
expect({a: 1}).to.not.equal({a: 1});
// Target array deeply (but not strictly) includes `{a: 1}`
expect([{a: 1}]).to.deep.include({a: 1});
expect([{a: 1}]).to.not.include({a: 1});
// Target object deeply (but not strictly) includes `x: {a: 1}`
expect({x: {a: 1}}).to.deep.include({x: {a: 1}});
expect({x: {a: 1}}).to.not.include({x: {a: 1}});
// Target array deeply (but not strictly) has member `{a: 1}`
expect([{a: 1}]).to.have.deep.members([{a: 1}]);
expect([{a: 1}]).to.not.have.members([{a: 1}]);
// Target set deeply (but not strictly) has key `{a: 1}`
expect(new Set([{a: 1}])).to.have.deep.keys([{a: 1}]);
expect(new Set([{a: 1}])).to.not.have.keys([{a: 1}]);
// Target object deeply (but not strictly) has property `x: {a: 1}`
expect({x: {a: 1}}).to.have.deep.property('x', {a: 1});
expect({x: {a: 1}}).to.not.have.property('x', {a: 1});
.nested
チェーンに続くすべてのアサーション.propertyおよび.includeで、ドット表記とブラケット表記を有効にします。
expect({a: {b: ['x', 'y']}}).to.have.nested.property('a.b[1]');
expect({a: {b: ['x', 'y']}}).to.nested.include({'a.b[1]': 'y'});
.または[]が実際のプロパティ名の一部である場合、その前にバックスラッシュを2つ追加することでエスケープできます。
expect({'.a': {'[b]': 'x'}}).to.have.nested.property('\\.a.\\[b\\]');
expect({'.a': {'[b]': 'x'}}).to.nested.include({'\\.a.\\[b\\]': 'x'});
.nestedは.ownと組み合わせることはできません。
.own
チェーンに続くすべてのアサーション.propertyおよび.includeで、継承されたプロパティが無視されるようになります。
Object.prototype.b = 2;
expect({a: 1}).to.have.own.property('a');
expect({a: 1}).to.have.property('b');
expect({a: 1}).to.not.have.own.property('b');
expect({a: 1}).to.own.include({a: 1});
expect({a: 1}).to.include({b: 2}).but.not.own.include({b: 2});
.ownは.nestedと組み合わせることはできません。
.ordered
チェーンに続くすべてのアサーション.membersで、メンバーが同じ順序であることが求められます。
expect([1, 2]).to.have.ordered.members([1, 2])
.but.not.have.ordered.members([2, 1]);
.includeと.orderedを組み合わせると、両方の配列の先頭から順序付けが始まります。
expect([1, 2, 3]).to.include.ordered.members([1, 2])
.but.not.include.ordered.members([2, 3]);
.any
チェーンに続くすべてのアサーション.keysで、ターゲットに指定されたキーの少なくとも1つがあることのみが求められます。これは、ターゲットに指定されたすべてのキーがあることを求める.allとは逆です。
expect({a: 1, b: 2}).to.not.have.any.keys('c', 'd');
.anyまたは.allを使用する際のガイダンスについては、.keysのドキュメントを参照してください。
.all
チェーンに続くすべてのアサーション.keysで、ターゲットに指定されたすべてのキーがあることが求められます。これは、ターゲットに指定されたキーの少なくとも1つがあることのみを求める.anyとは逆です。
expect({a: 1, b: 2}).to.have.all.keys('a', 'b');
.allも.anyもチェーン内で先に追加されていない場合、デフォルトで.allが使用されます。しかし、可読性を向上させるために.allを追加するのが最適な場合が多いです。
.anyまたは.allを使用する際のガイダンスについては、.keysのドキュメントを参照してください。
.a(type[, msg])
ターゲットの型が指定された文字列typeと等しいことをアサートします。型は大文字と小文字を区別しません。type-detectプロジェクトページで、型検出アルゴリズムに関する情報を確認してください: https://github.com/chaijs/type-detect。
expect('foo').to.be.a('string');
expect({a: 1}).to.be.an('object');
expect(null).to.be.a('null');
expect(undefined).to.be.an('undefined');
expect(new Error).to.be.an('error');
expect(Promise.resolve()).to.be.a('promise');
expect(new Float32Array).to.be.a('float32array');
expect(Symbol()).to.be.a('symbol');
.aは、Symbol.toStringTagを介してカスタム型が設定されているオブジェクトをサポートします。
var myObj = {
[Symbol.toStringTag]: 'myCustomType'
};
expect(myObj).to.be.a('myCustomType').but.not.an('object');
同じターゲットに対してさらにアサーションを行う前に、.aを使用してターゲットの型をチェックするのが最適な場合が多いです。そうすることで、ターゲットの型に基づいて異なる動作をするアサーションによる予期しない動作を回避できます。
expect([1, 2, 3]).to.be.an('array').that.includes(2);
expect([]).to.be.an('array').that.is.empty;
.aを否定するには、チェーン内で先に.notを追加します。しかし、多くの予期しない型ではないことを主張するのではなく、ターゲットが期待される型であることを主張するのが最適な場合が多いです。
expect('foo').to.be.a('string'); // Recommended
expect('foo').to.not.be.an('array'); // Not recommended
.aは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け入れます。メッセージは、expectへの第2引数としても指定できます。
expect(1).to.be.a('string', 'nooo why fail??');
expect(1, 'nooo why fail??').to.be.a('string');
.aは、アサーションの可読性を向上させるための言語チェーンとしても使用できます。
expect({b: 2}).to.have.a.property('b');
エイリアスの.anは、.aと交換して使用できます。
.include(val[, msg])
ターゲットが文字列の場合、.includeは、指定された文字列valがターゲットのサブストリングであることをアサートします。
expect('foobar').to.include('foo');
ターゲットが配列の場合、.includeは、指定されたvalがターゲットのメンバーであることをアサートします。
expect([1, 2, 3]).to.include(2);
ターゲットがオブジェクトの場合、.includeは、指定されたオブジェクトvalのプロパティがターゲットのプロパティのサブセットであることをアサートします。
expect({a: 1, b: 2, c: 3}).to.include({a: 1, b: 2});
ターゲットがSetまたはWeakSetの場合、.includeは、指定されたvalがターゲットのメンバーであることをアサートします。SameValueZero等価性アルゴリズムが使用されます。
expect(new Set([1, 2])).to.include(2);
ターゲットがMapの場合、.includeは、指定されたvalがターゲットの値の1つであることをアサートします。SameValueZero等価性アルゴリズムが使用されます。
expect(new Map([['a', 1], ['b', 2]])).to.include(2);
.includeはターゲットの型に基づいて異なる動作をするため、.includeを使用する前にターゲットの型をチェックすることが重要です。.aのドキュメントで、ターゲットの型のテストに関する情報を確認してください。
expect([1, 2, 3]).to.be.an('array').that.includes(2);
デフォルトでは、厳密な(===)等価性が配列のメンバーとオブジェクトのプロパティの比較に使用されます。代わりに深層等価性を使用するには、チェーン内で先に.deepを追加します（WeakSetターゲットはサポートされていません）。deep-eqlプロジェクトページで、深層等価性アルゴリズムに関する情報を確認してください: https://github.com/chaijs/deep-eql。
// Target array deeply (but not strictly) includes `{a: 1}`
expect([{a: 1}]).to.deep.include({a: 1});
expect([{a: 1}]).to.not.include({a: 1});
// Target object deeply (but not strictly) includes `x: {a: 1}`
expect({x: {a: 1}}).to.deep.include({x: {a: 1}});
expect({x: {a: 1}}).to.not.include({x: {a: 1}});
デフォルトでは、オブジェクトを扱う場合、ターゲットのプロパティすべてが検索されます。これには、継承されたプロパティや列挙できないプロパティが含まれます。検索からターゲットの継承されたプロパティを除外するには、チェーン内で先に.ownを追加します。
Object.prototype.b = 2;
expect({a: 1}).to.own.include({a: 1});
expect({a: 1}).to.include({b: 2}).but.not.own.include({b: 2});
ターゲットオブジェクトは、常にvalの列挙可能なプロパティのみを検索対象とします。
.deepと.ownは組み合わせることができます。
expect({a: {b: 2}}).to.deep.own.include({a: {b: 2}});
ネストされたプロパティを参照する際にドット記法とブラケット記法を有効にするには、チェーンの先頭に.nestedを追加します。
expect({a: {b: ['x', 'y']}}).to.nested.include({'a.b[1]': 'y'});
.または[]が実際のプロパティ名の一部である場合、その前にバックスラッシュを2つ追加することでエスケープできます。
expect({'.a': {'[b]': 2}}).to.nested.include({'\\.a.\\[b\\]': 2});
.deepと.nestedは組み合わせて使用できます。
expect({a: {b: [{c: 3}]}}).to.deep.nested.include({'a.b[0]': {c: 3}});
.ownと.nestedは組み合わせることができません。
.includeを否定するには、チェーンの先頭に.notを追加します。
expect('foobar').to.not.include('taco');
expect([1, 2, 3]).to.not.include(4);
しかし、対象がオブジェクトの場合、.includeを否定することは危険です。問題は、対象オブジェクトがvalのすべてのキー/値ペアを持っていないと主張することで、不確実な期待を生み出すことです。一部のキー/値ペアを持っている場合と持っていない場合があります。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが最善策です。
対象オブジェクトがvalのキーを持つことが期待されていない場合、それを正確にアサートするのが最善策です。
expect({c: 3}).to.not.have.any.keys('a', 'b'); // Recommended
expect({c: 3}).to.not.include({a: 1, b: 2}); // Not recommended
対象オブジェクトがvalのキーを持つことが期待されている場合、多くの予期しない値のいずれかを持っていないとアサートするのではなく、各プロパティが期待される値を持っているとアサートするのが最善策です。
expect({a: 3, b: 4}).to.include({a: 3, b: 4}); // Recommended
expect({a: 3, b: 4}).to.not.include({a: 1, b: 2}); // Not recommended
.includeは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け入れます。メッセージは、expectの第2引数としても指定できます。
expect([1, 2, 3]).to.include(4, 'nooo why fail??');
expect([1, 2, 3], 'nooo why fail??').to.include(4);
.includeは言語チェーンとしても使用でき、チェーンに続くすべての.membersおよび.keysアサーションで、対象が期待される集合のスーパーセットであること（同一の集合であることではない）を要求します。.includeが追加されると、.membersはサブセット内の重複を無視することに注意してください。
// Target object's keys are a superset of ['a', 'b'] but not identical
expect({a: 1, b: 2, c: 3}).to.include.all.keys('a', 'b');
expect({a: 1, b: 2, c: 3}).to.not.have.all.keys('a', 'b');
// Target array is a superset of [1, 2] but not identical
expect([1, 2, 3]).to.include.members([1, 2]);
expect([1, 2, 3]).to.not.have.members([1, 2]);
// Duplicates in the subset are ignored
expect([1, 2, 3]).to.include.members([1, 2, 2, 2]);
チェーンの先頭に.anyを追加すると、.keysアサーションは.includeを無視することに注意してください。
// Both assertions are identical
expect({a: 1}).to.include.any.keys('a', 'b');
expect({a: 1}).to.have.any.keys('a', 'b');
.includes、.contain、.containsというエイリアスは、.includeと交換して使用できます。
.ok
対象が真偽値（ブール値のコンテキストではtrueとみなされる値）であるとアサートします。ただし、対象が厳密に（===）または深く、期待される値と等しいとアサートするのが最善策です。
expect(1).to.equal(1); // Recommended
expect(1).to.be.ok; // Not recommended
expect(true).to.be.true; // Recommended
expect(true).to.be.ok; // Not recommended
.okを否定するには、チェーンの先頭に.notを追加します。
expect(0).to.equal(0); // Recommended
expect(0).to.not.be.ok; // Not recommended
expect(false).to.be.false; // Recommended
expect(false).to.not.be.ok; // Not recommended
expect(null).to.be.null; // Recommended
expect(null).to.not.be.ok; // Not recommended
expect(undefined).to.be.undefined; // Recommended
expect(undefined).to.not.be.ok; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(false, 'nooo why fail??').to.be.ok;
.true
対象が厳密に（===）trueと等しいとアサートします。
expect(true).to.be.true;
.trueを否定するには、チェーンの先頭に.notを追加します。ただし、trueと等しくないというよりも、対象が期待される値と等しいとアサートするのが最善策です。
expect(false).to.be.false; // Recommended
expect(false).to.not.be.true; // Not recommended
expect(1).to.equal(1); // Recommended
expect(1).to.not.be.true; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(false, 'nooo why fail??').to.be.true;
.false
対象が厳密に（===）falseと等しいとアサートします。
expect(false).to.be.false;
.falseを否定するには、チェーンの先頭に.notを追加します。ただし、falseと等しくないというよりも、対象が期待される値と等しいとアサートするのが最善策です。
expect(true).to.be.true; // Recommended
expect(true).to.not.be.false; // Not recommended
expect(1).to.equal(1); // Recommended
expect(1).to.not.be.false; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(true, 'nooo why fail??').to.be.false;
.null
対象が厳密に（===）nullと等しいとアサートします。
expect(null).to.be.null;
.nullを否定するには、チェーンの先頭に.notを追加します。ただし、nullと等しくないというよりも、対象が期待される値と等しいとアサートするのが最善策です。
expect(1).to.equal(1); // Recommended
expect(1).to.not.be.null; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(42, 'nooo why fail??').to.be.null;
.undefined
対象が厳密に（===）undefinedと等しいとアサートします。
expect(undefined).to.be.undefined;
.undefinedを否定するには、チェーンの先頭に.notを追加します。ただし、undefinedと等しくないというよりも、対象が期待される値と等しいとアサートするのが最善策です。
expect(1).to.equal(1); // Recommended
expect(1).to.not.be.undefined; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(42, 'nooo why fail??').to.be.undefined;
.NaN
対象が正確にNaNであるとアサートします。
expect(NaN).to.be.NaN;
.NaNを否定するには、チェーンの先頭に.notを追加します。ただし、NaNと等しくないというよりも、対象が期待される値と等しいとアサートするのが最善策です。
expect('foo').to.equal('foo'); // Recommended
expect('foo').to.not.be.NaN; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(42, 'nooo why fail??').to.be.NaN;
.exist
対象が厳密に（===）nullまたはundefinedのいずれにも等しくないことをアサートします。ただし、対象が期待される値と等しいとアサートするのが最善策です。
expect(1).to.equal(1); // Recommended
expect(1).to.exist; // Not recommended
expect(0).to.equal(0); // Recommended
expect(0).to.exist; // Not recommended
.existを否定するには、チェーンの先頭に.notを追加します。
expect(null).to.be.null; // Recommended
expect(null).to.not.exist; // Not recommended
expect(undefined).to.be.undefined; // Recommended
expect(undefined).to.not.exist; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(null, 'nooo why fail??').to.exist;
.existsというエイリアスは、.existと交換して使用できます。
.empty
対象が文字列または配列の場合、.emptyは、対象のlengthプロパティが厳密に（===）0と等しいとアサートします。
expect([]).to.be.empty;
expect('').to.be.empty;
対象がマップまたはセットの場合、.emptyは、対象のsizeプロパティが厳密に0と等しいとアサートします。
expect(new Set()).to.be.empty;
expect(new Map()).to.be.empty;
対象が非関数オブジェクトの場合、.emptyは、対象が独自の列挙可能なプロパティを持っていないとアサートします。Symbolベースのキーを持つプロパティはカウントから除外されます。
expect({}).to.be.empty;
.emptyは対象の型に基づいて異なる動作をするため、.emptyを使用する前に対象の型を確認することが重要です。対象の型のテストに関する情報は、.aのドキュメントを参照してください。
expect([]).to.be.an('array').that.is.empty;
.emptyを否定するには、チェーンの先頭に.notを追加します。ただし、空ではないとアサートするよりも、対象が期待される数の値を含むとアサートするのが最善策です。
expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
expect([1, 2, 3]).to.not.be.empty; // Not recommended
expect(new Set([1, 2, 3])).to.have.property('size', 3); // Recommended
expect(new Set([1, 2, 3])).to.not.be.empty; // Not recommended
expect(Object.keys({a: 1})).to.have.lengthOf(1); // Recommended
expect({a: 1}).to.not.be.empty; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect([1, 2, 3], 'nooo why fail??').to.be.empty;
.arguments
対象がargumentsオブジェクトであるとアサートします。
function test () {
expect(arguments).to.be.arguments;
}
test();
.argumentsを否定するには、チェーンの先頭に.notを追加します。ただし、argumentsオブジェクトではないとアサートするよりも、対象が期待される型であるとアサートするのが最善策です。
expect('foo').to.be.a('string'); // Recommended
expect('foo').to.not.be.arguments; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect({}, 'nooo why fail??').to.be.arguments;
.Argumentsというエイリアスは、.argumentsと交換して使用できます。
.equal(val[, msg])
対象が指定されたvalと厳密に（===）等しいとアサートします。
expect(1).to.equal(1);
expect('foo').to.equal('foo');
深い等価性を代わりに使用するには、チェーンの先頭に.deepを追加します。深い等価性アルゴリズムに関する情報は、deep-eqlプロジェクトページ（https://github.com/chaijs/deep-eql）を参照してください。
// Target object deeply (but not strictly) equals `{a: 1}`
expect({a: 1}).to.deep.equal({a: 1});
expect({a: 1}).to.not.equal({a: 1});
// Target array deeply (but not strictly) equals `[1, 2]`
expect([1, 2]).to.deep.equal([1, 2]);
expect([1, 2]).to.not.equal([1, 2]);
.equalを否定するには、チェーンの先頭に.notを追加します。ただし、無数の予期しない値のいずれかと等しくないというよりも、対象が期待される値と等しいとアサートするのが最善策です。
expect(1).to.equal(1); // Recommended
expect(1).to.not.equal(2); // Not recommended
.equalは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け入れます。メッセージは、expectの第2引数としても指定できます。
expect(1).to.equal(2, 'nooo why fail??');
expect(1, 'nooo why fail??').to.equal(2);
.equalsおよびeqというエイリアスは、.equalと交換して使用できます。
.eql(obj[, msg])
対象が指定されたobjと深く等しいとアサートします。深い等価性アルゴリズムに関する情報は、deep-eqlプロジェクトページ（https://github.com/chaijs/deep-eql）を参照してください。
// Target object is deeply (but not strictly) equal to {a: 1}
expect({a: 1}).to.eql({a: 1}).but.not.equal({a: 1});
// Target array is deeply (but not strictly) equal to [1, 2]
expect([1, 2]).to.eql([1, 2]).but.not.equal([1, 2]);
.eqlを否定するには、チェーンの先頭に.notを追加します。ただし、無数の予期しない値と深く等しくないというよりも、対象が期待される値と深く等しいとアサートするのが最善策です。
expect({a: 1}).to.eql({a: 1}); // Recommended
expect({a: 1}).to.not.eql({b: 2}); // Not recommended
.eqlは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け入れます。メッセージは、expectの第2引数としても指定できます。
expect({a: 1}).to.eql({b: 2}, 'nooo why fail??');
expect({a: 1}, 'nooo why fail??').to.eql({b: 2});
.eqlsというエイリアスは、.eqlと交換して使用できます。
.deep.equalアサーションは.eqlとほぼ同一ですが、1つの違いがあります。.deep.equalは、チェーンに続く他のアサーションにも深い等価性の比較を使用させます。
.above(n[, msg])
ターゲットが、与えられた数値または日付 `n` より大きい数値または日付であることをアサートします。ただし、多くの場合、ターゲットが期待値と等しいことをアサートするのが最善です。
expect(2).to.equal(2); // Recommended
expect(2).to.be.above(1); // Not recommended
チェーンの先頭に `.lengthOf` を追加して、ターゲットの `length` または `size` が与えられた数値 `n` より大きいことをアサートします。
expect('foo').to.have.lengthOf(3); // Recommended
expect('foo').to.have.lengthOf.above(2); // Not recommended
expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
expect([1, 2, 3]).to.have.lengthOf.above(2); // Not recommended
チェーンの先頭に `.not` を追加して、`.above` を否定します。
expect(2).to.equal(2); // Recommended
expect(1).to.not.be.above(2); // Not recommended
`.above` は、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションの `msg` 引数を受け入れます。メッセージは、`expect` の第二引数としても指定できます。
expect(1).to.be.above(2, 'nooo why fail??');
expect(1, 'nooo why fail??').to.be.above(2);
エイリアスの `.gt` と `.greaterThan` は、`.above` と互換的に使用できます。
.least(n[, msg])
ターゲットが、与えられた数値または日付 `n` 以上である数値または日付であることをアサートします。ただし、多くの場合、ターゲットが期待値と等しいことをアサートするのが最善です。
expect(2).to.equal(2); // Recommended
expect(2).to.be.at.least(1); // Not recommended
expect(2).to.be.at.least(2); // Not recommended
チェーンの先頭に `.lengthOf` を追加して、ターゲットの `length` または `size` が与えられた数値 `n` 以上であることをアサートします。
expect('foo').to.have.lengthOf(3); // Recommended
expect('foo').to.have.lengthOf.at.least(2); // Not recommended
expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
expect([1, 2, 3]).to.have.lengthOf.at.least(2); // Not recommended
チェーンの先頭に `.not` を追加して、`.least` を否定します。
expect(1).to.equal(1); // Recommended
expect(1).to.not.be.at.least(2); // Not recommended
`.least` は、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションの `msg` 引数を受け入れます。メッセージは、`expect` の第二引数としても指定できます。
expect(1).to.be.at.least(2, 'nooo why fail??');
expect(1, 'nooo why fail??').to.be.at.least(2);
エイリアスの `.gte` と `.greaterThanOrEqual` は、`.least` と互換的に使用できます。
.below(n[, msg])
ターゲットが、与えられた数値または日付 `n` より小さい数値または日付であることをアサートします。ただし、多くの場合、ターゲットが期待値と等しいことをアサートするのが最善です。
expect(1).to.equal(1); // Recommended
expect(1).to.be.below(2); // Not recommended
チェーンの先頭に `.lengthOf` を追加して、ターゲットの `length` または `size` が与えられた数値 `n` より小さいことをアサートします。
expect('foo').to.have.lengthOf(3); // Recommended
expect('foo').to.have.lengthOf.below(4); // Not recommended
expect([1, 2, 3]).to.have.length(3); // Recommended
expect([1, 2, 3]).to.have.lengthOf.below(4); // Not recommended
チェーンの先頭に `.not` を追加して、`.below` を否定します。
expect(2).to.equal(2); // Recommended
expect(2).to.not.be.below(1); // Not recommended
`.below` は、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションの `msg` 引数を受け入れます。メッセージは、`expect` の第二引数としても指定できます。
expect(2).to.be.below(1, 'nooo why fail??');
expect(2, 'nooo why fail??').to.be.below(1);
エイリアスの `.lt` と `.lessThan` は、`.below` と互換的に使用できます。
.most(n[, msg])
ターゲットが、与えられた数値または日付 `n` 以下の数値または日付であることをアサートします。ただし、多くの場合、ターゲットが期待値と等しいことをアサートするのが最善です。
expect(1).to.equal(1); // Recommended
expect(1).to.be.at.most(2); // Not recommended
expect(1).to.be.at.most(1); // Not recommended
チェーンの先頭に `.lengthOf` を追加して、ターゲットの `length` または `size` が与えられた数値 `n` 以下であることをアサートします。
expect('foo').to.have.lengthOf(3); // Recommended
expect('foo').to.have.lengthOf.at.most(4); // Not recommended
expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
expect([1, 2, 3]).to.have.lengthOf.at.most(4); // Not recommended
チェーンの先頭に `.not` を追加して、`.most` を否定します。
expect(2).to.equal(2); // Recommended
expect(2).to.not.be.at.most(1); // Not recommended
`.most` は、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションの `msg` 引数を受け入れます。メッセージは、`expect` の第二引数としても指定できます。
expect(2).to.be.at.most(1, 'nooo why fail??');
expect(2, 'nooo why fail??').to.be.at.most(1);
エイリアスの `.lte` と `.lessThanOrEqual` は、`.most` と互換的に使用できます。
.within(start, finish[, msg])
ターゲットが、与えられた数値または日付 `start` 以上、かつ与えられた数値または日付 `finish` 以下である数値または日付であることをアサートします。ただし、多くの場合、ターゲットが期待値と等しいことをアサートするのが最善です。
expect(2).to.equal(2); // Recommended
expect(2).to.be.within(1, 3); // Not recommended
expect(2).to.be.within(2, 3); // Not recommended
expect(2).to.be.within(1, 2); // Not recommended
チェーンの先頭に `.lengthOf` を追加して、ターゲットの `length` または `size` が与えられた数値 `start` 以上、かつ与えられた数値 `finish` 以下であることをアサートします。
expect('foo').to.have.lengthOf(3); // Recommended
expect('foo').to.have.lengthOf.within(2, 4); // Not recommended
expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
expect([1, 2, 3]).to.have.lengthOf.within(2, 4); // Not recommended
チェーンの先頭に `.not` を追加して、`.within` を否定します。
expect(1).to.equal(1); // Recommended
expect(1).to.not.be.within(2, 4); // Not recommended
`.within` は、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションの `msg` 引数を受け入れます。メッセージは、`expect` の第二引数としても指定できます。
expect(4).to.be.within(1, 3, 'nooo why fail??');
expect(4, 'nooo why fail??').to.be.within(1, 3);
.instanceof(constructor[, msg])
ターゲットが、与えられた `constructor` のインスタンスであることをアサートします。
function Cat () { }
expect(new Cat()).to.be.an.instanceof(Cat);
expect([1, 2]).to.be.an.instanceof(Array);
チェーンの先頭に `.not` を追加して、`.instanceof` を否定します。
expect({a: 1}).to.not.be.an.instanceof(Array);
`.instanceof` は、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションの `msg` 引数を受け入れます。メッセージは、`expect` の第二引数としても指定できます。
expect(1).to.be.an.instanceof(Array, 'nooo why fail??');
expect(1, 'nooo why fail??').to.be.an.instanceof(Array);
ES5 の制限により、Babel や TypeScript などのトランスパイラを使用する場合、`.instanceof` が常に期待通りに動作するとは限りません。特に、`Array`、`Error`、`Map` などの組み込みオブジェクトをサブクラス化する場合、予期しない結果が生じる可能性があります。詳細は、使用しているトランスパイラのドキュメントを参照してください。
- (Babel)
- (TypeScript)
エイリアスの `.instanceOf` は、`.instanceof` と互換的に使用できます。
.property(name[, val[, msg]])
ターゲットが、指定されたキー `name` を持つプロパティを持つことをアサートします。
expect({a: 1}).to.have.property('a');
`val` が指定されている場合、`.property` は、プロパティの値が指定された `val` と等しいこともアサートします。
expect({a: 1}).to.have.property('a', 1);
デフォルトでは、厳密な（`===`）等号が使用されます。チェーンの先頭に `.deep` を追加して、代わりに深い等号を使用します。深い等号アルゴリズムの詳細については、`deep-eql` プロジェクトページを参照してください: https://github.com/chaijs/deep-eql。
// Target object deeply (but not strictly) has property `x: {a: 1}`
expect({x: {a: 1}}).to.have.deep.property('x', {a: 1});
expect({x: {a: 1}}).to.not.have.property('x', {a: 1});
ターゲットの列挙可能なプロパティと列挙不可能なプロパティは、常に検索に含まれます。デフォルトでは、自身のプロパティと継承されたプロパティの両方が含まれます。チェーンの先頭に `.own` を追加して、検索から継承されたプロパティを除外します。
Object.prototype.b = 2;
expect({a: 1}).to.have.own.property('a');
expect({a: 1}).to.have.own.property('a', 1);
expect({a: 1}).to.have.property('b');
expect({a: 1}).to.not.have.own.property('b');
.deepと.ownは組み合わせることができます。
expect({x: {a: 1}}).to.have.deep.own.property('x', {a: 1});
ネストされたプロパティを参照する際にドット記法とブラケット記法を有効にするには、チェーンの先頭に.nestedを追加します。
expect({a: {b: ['x', 'y']}}).to.have.nested.property('a.b[1]');
expect({a: {b: ['x', 'y']}}).to.have.nested.property('a.b[1]', 'y');
.または[]が実際のプロパティ名の一部である場合、その前にバックスラッシュを2つ追加することでエスケープできます。
expect({'.a': {'[b]': 'x'}}).to.have.nested.property('\\.a.\\[b\\]');
.deepと.nestedは組み合わせて使用できます。
expect({a: {b: [{c: 3}]}})
.to.have.deep.nested.property('a.b[0]', {c: 3});
.ownと.nestedは組み合わせることができません。
チェーンの先頭に `.not` を追加して、`.property` を否定します。
expect({a: 1}).to.not.have.property('b');
ただし、`val` を指定して `.property` を否定するのは危険です。これは、ターゲットが指定されたキー `name` を持つプロパティを持たないか、指定されたキー `name` を持つプロパティを持つがその値が指定された `val` と等しくないことをアサートすることで、不確かな期待を作成するためです。多くの場合、期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが最善です。
ターゲットが指定されたキー `name` を持つプロパティを持たないことが期待される場合、それを正確にアサートするのが最善です。
expect({b: 2}).to.not.have.property('a'); // Recommended
expect({b: 2}).to.not.have.property('a', 1); // Not recommended
ターゲットが指定されたキー `name` を持つプロパティを持つことが期待される場合、多くの予期しない値のいずれかを持たないことをアサートするのではなく、プロパティが期待される値を持つことをアサートするのが最善です。
expect({a: 3}).to.have.property('a', 3); // Recommended
expect({a: 3}).to.not.have.property('a', 1); // Not recommended
.property は、チェーンの後続するアサーションの対象を、元のターゲットオブジェクトのプロパティの値に変更します。
expect({a: 1}).to.have.property('a').that.is.a('number');
.property は、オプションの msg 引数を受け付けます。これは、アサーションが失敗した際に表示されるカスタムエラーメッセージです。メッセージは、expect の第2引数として指定することもできます。val を指定しない場合は、第2の方法のみを使用してください。
// Recommended
expect({a: 1}).to.have.property('a', 2, 'nooo why fail??');
expect({a: 1}, 'nooo why fail??').to.have.property('a', 2);
expect({a: 1}, 'nooo why fail??').to.have.property('b');
// Not recommended
expect({a: 1}).to.have.property('b', undefined, 'nooo why fail??');
上記のアサーションは、val を指定しないこととは異なります。代わりに、ターゲットオブジェクトに b プロパティがあり、その値が undefined であることをアサートします。
アサーション .ownProperty と .haveOwnProperty は、.own.property と交換して使用できます。
.ownPropertyDescriptor(name[, descriptor[, msg]])
ターゲットが、指定されたキー name を持つ独自のプロパティ記述子を持つことをアサートします。列挙可能プロパティと非列挙可能プロパティの両方が検索に含まれます。
expect({a: 1}).to.have.ownPropertyDescriptor('a');
descriptor が指定されている場合、.ownPropertyDescriptor は、プロパティの記述子が指定された descriptor と深く等しいこともアサートします。深層等価アルゴリズムの詳細については、deep-eql プロジェクトページを参照してください: https://github.com/chaijs/deep-eql。
expect({a: 1}).to.have.ownPropertyDescriptor('a', {
configurable: true,
enumerable: true,
writable: true,
value: 1,
});
.ownPropertyDescriptor を否定するには、チェーンの先頭に .not を追加します。
expect({a: 1}).to.not.have.ownPropertyDescriptor('b');
しかし、descriptor を指定する場合、.ownPropertyDescriptor を否定することは危険です。問題は、ターゲットが指定されたキー name を持つプロパティ記述子を持たない、または指定されたキー name を持つプロパティ記述子を持つが、指定された descriptor と深く等しくないことをアサートすることで、不確実な期待が生まれることです。多くの場合、期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが最善です。
ターゲットが指定されたキー name を持つプロパティ記述子を持たないことが期待される場合、それを正確にアサートするのが最善です。
// Recommended
expect({b: 2}).to.not.have.ownPropertyDescriptor('a');
// Not recommended
expect({b: 2}).to.not.have.ownPropertyDescriptor('a', {
configurable: true,
enumerable: true,
writable: true,
value: 1,
});
ターゲットが指定されたキー name を持つプロパティ記述子を持つことが期待される場合、多くの予期しない記述子のいずれかを持たないことをアサートするのではなく、プロパティが期待される記述子を持つことをアサートするのが最善です。
// Recommended
expect({a: 3}).to.have.ownPropertyDescriptor('a', {
configurable: true,
enumerable: true,
writable: true,
value: 3,
});
// Not recommended
expect({a: 3}).to.not.have.ownPropertyDescriptor('a', {
configurable: true,
enumerable: true,
writable: true,
value: 1,
});
.ownPropertyDescriptor は、チェーンの後続するアサーションの対象を、元のターゲットオブジェクトのプロパティ記述子の値に変更します。
expect({a: 1}).to.have.ownPropertyDescriptor('a')
.that.has.property('enumerable', true);
.ownPropertyDescriptor は、オプションの msg 引数を受け付けます。これは、アサーションが失敗した際に表示されるカスタムエラーメッセージです。メッセージは、expect の第2引数として指定することもできます。descriptor を指定しない場合は、第2の方法のみを使用してください。
// Recommended
expect({a: 1}).to.have.ownPropertyDescriptor('a', {
configurable: true,
enumerable: true,
writable: true,
value: 2,
}, 'nooo why fail??');
// Recommended
expect({a: 1}, 'nooo why fail??').to.have.ownPropertyDescriptor('a', {
configurable: true,
enumerable: true,
writable: true,
value: 2,
});
// Recommended
expect({a: 1}, 'nooo why fail??').to.have.ownPropertyDescriptor('b');
// Not recommended
expect({a: 1})
.to.have.ownPropertyDescriptor('b', undefined, 'nooo why fail??');
上記のアサーションは、descriptor を指定しないこととは異なります。代わりに、ターゲットオブジェクトに b プロパティ記述子があり、それが undefined と深く等しいことをアサートします。
エイリアスの .haveOwnPropertyDescriptor は、.ownPropertyDescriptor と交換して使用できます。
.lengthOf(n[, msg])
ターゲットの length または size が、指定された数値 n と等しいことをアサートします。
expect([1, 2, 3]).to.have.lengthOf(3);
expect('foo').to.have.lengthOf(3);
expect(new Set([1, 2, 3])).to.have.lengthOf(3);
expect(new Map([['a', 1], ['b', 2], ['c', 3]])).to.have.lengthOf(3);
.lengthOf を否定するには、チェーンの先頭に .not を追加します。しかし、多くの予期しない値と等しくないことをアサートするのではなく、ターゲットの length プロパティが期待される値と等しいことをアサートするのが最善です。
expect('foo').to.have.lengthOf(3); // Recommended
expect('foo').to.not.have.lengthOf(4); // Not recommended
.lengthOf は、オプションの msg 引数を受け付けます。これは、アサーションが失敗した際に表示されるカスタムエラーメッセージです。メッセージは、expect の第2引数として指定することもできます。
expect([1, 2, 3]).to.have.lengthOf(2, 'nooo why fail??');
expect([1, 2, 3], 'nooo why fail??').to.have.lengthOf(2);
.lengthOf は、言語チェーンとしても使用でき、チェーンの後続する .above、.below、.least、.most、.within アサーションはすべて、ターゲットの length プロパティをターゲットとして使用します。しかし、値のある範囲内にあることをアサートするのではなく、ターゲットの length プロパティが期待される長さであることをアサートするのが最善です。
// Recommended
expect([1, 2, 3]).to.have.lengthOf(3);
// Not recommended
expect([1, 2, 3]).to.have.lengthOf.above(2);
expect([1, 2, 3]).to.have.lengthOf.below(4);
expect([1, 2, 3]).to.have.lengthOf.at.least(3);
expect([1, 2, 3]).to.have.lengthOf.at.most(3);
expect([1, 2, 3]).to.have.lengthOf.within(2,4);
互換性の問題により、エイリアスの .length は、.a のような呼び出されていないメソッドから直接チェーンすることはできません。したがって、.length は、すべての状況で .lengthOf と交換して使用することはできません。.length の代わりに常に .lengthOf を使用することをお勧めします。
expect([1, 2, 3]).to.have.a.length(3); // incompatible; throws error
expect([1, 2, 3]).to.have.a.lengthOf(3); // passes as expected
.match(re[, msg])
ターゲットが指定された正規表現 re に一致することをアサートします。
expect('foobar').to.match(/^foo/);
.match を否定するには、チェーンの先頭に .not を追加します。
expect('foobar').to.not.match(/taco/);
.match は、オプションの msg 引数を受け付けます。これは、アサーションが失敗した際に表示されるカスタムエラーメッセージです。メッセージは、expect の第2引数として指定することもできます。
expect('foobar').to.match(/taco/, 'nooo why fail??');
expect('foobar', 'nooo why fail??').to.match(/taco/);
エイリアスの .matches は、.match と交換して使用できます。
.string(str[, msg])
ターゲット文字列が指定された部分文字列 str を含むことをアサートします。
expect('foobar').to.have.string('bar');
.string を否定するには、チェーンの先頭に .not を追加します。
expect('foobar').to.not.have.string('taco');
.string は、オプションの msg 引数を受け付けます。これは、アサーションが失敗した際に表示されるカスタムエラーメッセージです。メッセージは、expect の第2引数として指定することもできます。
expect('foobar').to.have.string('taco', 'nooo why fail??');
expect('foobar', 'nooo why fail??').to.have.string('taco');
.keys(key1[, key2[, …]])
ターゲットオブジェクト、配列、マップ、またはセットが指定されたキーを持つことをアサートします。ターゲット自身の継承されたプロパティのみが検索に含まれます。
ターゲットがオブジェクトまたは配列の場合、キーは1つ以上の文字列引数、単一の配列引数、または単一のオブジェクト引数として指定できます。後者の場合、指定されたオブジェクト内のキーのみが重要で、値は無視されます。
expect({a: 1, b: 2}).to.have.all.keys('a', 'b');
expect(['x', 'y']).to.have.all.keys(0, 1);
expect({a: 1, b: 2}).to.have.all.keys(['a', 'b']);
expect(['x', 'y']).to.have.all.keys([0, 1]);
expect({a: 1, b: 2}).to.have.all.keys({a: 4, b: 5}); // ignore 4 and 5
expect(['x', 'y']).to.have.all.keys({0: 4, 1: 5}); // ignore 4 and 5
ターゲットがマップまたはセットの場合、各キーは個別の引数として指定する必要があります。
expect(new Map([['a', 1], ['b', 2]])).to.have.all.keys('a', 'b');
expect(new Set(['a', 'b'])).to.have.all.keys('a', 'b');
.keys はターゲットの型に基づいて異なる動作をするため、.keys を使用する前にターゲットの型を確認することが重要です。ターゲットの型のテストの詳細については、.a のドキュメントを参照してください。
expect({a: 1, b: 2}).to.be.an('object').that.has.all.keys('a', 'b');
デフォルトでは、厳密な（===）等価性がマップとセットのキーの比較に使用されます。代わりに深層等価性を使用するには、チェーンの先頭に .deep を追加します。深層等価アルゴリズムの詳細については、deep-eql プロジェクトページを参照してください: https://github.com/chaijs/deep-eql。
// Target set deeply (but not strictly) has key `{a: 1}`
expect(new Set([{a: 1}])).to.have.all.deep.keys([{a: 1}]);
expect(new Set([{a: 1}])).to.not.have.all.keys([{a: 1}]);
デフォルトでは、対象は指定されたキーをすべて持っていなければならず、それ以上あってはいけません。対象が指定されたキーの少なくとも1つを持っているだけでよい場合は、チェーンの先頭に.anyを追加します。また、.keysを否定するには、チェーンの先頭に.notを追加します。.keysを否定する場合は.anyを追加し、否定せずに.keysをアサートする場合は.allを使用するのが最適です。
.keysを否定する場合、.not.any.keysは出力の期待値を正確にアサートしますが、.not.all.keysは不確実な期待値を生み出すため、.anyが推奨されます。
// Recommended; asserts that target doesn't have any of the given keys
expect({a: 1, b: 2}).to.not.have.any.keys('c', 'd');
// Not recommended; asserts that target doesn't have all of the given
// keys but may or may not have some of them
expect({a: 1, b: 2}).to.not.have.all.keys('c', 'd');
否定せずに.keysをアサートする場合、.all.keysは出力の期待値を正確にアサートしますが、.any.keysは不確実な期待値を生み出すため、.allが推奨されます。
// Recommended; asserts that target has all the given keys
expect({a: 1, b: 2}).to.have.all.keys('a', 'b');
// Not recommended; asserts that target has at least one of the given
// keys but may or may not have more of them
expect({a: 1, b: 2}).to.have.any.keys('a', 'b');
.allも.anyもチェーンの先頭に現れない場合は、デフォルトで.allが使用されます。ただし、可読性を向上させるため、.allを追加するのが最適な場合が多いです。
// Both assertions are identical
expect({a: 1, b: 2}).to.have.all.keys('a', 'b'); // Recommended
expect({a: 1, b: 2}).to.have.keys('a', 'b'); // Not recommended
対象のキーが期待されるキーのスーパーセットであることを要求するには（同一の集合ではなく）、チェーンの先頭に.includeを追加します。
// Target object's keys are a superset of ['a', 'b'] but not identical
expect({a: 1, b: 2, c: 3}).to.include.all.keys('a', 'b');
expect({a: 1, b: 2, c: 3}).to.not.have.all.keys('a', 'b');
ただし、.anyと.includeを組み合わせると、.anyのみが有効になります。.includeはこの場合は無視されます。
// Both assertions are identical
expect({a: 1}).to.have.any.keys('a', 'b');
expect({a: 1}).to.include.any.keys('a', 'b');
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect({a: 1}, 'nooo why fail??').to.have.key('b');
エイリアスの.keyは.keysと交換して使用できます。
.throw([errorLike], [errMsgMatcher], [msg])
引数が指定されていない場合、.throwは対象関数を呼び出し、エラーがスローされることをアサートします。
var badFn = function () { throw new TypeError('Illegal salmon!'); };
expect(badFn).to.throw();
引数が1つ指定され、それがエラーコンストラクタの場合、.throwは対象関数を呼び出し、そのエラーコンストラクタのインスタンスであるエラーがスローされることをアサートします。
var badFn = function () { throw new TypeError('Illegal salmon!'); };
expect(badFn).to.throw(TypeError);
引数が1つ指定され、それがエラーインスタンスの場合、.throwは対象関数を呼び出し、そのエラーインスタンスと厳密に(===)等しいエラーがスローされることをアサートします。
var err = new TypeError('Illegal salmon!');
var badFn = function () { throw err; };
expect(badFn).to.throw(err);
引数が1つ指定され、それが文字列の場合、.throwは対象関数を呼び出し、その文字列を含むメッセージを持つエラーがスローされることをアサートします。
var badFn = function () { throw new TypeError('Illegal salmon!'); };
expect(badFn).to.throw('salmon');
引数が1つ指定され、それが正規表現の場合、.throwは対象関数を呼び出し、その正規表現に一致するメッセージを持つエラーがスローされることをアサートします。
var badFn = function () { throw new TypeError('Illegal salmon!'); };
expect(badFn).to.throw(/salmon/);
引数が2つ指定され、最初の引数がエラーインスタンスまたはコンストラクタであり、2番目の引数が文字列または正規表現の場合、.throwは関数を呼び出し、上記のように両方の条件を満たすエラーがスローされることをアサートします。
var err = new TypeError('Illegal salmon!');
var badFn = function () { throw err; };
expect(badFn).to.throw(TypeError, 'salmon');
expect(badFn).to.throw(TypeError, /salmon/);
expect(badFn).to.throw(err, 'salmon');
expect(badFn).to.throw(err, /salmon/);
.throwを否定するには、チェーンの先頭に.notを追加します。
var goodFn = function () {};
expect(goodFn).to.not.throw();
ただし、引数を指定して.throwを否定するのは危険です。これは、対象がエラーをスローしない、またはエラーをスローするが指定された型とは異なる型である、または指定された型でエラーをスローするが、指定された文字列を含まないメッセージを持つなど、不確実な期待値を生み出すためです。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが最適です。
対象がエラーをスローしないと予想される場合、それを正確にアサートするのが最適です。
var goodFn = function () {};
expect(goodFn).to.not.throw(); // Recommended
expect(goodFn).to.not.throw(ReferenceError, 'x'); // Not recommended
対象がエラーをスローすると予想される場合、エラーが期待される型であり、期待される文字列を含むメッセージを持つことをアサートするのが、多くの予期しない型を持たず、特定の文字列を含むメッセージを持たないことをアサートするよりも最適です。
var badFn = function () { throw new TypeError('Illegal salmon!'); };
expect(badFn).to.throw(TypeError, 'salmon'); // Recommended
expect(badFn).to.not.throw(ReferenceError, 'x'); // Not recommended
.throwは、チェーンに続くアサーションの対象を、スローされたエラーオブジェクトに変更します。
var err = new TypeError('Illegal salmon!');
err.code = 42;
var badFn = function () { throw err; };
expect(badFn).to.throw(TypeError).with.property('code', 42);
.throwは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け入れます。メッセージは、expectの2番目の引数としても指定できます。2つの引数を指定しない場合は、常に2番目の形式を使用してください。
var goodFn = function () {};
expect(goodFn).to.throw(TypeError, 'x', 'nooo why fail??');
expect(goodFn, 'nooo why fail??').to.throw();
ES5の制限により、BabelやTypeScriptなどのトランスパイラを使用する場合、.throwが常に期待通りに動作するとは限りません。特に、組み込みのErrorオブジェクトをサブクラス化し、そのサブクラス化されたコンストラクタを.throwに渡すと、予期しない結果が生じる可能性があります。詳細については、トランスパイラのドキュメントを参照してください。
- (Babel)
- (TypeScript)
throwアサーションを使用する際の一般的な間違いに注意してください。よくある間違いの1つは、throwアサーションが関数を実行させる代わりに、誤って自分で関数を呼び出してしまうことです。たとえば、fnという名前の関数がスローされるかどうかをテストする場合は、アサーションの対象としてfn()ではなくfnを指定します。
expect(fn).to.throw(); // Good! Tests `fn` as desired
expect(fn()).to.throw(); // Bad! Tests result of `fn()`, not `fn`
特定の引数を渡したときに関数fnがスローされることをアサートする必要がある場合は、fnへの呼び出しを別の関数でラップします。
expect(function () { fn(42); }).to.throw(); // Function expression
expect(() => fn(42)).to.throw(); // ES6 arrow function
もう1つのよくある間違いは、アサーションの対象としてオブジェクトメソッド（またはthisに依存するスタンドアロン関数）を指定することです。これは、関数が.throwによって呼び出されるとthisコンテキストが失われるため問題があります。thisが何であるべきかを知る方法がありません。この問題を回避するには2つの方法があります。1つの解決策は、メソッドまたは関数呼び出しを別の関数でラップすることです。もう1つの解決策はbindを使用することです。
expect(function () { cat.meow(); }).to.throw(); // Function expression
expect(() => cat.meow()).to.throw(); // ES6 arrow function
expect(cat.meow.bind(cat)).to.throw(); // Bind
最後に、JavaScriptではErrorおよびErrorの派生型（ReferenceError、TypeError、およびErrorを拡張するユーザー定義オブジェクトなど）のみをスローするのがベストプラクティスであることに言及しておく価値があります。初期化されたときにスタックトレースを生成する他の型の値はありません。とは言っても、throwアサーションは、技術的にはErrorとその派生型だけでなく、あらゆる型の値のスローをサポートしています。
エイリアスの.throwsと.Throwは.throwと交換して使用できます。
.respondTo(method[, msg])
対象が非関数オブジェクトの場合、.respondToは、対象が指定された名前methodのメソッドを持つことをアサートします。メソッドは、独自のメソッドまたは継承されたメソッドであり、列挙可能または非列挙可能にすることができます。
function Cat () {}
Cat.prototype.meow = function () {};
expect(new Cat()).to.respondTo('meow');
対象が関数の場合は、.respondToは、対象のprototypeプロパティが指定された名前methodのメソッドを持つことをアサートします。同様に、メソッドは独自のメソッドまたは継承されたメソッドであり、列挙可能または非列挙可能にすることができます。
function Cat () {}
Cat.prototype.meow = function () {};
expect(Cat).to.respondTo('meow');
チェーンの先頭に.itselfを追加すると、関数のオブジェクトであっても、.respondToはターゲットを非関数オブジェクトとして扱うようになります。そのため、ターゲットが指定された名前methodを持つメソッドを持つことをアサートするのではなく、ターゲットのprototypeプロパティが指定された名前methodを持つメソッドを持つことをアサートします。
function Cat () {}
Cat.prototype.meow = function () {};
Cat.hiss = function () {};
expect(Cat).itself.to.respondTo('hiss').but.not.respondTo('meow');
.itselfを追加しない場合、.respondToを使用する前にターゲットの型を確認することが重要です。.aのドキュメントを参照して、ターゲットの型を確認する方法を確認してください。
function Cat () {}
Cat.prototype.meow = function () {};
expect(new Cat()).to.be.an('object').that.respondsTo('meow');
チェーンの先頭に.notを追加して.respondToを否定します。
function Dog () {}
Dog.prototype.bark = function () {};
expect(new Dog()).to.not.respondTo('meow');
.respondToは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け付けます。メッセージは、expectの第二引数としても指定できます。
expect({}).to.respondTo('meow', 'nooo why fail??');
expect({}, 'nooo why fail??').to.respondTo('meow');
エイリアスの.respondsToは、.respondToと交換可能に使用できます。
.itself
チェーンの後続するすべての.respondToアサーションが、ターゲットが関数オブジェクトであっても、非関数オブジェクトであるかのように動作するように強制します。そのため、.respondToは、ターゲットが指定された名前のメソッドを持つことをアサートするようになり、ターゲットのprototypeプロパティが指定された名前のメソッドを持つことをアサートするのを防ぎます。
function Cat () {}
Cat.prototype.meow = function () {};
Cat.hiss = function () {};
expect(Cat).itself.to.respondTo('hiss').but.not.respondTo('meow');
.satisfy(matcher[, msg])
指定されたmatcher関数を、ターゲットが最初の引数として渡されて呼び出し、返された値が真であることをアサートします。
expect(1).to.satisfy(function(num) {
return num > 0;
});
チェーンの先頭に.notを追加して.satisfyを否定します。
expect(1).to.not.satisfy(function(num) {
return num > 2;
});
.satisfyは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け付けます。メッセージは、expectの第二引数としても指定できます。
expect(1).to.satisfy(function(num) {
return num > 2;
}, 'nooo why fail??');
expect(1, 'nooo why fail??').to.satisfy(function(num) {
return num > 2;
});
エイリアスの.satisfiesは、.satisfyと交換可能に使用できます。
.closeTo(expected, delta[, msg])
ターゲットが、指定された数値expectedの+/-delta範囲内にある数値であることをアサートします。ただし、多くの場合、ターゲットが期待値と等しいことをアサートするのが最適です。
// Recommended
expect(1.5).to.equal(1.5);
// Not recommended
expect(1.5).to.be.closeTo(1, 0.5);
expect(1.5).to.be.closeTo(2, 0.5);
expect(1.5).to.be.closeTo(1, 1);
チェーンの先頭に.notを追加して.closeToを否定します。
expect(1.5).to.equal(1.5); // Recommended
expect(1.5).to.not.be.closeTo(3, 1); // Not recommended
.closeToは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け付けます。メッセージは、expectの第二引数としても指定できます。
expect(1.5).to.be.closeTo(3, 1, 'nooo why fail??');
expect(1.5, 'nooo why fail??').to.be.closeTo(3, 1);
エイリアスの.approximatelyは、.closeToと交換可能に使用できます。
.members(set[, msg])
ターゲット配列が、指定された配列setと同じメンバーを持つことをアサートします。
expect([1, 2, 3]).to.have.members([2, 1, 3]);
expect([1, 2, 2]).to.have.members([2, 1, 2]);
デフォルトでは、メンバーは厳密な(===)等価性を用いて比較されます。代わりに深い等価性を使用するには、チェーンの先頭に.deepを追加します。深い等価性アルゴリズムの詳細については、deep-eqlプロジェクトページ(https://github.com/chaijs/deep-eql)を参照してください。
// Target array deeply (but not strictly) has member `{a: 1}`
expect([{a: 1}]).to.have.deep.members([{a: 1}]);
expect([{a: 1}]).to.not.have.members([{a: 1}]);
デフォルトでは、順序は関係ありません。メンバーが同じ順序で表示されるようにするには、チェーンの先頭に.orderedを追加します。
expect([1, 2, 3]).to.have.ordered.members([1, 2, 3]);
expect([1, 2, 3]).to.have.members([2, 1, 3])
.but.not.ordered.members([2, 1, 3]);
デフォルトでは、両方の配列は同じサイズである必要があります。ターゲットのメンバーが期待されるメンバーのスーパーセットである必要がある場合は、チェーンの先頭に.includeを追加します。.includeを追加した場合、サブセットでは重複は無視されます。
// Target array is a superset of [1, 2] but not identical
expect([1, 2, 3]).to.include.members([1, 2]);
expect([1, 2, 3]).to.not.have.members([1, 2]);
// Duplicates in the subset are ignored
expect([1, 2, 3]).to.include.members([1, 2, 2, 2]);
.deep、.ordered、および.includeはすべて組み合わせることができます。ただし、.includeと.orderedを組み合わせる場合、順序付けは両方の配列の先頭から始まります。
expect([{a: 1}, {b: 2}, {c: 3}])
.to.include.deep.ordered.members([{a: 1}, {b: 2}])
.but.not.include.deep.ordered.members([{b: 2}, {c: 3}]);
チェーンの先頭に.notを追加して.membersを否定します。ただし、そうすることは危険です。問題は、ターゲット配列が指定された配列setと同じメンバーをすべて持たないことをアサートすることによって、不確かな期待を生み出すことです。一部のメンバーを持つ可能性があり、持たない可能性もあります。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが最適です。
expect([1, 2]).to.not.include(3).and.not.include(4); // Recommended
expect([1, 2]).to.not.have.members([3, 4]); // Not recommended
.membersは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け付けます。メッセージは、expectの第二引数としても指定できます。
expect([1, 2]).to.have.members([1, 2, 3], 'nooo why fail??');
expect([1, 2], 'nooo why fail??').to.have.members([1, 2, 3]);
.oneOf(list[, msg])
ターゲットが指定された配列listのメンバーであることをアサートします。ただし、多くの場合、ターゲットが期待値と等しいことをアサートするのが最適です。
expect(1).to.equal(1); // Recommended
expect(1).to.be.oneOf([1, 2, 3]); // Not recommended
比較は厳密な(===)等価性を使用して実行されます。
チェーンの先頭に.notを追加して.oneOfを否定します。
expect(1).to.equal(1); // Recommended
expect(1).to.not.be.oneOf([2, 3, 4]); // Not recommended
配列と文字列の両方で機能する.containまたは.includeとチェーン接続することもできます。
expect('Today is sunny').to.contain.oneOf(['sunny', 'cloudy'])
expect('Today is rainy').to.not.contain.oneOf(['sunny', 'cloudy'])
expect([1,2,3]).to.contain.oneOf([3,4,5])
expect([1,2,3]).to.not.contain.oneOf([4,5,6])
.oneOfは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け付けます。メッセージは、expectの第二引数としても指定できます。
expect(1).to.be.oneOf([2, 3, 4], 'nooo why fail??');
expect(1, 'nooo why fail??').to.be.oneOf([2, 3, 4]);
.change(subject[, prop[, msg]])
引数を1つ指定した場合、.changeは、ターゲット関数の実行前と実行後とで、指定された関数subjectが異なる値を返すことをアサートします。ただし、多くの場合、subjectが期待値と等しいことをアサートするのが最適です。
var dots = ''
, addDot = function () { dots += '.'; }
, getDots = function () { return dots; };
// Recommended
expect(getDots()).to.equal('');
addDot();
expect(getDots()).to.equal('.');
// Not recommended
expect(addDot).to.change(getDots);
引数を2つ指定した場合、.changeは、ターゲット関数の実行前と実行後とで、指定されたオブジェクトsubjectのpropプロパティの値が異なることをアサートします。
var myObj = {dots: ''}
, addDot = function () { myObj.dots += '.'; };
// Recommended
expect(myObj).to.have.property('dots', '');
addDot();
expect(myObj).to.have.property('dots', '.');
// Not recommended
expect(addDot).to.change(myObj, 'dots');
厳密な(===)等価性が、実行前と実行後の値の比較に使用されます。
チェーンの先頭に.notを追加して.changeを否定します。
var dots = ''
, noop = function () {}
, getDots = function () { return dots; };
expect(noop).to.not.change(getDots);
var myObj = {dots: ''}
, noop = function () {};
expect(noop).to.not.change(myObj, 'dots');
.changeは、アサーションが失敗したときに表示されるカスタムエラーメッセージであるオプションのmsg引数を受け付けます。メッセージは、expectの第二引数としても指定できます。2つの引数を指定しない場合は、常に第二の形式を使用してください。
var myObj = {dots: ''}
, addDot = function () { myObj.dots += '.'; };
expect(addDot).to.not.change(myObj, 'dots', 'nooo why fail??');
var dots = ''
, addDot = function () { dots += '.'; }
, getDots = function () { return dots; };
expect(addDot, 'nooo why fail??').to.not.change(getDots);
.changeはまた、チェーンの後続するすべての.byアサーションが、数値の対象がどれだけ増減したかをアサートするようにします。しかし、.change.byを使用するのは危険です。問題は、対象が指定されたデルタだけ増加するか、または指定されたデルタだけ減少することをアサートすることによって、不確かな期待を生み出すことです。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが最適です。
var myObj = {val: 1}
, addTwo = function () { myObj.val += 2; }
, subtractTwo = function () { myObj.val -= 2; };
expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
expect(addTwo).to.change(myObj, 'val').by(2); // Not recommended
expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
expect(subtractTwo).to.change(myObj, 'val').by(2); // Not recommended
エイリアス .changes は、.change と置き換えて使用できます。
.increase(subject[, prop[, msg]])
引数が1つの場合、.increase は、対象関数の呼び出し後に関数 subject を呼び出した際に返される数値が、呼び出し前よりも大きくなることをアサートします。.increase は、チェーン内の後続するすべての .by アサーションについても、数値がどれだけ大きくなったかをアサートします。任意の数値増加ではなく、期待される数値増加分だけ増加したことをアサートすることが、多くの場合最適です。
var val = 1
, addTwo = function () { val += 2; }
, getVal = function () { return val; };
expect(addTwo).to.increase(getVal).by(2); // Recommended
expect(addTwo).to.increase(getVal); // Not recommended
引数が2つの場合、.increase は、対象関数の呼び出し後、オブジェクト subject の prop プロパティの値が、呼び出し前よりも大きくなることをアサートします。
var myObj = {val: 1}
, addTwo = function () { myObj.val += 2; };
expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
expect(addTwo).to.increase(myObj, 'val'); // Not recommended
チェーンの先頭に .not を追加して .increase を否定できます。ただし、これは危険です。これは、subjectが減少するか、または同じままであるという不確かな期待値を作成するためです。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが、多くの場合最適です。
subjectが減少することが期待される場合、期待される量だけ減少したことをアサートするのが、多くの場合最適です。
var myObj = {val: 1}
, subtractTwo = function () { myObj.val -= 2; };
expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
expect(subtractTwo).to.not.increase(myObj, 'val'); // Not recommended
subjectが同じままであることが期待される場合、まさにそれをアサートするのが、多くの場合最適です。
var myObj = {val: 1}
, noop = function () {};
expect(noop).to.not.change(myObj, 'val'); // Recommended
expect(noop).to.not.increase(myObj, 'val'); // Not recommended
.increase は、アサーションが失敗した際に表示されるカスタムエラーメッセージであるオプションの msg 引数を受け入れます。メッセージは、expect の2番目の引数として指定することもできます。2つの引数を指定しない場合は、常に2番目の形式を使用してください。
var myObj = {val: 1}
, noop = function () {};
expect(noop).to.increase(myObj, 'val', 'nooo why fail??');
var val = 1
, noop = function () {}
, getVal = function () { return val; };
expect(noop, 'nooo why fail??').to.increase(getVal);
エイリアス .increases は、.increase と置き換えて使用できます。
.decrease(subject[, prop[, msg]])
引数が1つの場合、.decrease は、対象関数の呼び出し後に関数 subject を呼び出した際に返される数値が、呼び出し前よりも小さくなることをアサートします。.decrease は、チェーン内の後続するすべての .by アサーションについても、数値がどれだけ小さくなったかをアサートします。任意の数値減少ではなく、期待される数値減少分だけ減少したことをアサートすることが、多くの場合最適です。
var val = 1
, subtractTwo = function () { val -= 2; }
, getVal = function () { return val; };
expect(subtractTwo).to.decrease(getVal).by(2); // Recommended
expect(subtractTwo).to.decrease(getVal); // Not recommended
引数が2つの場合、.decrease は、対象関数の呼び出し後、オブジェクト subject の prop プロパティの値が、呼び出し前よりも小さくなることをアサートします。
var myObj = {val: 1}
, subtractTwo = function () { myObj.val -= 2; };
expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
expect(subtractTwo).to.decrease(myObj, 'val'); // Not recommended
チェーンの先頭に .not を追加して .decrease を否定できます。ただし、これは危険です。これは、subjectが増加するか、または同じままであるという不確かな期待値を作成するためです。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが、多くの場合最適です。
subjectが増加することが期待される場合、期待される量だけ増加したことをアサートするのが、多くの場合最適です。
var myObj = {val: 1}
, addTwo = function () { myObj.val += 2; };
expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
expect(addTwo).to.not.decrease(myObj, 'val'); // Not recommended
subjectが同じままであることが期待される場合、まさにそれをアサートするのが、多くの場合最適です。
var myObj = {val: 1}
, noop = function () {};
expect(noop).to.not.change(myObj, 'val'); // Recommended
expect(noop).to.not.decrease(myObj, 'val'); // Not recommended
.decrease は、アサーションが失敗した際に表示されるカスタムエラーメッセージであるオプションの msg 引数を受け入れます。メッセージは、expect の2番目の引数として指定することもできます。
var myObj = {val: 1}
, noop = function () {};
expect(noop).to.decrease(myObj, 'val', 'nooo why fail??');
var val = 1
, noop = function () {}
, getVal = function () { return val; };
expect(noop, 'nooo why fail??').to.decrease(getVal);
エイリアス .decreases は、.decrease と置き換えて使用できます。
.by(delta[, msg])
チェーン内の .increase アサーションに続く場合、.by は、.increase アサーションの対象が指定された delta だけ増加したことをアサートします。
var myObj = {val: 1}
, addTwo = function () { myObj.val += 2; };
expect(addTwo).to.increase(myObj, 'val').by(2);
チェーン内の .decrease アサーションに続く場合、.by は、.decrease アサーションの対象が指定された delta だけ減少したことをアサートします。
var myObj = {val: 1}
, subtractTwo = function () { myObj.val -= 2; };
expect(subtractTwo).to.decrease(myObj, 'val').by(2);
チェーン内の .change アサーションに続く場合、.by は、.change アサーションの対象が指定された delta だけ増加または減少したことをアサートします。ただし、.change.by を使用することは危険です。これは不確かな期待値を作成するためです。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが、多くの場合最適です。
var myObj = {val: 1}
, addTwo = function () { myObj.val += 2; }
, subtractTwo = function () { myObj.val -= 2; };
expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
expect(addTwo).to.change(myObj, 'val').by(2); // Not recommended
expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
expect(subtractTwo).to.change(myObj, 'val').by(2); // Not recommended
チェーンの先頭に .not を追加して .by を否定できます。ただし、対象が期待されるデルタだけ変化したことをアサートする方が、数え切れないほどの予期しないデルタだけ変化しなかったことをアサートするよりも、多くの場合最適です。
var myObj = {val: 1}
, addTwo = function () { myObj.val += 2; };
// Recommended
expect(addTwo).to.increase(myObj, 'val').by(2);
// Not recommended
expect(addTwo).to.increase(myObj, 'val').but.not.by(3);
.by は、アサーションが失敗した際に表示されるカスタムエラーメッセージであるオプションの msg 引数を受け入れます。メッセージは、expect の2番目の引数として指定することもできます。
var myObj = {val: 1}
, addTwo = function () { myObj.val += 2; };
expect(addTwo).to.increase(myObj, 'val').by(3, 'nooo why fail??');
expect(addTwo, 'nooo why fail??').to.increase(myObj, 'val').by(3);
.extensible
対象が拡張可能であることをアサートします。つまり、新しいプロパティを追加できます。プリミティブは決して拡張可能ではありません。
expect({a: 1}).to.be.extensible;
チェーンの先頭に .not を追加して .extensible を否定できます。
var nonExtensibleObject = Object.preventExtensions({})
, sealedObject = Object.seal({})
, frozenObject = Object.freeze({});
expect(nonExtensibleObject).to.not.be.extensible;
expect(sealedObject).to.not.be.extensible;
expect(frozenObject).to.not.be.extensible;
expect(1).to.not.be.extensible;
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect(1, 'nooo why fail??').to.be.extensible;
.sealed
対象がシールされていることをアサートします。つまり、新しいプロパティを追加できず、既存のプロパティを再構成または削除できません。ただし、既存のプロパティを異なる値に再代入することは可能です。プリミティブは常にシールされています。
var sealedObject = Object.seal({});
var frozenObject = Object.freeze({});
expect(sealedObject).to.be.sealed;
expect(frozenObject).to.be.sealed;
expect(1).to.be.sealed;
チェーンの先頭に .not を追加して .sealed を否定できます。
expect({a: 1}).to.not.be.sealed;
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect({a: 1}, 'nooo why fail??').to.be.sealed;
.frozen
対象がフリーズされていることをアサートします。つまり、新しいプロパティを追加できず、既存のプロパティを異なる値に再代入したり、再構成したり、削除したりできません。プリミティブは常にフリーズされています。
var frozenObject = Object.freeze({});
expect(frozenObject).to.be.frozen;
expect(1).to.be.frozen;
チェーンの先頭に .not を追加して .frozen を否定できます。
expect({a: 1}).to.not.be.frozen;
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect({a: 1}, 'nooo why fail??').to.be.frozen;
.finite
対象が数値であり、NaN または正/負の Infinity ではないことをアサートします。
expect(1).to.be.finite;
チェーンの先頭に .not を追加して .finite を否定できます。ただし、これは危険です。これは、subjectが数値でないか、NaN であるか、正の Infinity であるか、負の Infinity であるという不確かな期待値を作成するためです。期待される正確な出力を特定し、その正確な出力のみを受け入れるアサーションを作成するのが、多くの場合最適です。
対象が数値でないことが期待される場合、多くの予期しない型ではなく、期待される型であることをアサートするのが、多くの場合最適です。
expect('foo').to.be.a('string'); // Recommended
expect('foo').to.not.be.finite; // Not recommended
対象が NaN であることが期待される場合、まさにそれをアサートするのが、多くの場合最適です。
expect(NaN).to.be.NaN; // Recommended
expect(NaN).to.not.be.finite; // Not recommended
対象が正の無限大であることが期待される場合、まさにそれをアサートするのが、多くの場合最適です。
expect(Infinity).to.equal(Infinity); // Recommended
expect(Infinity).to.not.be.finite; // Not recommended
対象が負の無限大であることが期待される場合、まさにそれをアサートするのが、多くの場合最適です。
expect(-Infinity).to.equal(-Infinity); // Recommended
expect(-Infinity).to.not.be.finite; // Not recommended
カスタムエラーメッセージは、expectの第2引数として指定できます。
expect('foo', 'nooo why fail??').to.be.finite;
.fail([message])
.fail(actual, expected, [message], [operator])
失敗をスローします。
expect.fail();
expect.fail("custom error message");
expect.fail(1, 2);
expect.fail(1, 2, "custom error message");
expect.fail(1, 2, "custom error message", ">");
expect.fail(1, 2, undefined, ">");
.fail([message])
.fail(actual, expected, [message], [operator])
失敗をスローします。
should.fail();
should.fail("custom error message");
should.fail(1, 2);
should.fail(1, 2, "custom error message");
should.fail(1, 2, "custom error message", ">");
should.fail(1, 2, undefined, ">");