Using Matchers

Jest では、マッチャー ("matcher") を使用して、様々な方法で値のテストをすることができます。このドキュメントでは、よく使われるマッチャーをいくつか紹介します。マッチャーの完全なリストについては、expect API ドキュメントをご覧ください。

一般的なマッチャー

値をテストする最も簡単な方法は、厳密に等価であることです。

test('two plus two is four', () => {
  expect(2 + 2).toBe(4);
});

このコードでは、expect(2 + 2) は "expectation" オブジェクトを返します。マッチャーを利用しなければこれらの "expectation" オブジェクトは大きな効果を発揮しません。このコードでは、 .toBe(4) はマッチャーです。 Jestが実行されると、失敗したマッチャーをすべて追跡し、素晴らしいエラーメッセージを表示することができます。

toBe は Object.is を使用して厳密な等価性をテストします。オブジェクトの値を確認する場合は、代わりに toEqual を使用します。

test('object assignment', () => {
  const data = {one: 1};
  data['two'] = 2;
  expect(data).toEqual({one: 1, two: 2});
});

toEqual は、オブジェクトまたは配列のすべてのフィールドを再帰的にチェックします。

また、マッチャーとは反対のテストをすることもできます:

test('adding positive numbers is not zero', () => {
  for (let a = 1; a < 10; a++) {
    for (let b = 1; b < 10; b++) {
      expect(a + b).not.toBe(0);
    }
  }
});

真偽値(およびそれらしく思える値)

テストにおいて、undefined, null, false の区別が必要な場合がありますが、時にはそれらを異なるものとして扱いたくないこともあります。 Jestには、(それらのケースで) 求められるものを明確に実装したヘルパーが備わっています。

toBeNull は null のみ一致します
toBeUndefined は undefined のみ一致します
toBeDefined は toBeUndefined の反対です
toBeTruthy は if ステートメントが真であるとみなすものに一致します
toBeFalsy は if ステートメントが偽であるとみなすものに一致します

例：

test('null', () => {
  const n = null;
  expect(n).toBeNull();
  expect(n).toBeDefined();
  expect(n).not.toBeUndefined();
  expect(n).not.toBeTruthy();
  expect(n).toBeFalsy();
});

test('zero', () => {
  const z = 0;
  expect(z).not.toBeNull();
  expect(z).toBeDefined();
  expect(z).not.toBeUndefined();
  expect(z).not.toBeTruthy();
  expect(z).toBeFalsy();
});

あなたは、あなたのコードがしたいことに最も正確に対応するマッチャーを使うべきです。

数値

数値の比較するほとんどの方法について、対応するマッチャーがあります。

test('two plus two', () => {
  const value = 2 + 2;
  expect(value).toBeGreaterThan(3);
  expect(value).toBeGreaterThanOrEqual(3.5);
  expect(value).toBeLessThan(5);
  expect(value).toBeLessThanOrEqual(4.5);

  // toBe and toEqual are equivalent for numbers
  expect(value).toBe(4);
  expect(value).toEqual(4);
});

わずかな丸め誤差にテストを依存させたくないでしょうから、浮動小数点の値が同一であるかを確認するにはtoEqualの代わりにtoBeCloseTo を使用して下さい。

test('adding floating point numbers', () => {
  const value = 0.1 + 0.2;
  //expect(value).toBe(0.3);         このように書くと、丸め込み誤差が原因で期待通りに動作しない
  expect(value).toBeCloseTo(0.3); // これならば正しく動く
});

文字列

toMatch で、文字列に対して正規表現でマッチするか確認できます。

test('there is no I in team', () => {
  expect('team').not.toMatch(/I/);
});

test('but there is a "stop" in Christoph', () => {
  expect('Christoph').toMatch(/stop/);
});

配列と反復可能なオブジェクト

toContain を使用して、配列や反復可能なオブジェクトに特定のアイテムが含まれているかどうかを確認できます。

const shoppingList = [
  'diapers',
  'kleenex',
  'trash bags',
  'paper towels',
  'milk',
];

test('the shopping list has milk on it', () => {
  expect(shoppingList).toContain('milk');
  expect(new Set(shoppingList)).toContain('milk');
});

例外

ある関数が呼び出し時に例外を投げることをテストするには、 toThrow を使用します。

function compileAndroidCode() {
  throw new Error('you are using the wrong JDK');
}

test('compiling android goes as expected', () => {
  expect(() => compileAndroidCode()).toThrow();
  expect(() => compileAndroidCode()).toThrow(Error);

  // You can also use the exact error message or a regexp
  expect(() => compileAndroidCode()).toThrow('you are using the wrong JDK');
  expect(() => compileAndroidCode()).toThrow(/JDK/);
});

注意: 例外をスローする関数は、ラッピング関数内で呼び出される必要があります。そうでなければ、 toThrow アサーションは失敗します。

その他

これはほんの一部です。マッチャーの完全なリストについては、リファレンスドキュメントを確認してください。

利用可能なマッチャーについて学んだら、次のステップは Jest で非同期コードをテストを確認することです。