【Jest】Matcher(マッチャー)の種類と特徴をわかりやすく解説！

この記事では『Matcher(マッチャー)』について

  • Matcher(マッチャー)とは
  • Matcher(マッチャー)の種類
  • 各Matcherの特徴

などを分かりやすく説明するように心掛けています。ご参考になれば幸いです。

Matcher(マッチャー)とは

Matcher(マッチャー)はテスト結果を検証するためのメソッドです。

JestではMatcherを使用して、テストの実行結果と期待値を比較することで、テストの成功や失敗を判定することができます。

MatcherにはtoBeやtoEqualなど様々な種類があります。後ほど「Matcherの種類とその特徴」について詳しく説明しますが、一例として、以下に示すようなtoBeというMatcherを用いたテストコードを見てみましょう。

test('2 + 3 が 5 になるか', () => {
    expect(2 + 3).toBe(5);
});

上記のコードでは、「2+3(テストの実行結果)」が「5(期待値)」と等しくなるかを判定しています。

このように、JestではMatcherを使用して様々なテストをすることができます。

なお、判定を否定する場合には、Matcherの前にnotを付けます。

test('2 + 3 が 4 にならないか', () => {
    expect(2 + 3).not.toBe(4);
});

上記のコードでは、「2+3(テストの実行結果)」が「4(期待値)」と等しくならないかを判定しています。

Matcher(マッチャー)の種類

以下の表にMatcherの種類についてまとめました。

Matcher特徴
toBe(value)「string/number/boolean等のプリミティブ型の値の判定」と「オブジェクトや配列の参照先の判定」に使用するMatcher。
toEqual(value)オブジェクトや配列の判定に使用するMatcher。
toStrictEqual(value)オブジェクトや配列の判定に使用するMatcher。
toEqual(value)よりも厳密に値の比較を行う。
toBeTruthy()truthy(真値)の判定に使用するMatcher。
toBeFalsy()falsy(偽値)の判定に使用するMatcher。
toBeNull()nullの判定に使用するMatcher。
toBeUndefined()undefinedの判定に使用するMatcher。
toBeDefined()toBeUndefined()の反対。
toBeNaN()NaNの判定に使用するMatcher。
toMatch(regexp | string)文字列に対して正規表現でマッチするかを判定するMatcher。
toHaveLength(number)配列や文字列の長さがnumberかを判定するMatcher。
toContain(item)配列に特定の要素が含まれているかを判定するMatcher。
参照先が異なると判定不可。
toContainEqual(item)配列に特定の要素が含まれているかを判定するMatcher。
参照先が異なっていても判定が可能。
toHaveProperty(keyPath[, value])オブジェクトにkeyPathのプロパティが含まれているかを判定するMatcher。
toBeGreaterThan(number)numberより大きいかを判定するMatcher。
toBeGreaterThanOrEqual(number)number以上かを判定するMatcher。
toBeLessThan(number)numberより小さいかを判定するMatcher。
toBeLessThanOrEqual(number)number以下かを判定するMatcher。
toBeCloseTo(number[, numDigits])浮動小数点の値が同一であるかを判定するMatcher。
toThrow([error])例外が発生したかを判定するMatcher。
toThrowError([error])例外が発生したかを判定するMatcher。
toHaveBeenCalled()関数やメソッドが呼ばれたかを判定するMatcher。
toHaveBeenCalledTimes(number)関数やメソッドがnumber回呼ばれたかを判定するMatcher。
toHaveBeenCalledWith(arg1, arg2, …)関数やメソッドが引数arg1やarg2で呼ばれたかを判定するMatcher。

ではそれから各Matcherの特徴についてプログラム例も用いて詳しく説明します。

toBe

toBe(value)は「string/number/boolean等のプリミティブ型の値の判定」と「オブジェクトや配列の参照先の判定」に使用するMatcherです。toBe(value)はObject.isを使用して厳密な等価性をテストしています。

Object. isとは

大まかに説明すると、Object.isは「strict equality(===)」からNaN, -0, +0に対する特別な処理を除いたものです。

例えば、NaNとNaNの比較は、「===」ではfalseを返しますが、「Object.is」ではtrueを返します。また、+0と-0の比較は、「===」ではtrueを返しますが、「Object.is」ではfalseを返します。

// ★NaN, -0, +0に対する特別な処理
// NaN同士の比較はfalse
NaN == NaN      //false
NaN === NaN     //false
// -0, +0の比較はtrue
-0 == +0        //true
-0 === +0       //true

// ★これらの特別な処理を除いたのが「Object.is」
Object.is(NaN, NaN) //true
Object.is(-0, +0)   //false

テストにおいては、同じ値を比較したいので、「strict equality(===)」よりも「Object.is」の方が使いやすいです。

toBeを用いたテストコード

toBe(value)を用いたテストコードを以下に示します。

test('toBeのテスト(プリミティブ値の比較)', () => {
    expect('hoge').toBe('hoge');
    expect(2 + 3).toBe(5);
    expect(true).toBe(true);
});

test('toBeのテスト(オブジェクトと配列の参照先の比較)', () => {
    const obj = { key: 'value' };
    const anotherObj = { key: 'value' };

    const arr = [1, 2, 3];
    const anotherArr = [1, 2, 3];

    // 同じ参照先の場合
    expect(obj).toBe(obj);
    expect(anotherObj).toBe(anotherObj);
    expect(arr).toBe(arr);
    expect(anotherArr).toBe(anotherArr);

    // 同じ値だが、参照先が異なる場合はテスト判定不可
    expect(obj).not.toBe(anotherObj);
    expect(obj).not.toBe({ key: 'value' });
    expect(obj).not.toBe({ ...obj });
    expect(arr).not.toBe(anotherArr);
    expect(arr).not.toBe([1, 2, 3]);
});

toEqualとtoStrictEqual

toEqual(value)とtoStrictEqual(value)は、オブジェクトや配列の判定に使用するMatcherです。toBe(value)とは異なり、参照先が異なっていても判定可能です。

toEqualとtoStrictEqualの違い

toStrictEqual(value)はtoEqual(value)よりも厳密に値の比較を行っています。toEqual(value)に対して、以下の2点に違いがあります。

  • undefinedが指定されているプロパティも等価であるかチェックする
  • インスタンスの生成元クラスが同じであるかもチェックする

このように、toStrictEqual(value)は厳密な判定をしているので、厳密性が求められる時には、toStrictEqual(value)を使うことをおすすめします。

toEqualとtoStrictEqualを用いたテストコード

toEqual(value)とtoStrictEqual(value)を用いたテストコードを以下に示します。

test('toEqualとtoStrictEqualのテスト', () => {
    const obj = { key: 'value' };
    const anotherObj = { key: 'value' };

    const arr = [1, 2, 3];
    const anotherArr = [1, 2, 3];

    // 同じ値だが、参照先が異なる場合でも判定可能!!
    expect(obj).toEqual(anotherObj);
    expect(obj).toEqual({ key: 'value' });
    expect(obj).toEqual({ ...obj });
    expect(arr).toEqual(anotherArr);
    expect(arr).toEqual([1, 2, 3]);

    expect(obj).toStrictEqual(anotherObj);
    expect(obj).toStrictEqual({ key: 'value' });
    expect(obj).toStrictEqual({ ...obj });
    expect(arr).toStrictEqual(anotherArr);
    expect(arr).toStrictEqual([1, 2, 3]);
});

test('toEqualとtoStrictEqualの違い', () => {
    const obj = { key: 'value' };
    const arr = [1, 2, 3];

    // undefinedの扱い方が異なる
    expect(obj).toEqual({ key: 'value', hoge: undefined });
    expect(obj).not.toStrictEqual({ key: 'value', hoge: undefined });
    expect(arr).toEqual([1, 2, 3, undefined]);
    expect(arr).not.toStrictEqual([1, 2, 3, undefined]);

    // インスタンスの生成元クラス(ClassA)
    class ClassA {
        key = 'value';
    }

    //クラス(ClassA)をインスタンス化
    const objFromClassA = new ClassA();

    // インスタンスの生成元クラスによる判定が異なる
    expect(obj).toEqual(objFromClassA);
    expect(obj).not.toStrictEqual(objFromClassA);
});

toBeTruthyとtoBeFalsy

toBeTruthy()とtoBeFalsy()はJavaScriptのtruthy(真値)とfalsy(偽値)の判定に使用するMatcherです。

falsy(フォルシー)はfalseと見なされる値です。「false, 0, +0, -0, 0n, 空文字(“”or‘’), null, undefined, NaN」がfalsyと定義されています。

一方、truthy(トゥルーシー)はtrueと見なされる値です。falsyとして定義された値以外がtruthyになります。

toBeTruthy()とtoBeFalsy()はboolean型の値判定ではありません。厳密にboolean型のtrueとfalseを判定したい場合には、toBe(true)とtoBe(false)を使用しましょう。

toBeTruthyとtoBeFalsyを用いたテストコード

toBeTruthy()とtoBeFalsy()を用いたテストコードを以下に示します。

test('toBeTruthyとtoBeFalsyのテスト', () => {
    expect(true).toBeTruthy();      //trueはtruthy
    expect(false).toBeFalsy();      //falseはfalsy

    //falsyとして定義されている値
    expect(0).toBeFalsy();
    expect(-0).toBeFalsy();
    expect(+0).toBeFalsy();
    expect(0n).toBeFalsy();
    expect("").toBeFalsy();
    expect('').toBeFalsy();
    expect(null).toBeFalsy();
    expect(undefined).toBeFalsy();
    expect(NaN).toBeFalsy();

    //Falsyとして定義された値以外はtruthy
    expect(1).toBeTruthy();             //0以外の数字はtruthy
    expect('hoge').toBeTruthy();        //空文字以外はtruthy
    expect({}).toBeTruthy();            //オブジェクトはtruthy
    expect([]).toBeTruthy();            //配列はtruthy
});

toBeNull

toBeNull()はnullの判定に使用するMatcherです。

toBe(null)でも同じように判定することができますが、toBeNull()を用いた方が、テストが失敗した時のメッセージが分かりやすいです。

toBeNullを用いたテストコード

toBeNull()を用いたテストコードを以下に示します。

test('toBeNullのテスト', () => {
    expect(null).toBeNull();
    expect('hoge').not.toBeNull();        //文字列はnullではない
    expect(undefined).not.toBeNull();     //undefinedはnullではない
    expect(NaN).not.toBeNull();           //NaNはnullではない
});

toBeNullを用いたテストコード(テストが失敗した時)

toBeNull()の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toBeNullのテスト(テストが失敗した場合)', () => {
    expect('hoge').toBeNull();     //文字列はnullではないがnullであるかをテストしている
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toBeNullのテスト(テストが失敗した場合) (3 ms)

  ● toBeNullのテスト(テストが失敗した場合)

    expect(received).toBeNull()

    Received: "hoge"

      110 |
      111 | test('toBeNullのテスト(テストが失敗した場合)', () => {
    > 112 |     expect('hoge').toBeNull();     //文字列はnullではないがnullであるかをテストしている
          |                    ^
      113 | });

      at Object.toBeNull (matcher.test.js:112:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.502 s, estimated 1 s
Ran all test suites.

toBe(null)の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toBeのテスト(テストが失敗した場合)', () => {
    expect('hoge').toBe(null);     //文字列はnullではないがnullであるかをテストしている
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toBeのテスト(テストが失敗した場合) (4 ms)

  ● toBeのテスト(テストが失敗した場合)

    expect(received).toBe(expected) // Object.is equality

    Expected: null
    Received: "hoge"

      110 |
      111 | test('toBeのテスト(テストが失敗した場合)', () => {
    > 112 |     expect('hoge').toBe(null);     //文字列はnullではないがnullであるかをテストしている
          |                    ^
      113 | });

      at Object.toBe (matcher.test.js:112:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.626 s
Ran all test suites.

toBeUndefinedとtoBeDefined

toBeUndefined()はundefinedの判定に使用するMatcherです。一方、toBeDefined()はtoBeUndefined()の反対です。

言い換えると、toBeUndefined()はnot.toBeDefined()と同じです。同様に、toBeDefined()はnot.toBeUndefined()と同じです。

toBe(undefined)でも同じように判定することができますが、toBeUndefined()を用いた方が、テストが失敗した時のメッセージが分かりやすいです。

toBeUndefinedとtoBeDefinedを用いたテストコード

toBeUndefined()とtoBeDefined()を用いたテストコードを以下に示します。

test('toBeUndefinedとtoBeDefinedのテスト', () => {
    expect(undefined).toBeUndefined();
    expect(undefined).not.toBeDefined();

    // 文字列はundefinedではない
    expect('hoge').not.toBeUndefined();
    expect('hoge').toBeDefined();

    // nullはundefinedではない
    expect(null).not.toBeUndefined();
    expect(null).toBeDefined();

    // NaNはundefinedではない
    expect(NaN).not.toBeUndefined();
    expect(NaN).toBeDefined();
});

toBeUndefinedを用いたテストコード(テストが失敗した時)

toBeUndefined()の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toBeUndefinedのテスト(テストが失敗した場合)', () => {
    expect('hoge').toBeUndefined();     //文字列はundefinedではないがundefinedであるかをテストしている
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toBeUndefinedのテスト(テストが失敗した場合) (2 ms)

  ● toBeUndefinedのテスト(テストが失敗した場合)

    expect(received).toBeUndefined()

    Received: "hoge"

      126 |
      127 | test('toBeUndefinedのテスト(テストが失敗した場合)', () => {
    > 128 |     expect('hoge').toBeUndefined();     //文字列はundefinedではないがundefinedであるかをテストしている
          |                    ^
      129 | });

      at Object.toBeUndefined (matcher.test.js:128:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.47 s, estimated 1 s
Ran all test suites.

toBe(undefined)の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toBeのテスト(テストが失敗した場合)', () => {
    expect('hoge').toBe(undefined);     //文字列はundefinedではないがundefinedであるかをテストしている
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toBeのテスト(テストが失敗した場合) (4 ms)

  ● toBeのテスト(テストが失敗した場合)

    expect(received).toBe(expected) // Object.is equality

    Expected: undefined
    Received: "hoge"

      126 |
      127 | test('toBeのテスト(テストが失敗した場合)', () => {
    > 128 |     expect('hoge').toBe(undefined);     //文字列はundefinedではないがundefinedであるかをテストしている
          |                    ^
      129 | });

      at Object.toBe (matcher.test.js:128:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.475 s, estimated 1 s
Ran all test suites.

toBeNaN

toBeNaN()はNaNの判定に使用するMatcherです。

toBe(NaN)でも同じように判定することができますが、toBeNaN()を用いた方が、テストが失敗した時のメッセージが分かりやすいです。

toBeNaNを用いたテストコード

toBeNaN()を用いたテストコードを以下に示します。

test('toBeNaNのテスト', () => {
    expect(NaN).toBeNaN();
    expect('hoge').not.toBeNaN();        //文字列はNaNではない
    expect(undefined).not.toBeNaN();     //undefinedはNaNではない
    expect(null).not.toBeNaN();          //NaNはNaNではない
});

toBeNaNを用いたテストコード(テストが失敗した時)

toBeNaN()の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toBeNaNのテスト(テストが失敗した場合)', () => {
    expect('hoge').toBeNaN();     //文字列はNaNではないがNaNであるかをテストしている
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toBeNaNのテスト(テストが失敗した場合) (2 ms)

  ● toBeNaNのテスト(テストが失敗した場合)

    expect(received).toBeNaN()

    Received: "hoge"

      133 |
      134 | test('toBeNaNのテスト(テストが失敗した場合)', () => {
    > 135 |     expect('hoge').toBeNaN();     //文字列はNaNではないがNaNであるかをテストしている
          |                    ^
      136 | });
      137 |

      at Object.toBeNaN (matcher.test.js:135:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.473 s, estimated 1 s
Ran all test suites.

toBe(NaN)の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toBeのテスト(テストが失敗した場合)', () => {
    expect('hoge').toBe(NaN);     //文字列はNaNではないがNaNであるかをテストしている
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toBeのテスト(テストが失敗した場合) (3 ms)

  ● toBeのテスト(テストが失敗した場合)

    expect(received).toBe(expected) // Object.is equality

    Expected: NaN
    Received: "hoge"

      133 |
      134 | test('toBeのテスト(テストが失敗した場合)', () => {
    > 135 |     expect('hoge').toBe(NaN);     //文字列はNaNではないがNaNであるかをテストしている
          |                    ^
      136 | });
      137 |

      at Object.toBe (matcher.test.js:135:20)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.482 s, estimated 1 s
Ran all test suites.

toMatch

toMatch(regexp | string)は文字列に対して正規表現でマッチするかを判定するMatcherです。toMatch(regexp | string)は正規表現(regexp)だけでなく、文字列(string)も引数に指定可能です。

toMatchを用いたテストコード

toMatch(regexp | string)を用いたテストコードを以下に示します。

test('toMatchのテスト', () => {
    expect('HogeHoge Test').toMatch(/Hoge/);        //文字列「HogeHoge Test」に「Hoge」が含まれているか
    expect('HogeHoge Test').not.toMatch(/Foo/);     //文字列「HogeHoge Test」に「Foo」が含まれていないか
    expect('HogeHoge Test').toMatch('Hoge');        //文字列「HogeHoge Test」に「Hoge」が含まれているか
    expect('HogeHoge Test').not.toMatch('Foo');     //文字列「HogeHoge Test」に「Foo」が含まれていないか
});

toHaveLength

toHaveLength(number)は配列や文字列の長さがnumberかを判定するMatcherです。

lengthプロパティを使っても判定できますが、toHaveLength(number)を使った方が読みやすいです。

toHaveLengthを用いたテストコード

toHaveLength(number)を用いたテストコードを以下に示します。

test('toHaveLengthのテスト', () => {
    const arr = [1, 2, 3];
    const str = 'hoge';

    // arrの長さは「3」か
    expect(arr).toHaveLength(3);
    expect(arr.length).toBe(3);

    // strの長さは「4」か
    expect(str).toHaveLength(4);
    expect(str.length).toBe(4);
});

toContainとtoContainEqual

toContain(item)とtoContainEqual(item)は配列に特定の要素が含まれているかを判定するMatcherです。

toContainとtoContainEqualの違い

toContainEqual(item)はtoContain(item)と異なり、参照先が異なっていても判定が可能です。

toContainとtoContainEqualを用いたテストコード

toContain(item)とtoContainEqual(item)を用いたテストコードを以下に示します。

test('toContainとtoContainEqualのテスト', () => {
    const obj = { key: 'value' };
    const arr = [obj, { hoge: 'foo' }];

    // 同じ参照先の場合
    expect(arr).toContain(obj);                     //配列arrにobjが含まれているか
    expect(arr).toContainEqual(obj);                //配列arrにobjが含まれているか

    // 同じ値だが、参照先が異なる場合
    expect(arr).not.toContain({ key: 'value' });    //配列arrに{ key: 'value' }が含まれているか
    expect(arr).toContainEqual({ key: 'value' });   //配列arrに{ key: 'value' }が含まれているか
});

toHaveProperty

toHaveProperty(keyPath[, value])はオブジェクトにkeyPathのプロパティが含まれているかを判定するMatcherです。オプション引数にvalueを指定すると、受け取ったプロパティの値も判定することができるようになります。

toEqual(value)でも同じように判定することができますが、toHaveProperty(keyPath[, value])を用いた方が、テストが失敗した時のメッセージが分かりやすいです。

toHavePropertyを用いたテストコード

toHaveProperty(keyPath[, value])を用いたテストコードを以下に示します。

test('toHavePropertyのテスト', () => {
    const obj = { key: 'value' };

    expect(obj).toHaveProperty('key');           //オブジェクトobjのプロパティにkeyが含まれているか
    expect(obj).toHaveProperty('key', 'value');  //オブジェクトobjのプロパティにkeyが含まれていて、その値は'value'であるか
});

toHavePropertyを用いたテストコード(テストが失敗した時)

toHaveProperty(keyPath[, value])の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toHavePropertyのテスト(テストが失敗した場合)', () => {
    const obj = { key: 'value' };

    expect(obj).toHaveProperty('key', 'hoge');          //オブジェクトobjのプロパティにkeyが含まれていて、その値は'hoge'であるか
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toHavePropertyのテスト(テストが失敗した場合) (5 ms)

  ● toHavePropertyのテスト(テストが失敗した場合)

    expect(received).toHaveProperty(path, value)

    Expected path: "key"

    Expected value: "hoge"
    Received value: "value"

      176 |     const obj = { key: 'value' };
      177 |
    > 178 |     expect(obj).toHaveProperty('key', 'hoge');          //オブジェクトobjのプロパティにkeyが含まれていて、その値は'hoge'であるか
          |                 ^
      179 | });

      at Object.toHaveProperty (matcher.test.js:178:17)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.471 s, estimated 1 s
Ran all test suites.

toEqual(value)の場合

テストコードを以下のように書いて、テストを失敗させます。

test('toEqualのテスト(テストが失敗した場合)', () => {
    const obj = { key: 'value' };

    expect(obj.key).toEqual('hoge');          //オブジェクトobjのプロパティkeyの値は'hoge'であるか
});

実行結果は以下の様になります。

PS C:\Users\user01\Desktop\matcherTest> npm test

> jesttest@1.0.0 test
> jest

 FAIL  ./matcher.test.js
  × toEqualのテスト(テストが失敗した場合) (5 ms)

  ● toEqualのテスト(テストが失敗した場合)

    expect(received).toEqual(expected) // deep equality

    Expected: "hoge"
    Received: "value"

      176 |     const obj = { key: 'value' };
      177 |
    > 178 |     expect(obj.key).toEqual('hoge');          //オブジェクトobjのプロパティkeyの値は'hoge'であるか
          |                     ^
      179 | });

      at Object.toEqual (matcher.test.js:178:21)

Test Suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Snapshots:   0 total
Time:        0.48 s, estimated 1 s
Ran all test suites.

toBeGreaterThanとtoBeGreaterThanOrEqual

toBeGreaterThan(number)はnumberより大きいかを判定するMatcherです。「～より大きい」なので、「number」は含まれません。

toBeGreaterThanOrEqual(number)はnumber以上かを判定するMatcherです。「～以上」なので、「number」の数は含まれます。

toBeGreaterThanとtoBeGreaterThanOrEqualを用いたテストコード

toBeGreaterThan(number)とtoBeGreaterThanOrEqual(number)を用いたテストコードを以下に示します。

test('toBeGreaterThanとtoBeGreaterThanOrEqualのテスト', () => {
    const value = 12;

    expect(value).toBeGreaterThan(10);          //「12」は「10」よりも大きいか
    expect(value).not.toBeGreaterThan(12);      //「12」は「12」よりも大きくないか

    expect(value).toBeGreaterThanOrEqual(10);   //「12」は「10」以上か
    expect(value).toBeGreaterThanOrEqual(12);   //「12」は「12」以上か
});

toBeLessThanとtoBeLessThanOrEqual

toBeLessThan(number)はnumberより小さいかを判定するMatcherです。「～より小さい」なので、「number」は含まれません。

toBeLessThanOrEqual(number)はnumber以下かを判定するMatcherです。「～以下」なので、「number」の数は含まれます。

toBeLessThanとtoBeLessThanOrEqualを用いたテストコード

toBeLessThan(number)とtoBeLessThanOrEqual(number)を用いたテストコードを以下に示します。

test('toBeLessThanとtoBeLessThanOrEqualのテスト', () => {
    const value = 12;

    expect(value).toBeLessThan(15);          //「12」は「15」よりも小さいか
    expect(value).not.toBeLessThan(12);      //「12」は「12」よりも小さくないか

    expect(value).toBeLessThanOrEqual(15);   //「12」は「15」以下か
    expect(value).toBeLessThanOrEqual(12);   //「12」は「12」以下か
});

toBeCloseTo

toBeCloseTo(number[, numDigits])は浮動小数点の値が同一であるかを判定するMatcherです。

オプションのnumDigitsは小数点以下のチェックする桁数を指定します。指定しなければ、デフォルト値の「2」となります。

toBeCloseToを用いたテストコード

toBeCloseTo(number[, numDigits])を用いたテストコードを以下に示します。

test('toBeCloseToのテスト', () => {
    const value = 0.1 + 0.2;

    expect(value).not.toBe(0.3);               //丸め誤差が原因で期待通りに動作しない
    expect(value).toBeCloseTo(0.3);            //valueと0.3を比較して、2桁(デフォルト)の制度まで等しいとテスト合格
    expect(value).toBeCloseTo(0.3, 5);         //valueと0.3を比較して、5桁の制度まで等しいとテスト合格
});

JavaScriptでは0.2+0.1は0.30000000000000004なので、toBe(value)で比較するとテストが失敗します。

toThrowとtoThrowError

toThrow([error])とtoThrowError([error])はどちらも例外が発生したかを判定するMatcherです。

引数を省略すると、例外が発生したかのみを判定します。引数には「例外の型」、「エラーメッセージ」、「Errorオブジェクト」などを指定することができます。

toThrowとtoThrowErrorを用いたテストコード

toThrow([error])とtoThrowError([error])を用いたテストコードを以下に示します。

class CustomError extends Error { }
function throwCustomError() {
    throw new CustomError('エラーが発生しました')
}

test('toThrowとtoThrowErrorのテスト', () => {
    // 例外が発生したかのみを判定
    // どの書き方でもOK
    expect(throwCustomError).toThrow();
    expect(throwCustomError).toThrowError();
    expect(() => throwCustomError()).toThrow();
    expect(() => throwCustomError()).toThrowError();

    // 例外の型を判定(引数に「例外の型」を指定)
    // どの書き方でもOK
    expect(throwCustomError).toThrow(CustomError);
    expect(throwCustomError).toThrowError(CustomError);
    expect(() => throwCustomError()).toThrow(CustomError);
    expect(() => throwCustomError()).toThrowError(CustomError);

    // エラーメッセージの判定(引数に「エラーメッセージ」や「Errorオブジェクト」を指定)
    // どの書き方でもOK
    expect(throwCustomError).toThrow('エラーが発生しました');
    expect(throwCustomError).toThrowError('エラーが発生しました');
    expect(throwCustomError).toThrow(new CustomError('エラーが発生しました'));
    expect(throwCustomError).toThrowError(new CustomError('エラーが発生しました'));
    expect(() => throwCustomError()).toThrow('エラーが発生しました');
    expect(() => throwCustomError()).toThrowError('エラーが発生しました');
    expect(() => throwCustomError()).toThrow(new CustomError('エラーが発生しました'));
    expect(() => throwCustomError()).toThrowError(new CustomError('エラーが発生しました'));

    // エラーメッセージのどこかで「エラー」と書かれているかを判定
    // どの書き方でもOK
    expect(throwCustomError).toThrow(/エラー/);
    expect(throwCustomError).toThrowError(/エラー/);
    expect(throwCustomError).toThrow('エラー');
    expect(throwCustomError).toThrowError('エラー');
    expect(() => throwCustomError()).toThrow(/エラー/);
    expect(() => throwCustomError()).toThrowError(/エラー/);
    expect(() => throwCustomError()).toThrow('エラー');
    expect(() => throwCustomError()).toThrowError('エラー');
});

本記事のまとめ

この記事では『Matcher(マッチャー)』について、以下の内容を説明しました。

  • Matcher(マッチャー)とは
  • Matcher(マッチャー)の種類
  • 各Matcherの特徴

お読み頂きありがとうございました。