Expect · Jest

テストを作成する時に、値が特定の条件に合致することを確認する必要がよくあるでしょう。 expect によって様々な事柄を検証するための数多くの"マッチャ"を利用することができます。

メソッド

<autogenerated_table_of_contents>

リファレンス

`expect(value)`

expect は値をテストしたい時に毎回使用する関数です。 expect のみを呼び出すということはほとんどありません。代わりに、値について何らかの事をアサートする"マッチャ"関数とともにexpect を使用することでしょう。

この事は例を見れば簡単に理解できます。 'grapefruit'という文字列を返すはずのbestLaCroixFlavor()メソッドがあるとしましょう。以下のようにテストするでしょう:

test('the best flavor is grapefruit', () => {
  expect(bestLaCroixFlavor()).toBe('grapefruit');
});

このケースでは、 toBeがマッチャ関数です。様々な事をテストするのを手助けする数多くの異なるマッチャ関数があり、以下にまとめられています。

expectへの引数はコードが生成する値であるべきであり、いかなるマッチャへの引数は正解の値であるべきです。それらを混同して使用すれば、テストは動作するものの、失敗したテストから出力されるエラーメッセージはおかしなものになります。

`expect.extend(matchers)`

Jestに独自のマッチャを追加したい場合は expect.extendを使用します。例えば、整数論のライブラリをテストしていて、数字が他の数字によって割り切れることを頻繁にアサートしているとしましょう。それをtoBeDivisibleByマッチャに抽象化することができます:

expect.extend({
  toBeDivisibleBy(received, argument) {
    const pass = received % argument == 0;
    if (pass) {
      return {
        message: () =>
          `expected ${received} not to be divisible by ${argument}`,
        pass: true,
      };
    } else {
      return {
        message: () => `expected ${received} to be divisible by ${argument}`,
        pass: false,
      };
    }
  },
});

test('even and odd numbers', () => {
  expect(100).toBeDivisibleBy(2);
  expect(101).not.toBeDivisibleBy(2);
  expect({apples: 6, bananas: 3}).toEqual({
    apples: expect.toBeDivisibleBy(2),
    bananas: expect.not.toBeDivisibleBy(2),
  });
});

expect.extends also supports async matchers. Async matchers return a Promise so you will need to await the returned value. Let's use an example matcher to illustrate the usage of them. We are going to implement a very similar matcher than toBeDivisibleBy, only difference is that the divisible number is going to be pulled from an external source.

expect.extend({
  async toBeDivisibleByExternalValue(received) {
    const externalValue = await getExternalValueFromRemoteSource();
    const pass = received % externalValue == 0;
    if (pass) {
      return {
        message: () =>
          `expected ${received} not to be divisible by ${externalValue}`,
        pass: true,
      };
    } else {
      return {
        message: () =>
          `expected ${received} to be divisible by ${externalValue}`,
        pass: false,
      };
    }
  },
});

test('is divisible by external value', async () => {
  await expect(100).toBeDivisibleByExternalValue();
  await expect(101).not.toBeDivisibleByExternalValue();
});

Matchers should return an object (or a Promise of an object) with two keys. passキーはマッチャの条件に合致するかどうかを示し、 messageキーは失敗した場合にエラーメッセージを返す引数なしの関数を提供します。したがって、passが偽なら、 messageはexpect(x).yourMatcher()が失敗した場合のエラーメッセージを返す必要があります。 passが真だった場合、 messageはexpect(x).not.yourMatcher()が失敗した場合のエラーメッセージを返す必要があります。

これらのヘルパー関数は独自マッチャのthis内で確認することができます。

`this.isNot`

マッチャがアサーションを反転させる否定の修飾子 .notを付けて呼ばれたかどうかを示す真偽値です。

`this.equals(a, b)`

２つのオブジェクトが同じ値を(再帰的に) 持つ場合に trueを返す深い等価関数です。

`this.utils`

jest-matcher-utilsからexportされたもので主に構成されるthis.utilsから利用できる多数の便利なツールがあります。

最も有用なものにエラーメッセージを見やすくフォーマットする matcherHint、 printExpected そしてprintReceivedがあります。例えば、 toBe マッチャの実装を見てみましょう:

const diff = require('jest-diff');
expect.extend({
  toBe(received, expected) {
    const pass = Object.is(received, expected);

    const message = pass
      ? () =>
          this.utils.matcherHint('.not.toBe') +
          '\n\n' +
          `Expected value to not be (using Object.is):\n` +
          `  ${this.utils.printExpected(expected)}\n` +
          `Received:\n` +
          `  ${this.utils.printReceived(received)}`
      : () => {
          const diffString = diff(expected, received, {
            expand: this.expand,
          });
          return (
            this.utils.matcherHint('.toBe') +
            '\n\n' +
            `Expected value to be (using Object.is):\n` +
            `  ${this.utils.printExpected(expected)}\n` +
            `Received:\n` +
            `  ${this.utils.printReceived(received)}` +
            (diffString ? `\n\nDifference:\n\n${diffString}` : '')
          );
        };

    return {actual: received, message, pass};
  },
});

上記のコードはこのような出力をします:

  expect(received).toBe(expected)

    Expected value to be (using Object.is):
      "banana"
    Received:
      "apple"

アサーションに失敗した場合、エラーメッセージは利用者がその問題を迅速に解決できるようになるべく多くのシグナルを与えるものであるべきです。独自アサーションの利用者が良い開発体験を得られるよう正確なエラーメッセージを作成する必要があります。

`expect.anything()`

expect.anything() は、null または undefined を除くものすべてに一致します。 toEqual または toBeCalledWith の内側でリテラル値の代わりに使用できます。例えば、モック関数がnullでない引数を与えられて呼び出されたことを確認するには:

test('map calls its argument with a non-null argument', () => {
  const mock = jest.fn();
  [1].map(x => mock(x));
  expect(mock).toBeCalledWith(expect.anything());
});

`expect.any(constructor)`

expect.any(constructor) は与えられたコンストラクタで生成されたもの全てに一致します。 toEqual または toBeCalledWith の内側でリテラル値の代わりに使用できます。例えば、モック関数が数字の引数を与えられて呼び出されたことを確認するには:

function randocall(fn) {
  return fn(Math.floor(Math.random() * 6 + 1));
}

test('randocall calls its callback with a number', () => {
  const mock = jest.fn();
  randocall(mock);
  expect(mock).toBeCalledWith(expect.any(Number));
});

`expect.arrayContaining(array)`

expect.arrayContaining(array) は受け取った配列が期待される配列の要素全てを含む場合に一致します。つまり受け取った配列は期待される配列を包含するということです。したがって受け取る配列が期待される配列に含まれない要素を含んでいても一致します。

以下のケースでリテラル値の代わりに使用できます:

toEqual または toBeCalledWithの中
objectContaining または toMatchObjectのプロパティとマッチさせる場合

describe('arrayContaining', () => {
  const expected = ['Alice', 'Bob'];
  it('matches even if received contains additional elements', () => {
    expect(['Alice', 'Bob', 'Eve']).toEqual(expect.arrayContaining(expected));
  });
  it('does not match if received does not contain expected elements', () => {
    expect(['Bob', 'Eve']).not.toEqual(expect.arrayContaining(expected));
  });
});

describe('Beware of a misunderstanding! A sequence of dice rolls', () => {
  const expected = [1, 2, 3, 4, 5, 6];
  it('matches even with an unexpected number 7', () => {
    expect([4, 1, 6, 7, 3, 5, 2, 5, 4, 6]).toEqual(
      expect.arrayContaining(expected),
    );
  });
  it('does not match without an expected number 2', () => {
    expect([4, 1, 6, 7, 3, 5, 7, 5, 4, 6]).not.toEqual(
      expect.arrayContaining(expected),
    );
  });
});

`expect.assertions(number)`

expect.assertions(number) はテスト中に特定の数だけアサーションが呼び出されたことを確認します。非同期のコードをテストにおいて、コールバック中のアサーションが実際に呼ばれたことを確認する際にしばしば便利です。

例えば、 callback1 と callback2の２つのコールバックを受けとるdoAsync関数があったとしたら、その関数は未知の順序で両方を呼び出します。以下のコードでテストできます:

test('doAsync calls both callbacks', () => {
  expect.assertions(2);
  function callback1(data) {
    expect(data).toBeTruthy();
  }
  function callback2(data) {
    expect(data).toBeTruthy();
  }

  doAsync(callback1, callback2);
});

expect.assertions(2)を呼び出すことで両方のコールバックが実際に呼ばれたことを確認できます。

`expect.hasAssertions()`

expect.hasAssertions()はテスト中で少なくとも1回はアサーションが呼び出されたことを確認します。非同期のコードをテストにおいて、コールバック中のアサーションが実際に呼ばれたことを確認する際にしばしば便利です。

例えば状態を取り扱ういくつかの関数があったとしましょう。 prepareState は状態オブジェクトとともにコールバックを呼び出し、validateState はその状態オブジェクトを確認し、 waitOnStateはprepareState のコールバックが完了するまで待つpromiseを返します。以下のコードでテストできます:

est('prepareState prepares a valid state', () => {
  expect.hasAssertions();
  prepareState(state => {
    expect(validateState(state)).toBeTruthy();
  });
  return waitOnState();
});

expect.hasAssertions()は prepareStateのコールバックが実際に呼ばれたことを確認します。

`expect.not.arrayContaining(array)`

expect.not.arrayContaining(array) matches a received array which contains none of the elements in the expected array. That is, the expected array is not a subset of the received array.

これは expect.arrayContaining の逆です。

describe('not.arrayContaining', () => {
  const expected = ['Samantha'];

  it('matches if the actual array does not contain the expected elements', () => {
    expect(['Alice', 'Bob', 'Eve']).toEqual(
      expect.not.arrayContaining(expected),
    );
  });
});

`expect.not.objectContaining(object)`

expect.not.objectContaining(object) matches any received object that does not recursively match the expected properties. That is, the expected object is not a subset of the received object. したがって受け取ったオブジェクトが期待されるオブジェクトに含まれないプロパティを含んでいても一致します。

これは expect.objectContaining の逆です。

describe('not.objectContaining', () => {
  const expected = {foo: 'bar'};

  it('matches if the actual object does not contain expected key: value pairs', () => {
    expect({bar: 'baz'}).toEqual(expect.not.objectContaining(expected));
  });
});

`expect.not.stringContaining(string)`

expect.not.stringContaining(string) matches the received string that does not contain the exact expected string.

これは expect.stringContaining の逆です。

describe('not.stringContaining', () => {
  const expected = 'Hello world!';

  it('matches if the actual string does not contain the expected substring', () => {
    expect('How are you?').toEqual(expect.not.stringContaining(expected));
  });
});

`expect.not.stringMatching(string | regexp)`

expect.not.stringMatching(string | regexp) matches the received string that does not match the expected regexp.

これは expect.stringMatching の逆です。

describe('not.stringMatching', () => {
  const expected = /Hello world!/;

  it('matches if the actual string does not match the expected regex', () => {
    expect('How are you?').toEqual(expect.not.stringMatching(expected));
  });
});

`expect.objectContaining(object)`

expect.objectContaining(object) は期待されたプロパティに再帰的に一致する、いかなる受け取ったオブジェクトにも一致します。つまり期待されるオブジェクトは受け取ったオブジェクトの 一部分 であるということです。したがって受け取ったオブジェクトが期待されるオブジェクトに含まれないプロパティを含んでいても一致します。

期待されるオブジェクトのプロパティにリテラル値を設定する代わりに、expect.anything()などのマッチャを使用することができます。

例えば、onPress関数がEvent オブジェクトと共に呼ばれ、eventが event.x とevent.y プロパティを持っていることだけ確認できれば良いと考えましょう。以下のようにできます:

test('onPress gets called with the right thing', () => {
  const onPress = jest.fn();
  simulatePresses(onPress);
  expect(onPress).toBeCalledWith(
    expect.objectContaining({
      x: expect.any(Number),
      y: expect.any(Number),
    }),
  );
});

`expect.stringContaining(string)`

expect.stringContaining(string) matches the received string that contains the exact expected string.

`expect.stringMatching(string | regexp)`

expect.stringMatching(string | regexp) matches the received string that matches the expected regexp.

以下のケースでリテラル値の代わりに使用できます:

toEqual または toBeCalledWithの中
arrayContainingの要素とマッチさせる場合
objectContaining または toMatchObjectのプロパティとマッチさせる場合

この例ではexpect.arrayContaining内のexpect.stringMatching によって、複数の非対称なマッチャをネストする方法も示します。

describe('stringMatching in arrayContaining', () => {
  const expected = [
    expect.stringMatching(/^Alic/),
    expect.stringMatching(/^[BR]ob/),
  ];
  it('matches even if received contains additional elements', () => {
    expect(['Alicia', 'Roberto', 'Evelina']).toEqual(
      expect.arrayContaining(expected),
    );
  });
  it('does not match if received does not contain expected elements', () => {
    expect(['Roberto', 'Evelina']).not.toEqual(
      expect.arrayContaining(expected),
    );
  });
});

`expect.addSnapshotSerializer(serializer)`

expect.addSnapshotSerializerを使用して、アプリケーション独自のデータ構造をフォーマットするモジュールを追加することができます。

個々のテストファイルにおいては、JavaScriptに組み込みの型やReactの要素のデフォルトのスナップショットのシリアライザよりもsnapshotSerializers設定で追加されたモジュールが優先され、それらの全てのモジュールより(このAPIで) 追加されたモジュールは優先されます。最後に追加されたモジュールが最初に確認されるモジュールになります。

import serializer from 'my-serializer-module';
expect.addSnapshotSerializer(serializer);

// affects expect(value).toMatchSnapshot() assertions in the test file

snapshotSerializers 設定で追加するのではなく、個々のテストファイルでスナップショットのシリアライザをつい以下する場合は:

依存関係を暗黙的でなく明示的なものにしてください。
create-react-appが利用できなくなるような設定は避けてください。

詳細については configuring Jest を参照してください。

`.not`

何かをテストする方法が分かっているなら、 .notによってその反対の事をテストできます。例えば以下のコードでは、ラクロワ飲料で一番美味しいのはココナッツ味ではないことをテストでします。

test('the best flavor is not coconut', () => {
  expect(bestLaCroixFlavor()).not.toBe('coconut');
});

`.resolves`

追加のマッチャをチェーンするためにに完了したpromiseの値を取り出すにはresolvesを使用して下さい。promiseがrejectされた場合はアサーションは失敗します。

例えば、以下のコードではpromiseが完了した結果の値が'lemon'であることをテストします:

test('resolves to lemon', () => {
  // make sure to add a return statement
  return expect(Promise.resolve('lemon')).resolves.toBe('lemon');
});

Promise をテストしているので、テストはいまだ非同期であることに注意して下さい。このために、ラップされていないアサーションを返すことで、Jest に処理が完了するまで待つように伝える必要があるのです。

また、async/await を.resolvesと組み合わせて使うことができます。

test('resolves to lemon', async () => {
  await expect(Promise.resolve('lemon')).resolves.toBe('lemon');
  await expect(Promise.resolve('lemon')).resolves.not.toBe('octopus');
});

`.rejects`

追加のマッチャをチェーンするためににrejectされたpromiseの理由を取り出すには .rejectsを使用して下さい。promiseが完了した場合はアサーションは失敗します。

例えば、このコードは Promise が理由'octopus' 付きで reject された事をテストします:

test('rejects to octopus', () => {
  // make sure to add a return statement
  return expect(Promise.reject(new Error('octopus'))).rejects.toThrow(
    'octopus',
  );
});

また、async/await を.rejectsと組み合わせて使うことができます。

test('rejects to octopus', async () => {
  await expect(Promise.reject(new Error('octopus'))).rejects.toThrow('octopus');
});

`.toBe(value)`

toBe just checks that a value is what you expect. It uses Object.is to check exact equality.

例えば以下のコードでは can オブジェクトのいくつかのプロパティを検証します。

const can = {
  name: 'pamplemousse',
  ounces: 12,
};

describe('the can', () => {
  test('has 12 ounces', () => {
    expect(can.ounces).toBe(12);
  });

  test('has a sophisticated name', () => {
    expect(can.name).toBe('pamplemousse');
  });
});

浮動小数点数に toBe を使用しないでください。例えば、JavaScriptでは数値の丸めによって0.2 + 0.1と 0.3は厳密には等価ではありません。浮動小数点がある場合は、代わりに.toBeCloseToを使用してください。

`.toHaveBeenCalled()`

次の別名でも同様となります: .toBeCalled()

モック関数が呼ばれたかを確認するには.toHaveBeenCalledを使用して下さい。

例えばdrink関数を引数に取って全ての今ある飲み物に適用するdrinkAll(drink, flavor)関数があるとしましょう。 drinkが 'lemon'味に適用されても, 'octopus'味には適用されないという事を確認したいでしょう。'octopus'味なんて奇妙であって欲しいとは思えません。このテストスイートでテストすることができます:

describe('drinkAll', () => {
  test('drinks something lemon-flavored', () => {
    const drink = jest.fn();
    drinkAll(drink, 'lemon');
    expect(drink).toHaveBeenCalled();
  });

  test('does not drink something octopus-flavored', () => {
    const drink = jest.fn();
    drinkAll(drink, 'octopus');
    expect(drink).not.toHaveBeenCalled();
  });
});

`.toHaveBeenCalledTimes(number)`

Also under the alias: .toBeCalledTimes(number)

モック関数が期待した回数だけ呼ばれたことを確認するには.toHaveBeenCalledTimes を使用して下さい。

例えばdrink関数を引数に取って渡された飲み物の配列に適用する drinkEach(drink, Array<flavor>) 関数があるとしましょう。ｄrink関数が正しい回数だけ呼ばれたことを確認したいでしょう。このテストスイートでテストすることができます:

test('drinkEach drinks each drink', () => {
  const drink = jest.fn();
  drinkEach(drink, ['lemon', 'octopus']);
  expect(drink).toHaveBeenCalledTimes(2);
});

`.toHaveBeenCalledWith(arg1, arg2, ...)`

次の別名でも同様となります: .toBeCalledWith()

モック関数が特定の引数を与えられて呼び出されたことを確認するには .toHaveBeenCalledWith を使用して下さい。

例えば register 関数で飲み物を登録でき、applyToAll(f) は関数f を全ての登録された飲み物に適用するものとしましょう。この振る舞いを確認するコードは、下記のように書けるでしょう:

test('registration applies correctly to orange La Croix', () => {
  const beverage = new LaCroix('orange');
  register(beverage);
  const f = jest.fn();
  applyToAll(f);
  expect(f).toHaveBeenCalledWith(beverage);
});

`.toHaveBeenLastCalledWith(arg1, arg2, ...)`

次の別名でも同様となります: .lastCalledWith(arg1, arg2, ...)

モック関数がある場合は .toHaveBeenLastCalledWithを使用して、最後の呼び出しがどんな引数を渡されたかをテストすることができます。例えば複数の風味に対して関数fを適用するapplyToAllFlavors(f) 関数があり、関数fが最後に操作した風味が'mango'だったとしましょう。以下のようにテストコードを書くことができます。

test('applying to all flavors does mango last', () => {
  const drink = jest.fn();
  applyToAllFlavors(drink);
  expect(drink).toHaveBeenLastCalledWith('mango');
});

`.toHaveBeenNthCalledWith(nthCall, arg1, arg2, ....)`

Also under the alias: .nthCalledWith(nthCall, arg1, arg2, ...)

If you have a mock function, you can use .toHaveBeenNthCalledWith to test what arguments it was nth called with. For example, let's say you have a drinkEach(drink, Array<flavor>) function that applies f to a bunch of flavors, and you want to ensure that when you call it, the first flavor it operates on is 'lemon' and the second one is 'octopus'. 以下のようにテストコードを書くことができます。

test('drinkEach drinks each drink', () => {
  const drink = jest.fn();
  drinkEach(drink, ['lemon', 'octopus']);
  expect(drink).toHaveBeenNthCalledWith(1, 'lemon');
  expect(drink).toHaveBeenNthCalledWith(2, 'octopus');
});

Note: the nth argument must be positive integer starting from 1.

`.toHaveReturned()`

Also under the alias: .toReturn()

If you have a mock function, you can use .toHaveReturned to test that the mock function successfully returned (i.e., did not throw an error) at least one time. For example, let's say you have a mock drink that returns true. 以下のようにテストコードを書くことができます。

test('drinks returns', () => {
  const drink = jest.fn(() => true);

  drink();

  expect(drink).toHaveReturned();
});

`.toHaveReturnedTimes(number)`

Also under the alias: .toReturnTimes(number)

Use .toHaveReturnedTimes to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times. Any calls to the mock function that throw an error are not counted toward the number of times the function returned.

For example, let's say you have a mock drink that returns true. You can write:

test('drink returns twice', () => {
  const drink = jest.fn(() => true);

  drink();
  drink();

  expect(drink).toHaveReturnedTimes(2);
});

`.toHaveReturnedWith(value)`

Also under the alias: .toReturnWith(value)

Use .toHaveReturnedWith to ensure that a mock function returned a specific value.

For example, let's say you have a mock drink that returns the name of the beverage that was consumed. You can write:

test('drink returns La Croix', () => {
  const beverage = {name: 'La Croix'};
  const drink = jest.fn(beverage => beverage.name);

  drink(beverage);

  expect(drink).toHaveReturnedWith('La Croix');
});

`.toHaveLastReturnedWith(value)`

Also under the alias: .lastReturnedWith(value)

Use .toHaveLastReturnedWith to test the specific value that a mock function last returned. If the last call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value.

For example, let's say you have a mock drink that returns the name of the beverage that was consumed. You can write:

test('drink returns La Croix (Orange) last', () => {
  const beverage1 = {name: 'La Croix (Lemon)'};
  const beverage2 = {name: 'La Croix (Orange)'};
  const drink = jest.fn(beverage => beverage.name);

  drink(beverage1);
  drink(beverage2);

  expect(drink).toHaveLastReturnedWith('La Croix (Orange)');
});

`.toHaveNthReturnedWith(nthCall, value)`

Also under the alias: .nthReturnedWith(nthCall, value)

Use .toHaveNthReturnedWith to test the specific value that a mock function returned for the nth call. If the nth call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value.

For example, let's say you have a mock drink that returns the name of the beverage that was consumed. You can write:

test('drink returns expected nth calls', () => {
  const beverage1 = {name: 'La Croix (Lemon)'};
  const beverage2 = {name: 'La Croix (Orange)'};
  const drink = jest.fn(beverage => beverage.name);

  drink(beverage1);
  drink(beverage2);

  expect(drink).toHaveNthReturnedWith(1, 'La Croix (Lemon)');
  expect(drink).toHaveNthReturnedWith(2, 'La Croix (Orange)');
});

Note: the nth argument must be positive integer starting from 1.

`.toBeCloseTo(number, numDigits)`

浮動小数点に対して厳密な比較を行うのは悪い考えです。丸めるという事は直感的なものが上手く行かなくなることを意味します。

test('adding works sanely with simple decimals', () => {
  expect(0.2 + 0.1).toBe(0.3); // Fails!
});

JavaScriptでは0.2 + 0.1 は実際には 0.30000000000000004なのでこのテストは失敗します。残念。

代わりに .toBeCloseToを使用して下さい。 numDigitsで小数点以下の何位まで確認するのかを制御できます。例えば、 0.2 + 0.1が 0.3に等しいことを小数点５位の精度で確認したい場合は、このようにテストできます:

test('adding works sanely with simple decimals', () => {
  expect(0.2 + 0.1).toBeCloseTo(0.3, 5);
});

numDigitsのデフォルト値は２で、大抵のケースにおいて適切なデフォルト値であると証明されています。

`.toBeDefined()`

変数がundefinedでないことを確認するには .toBeDefinedを使用します。例えば、関数 fetchNewFlavorIdea()が何らかの値を返すことを確認しただけなら、このように書くことができます。

test('there is a new flavor idea', () => {
  expect(fetchNewFlavorIdea()).toBeDefined();
});

expect(fetchNewFlavorIdea()).not.toBe(undefined)とも書くことができますが、undefinedを直接コード内で参照するのは避けたほうが実務上良いでしょう。

`.toBeFalsy()`

値がどのようなものかを気にせず、真偽値のコンテクストの中で値が偽であることを確認したい場合は.toBeFalsy を使用して下さい。例えば、以下のようなアプリケーションコードがあったとします:

drinkSomeLaCroix();
if (!getErrors()) {
  drinkMoreLaCroix();
}

getErrorsがどんなものを返すかは特に気にしないでしょう - false、null、あるいは 0を返すかもしれませんが、それでもコードは動作します。だからラクロワ飲料を飲んだ後でエラーが無いことをテストしたければ、このように書くことができます:

test('drinking La Croix does not lead to errors', () => {
  drinkSomeLaCroix();
  expect(getErrors()).toBeFalsy();
});

JavaScriptでは、偽と類推される６つの値があります: false、 0、 ''、 null、 undefined、そして NaNです。他の全ては真と類推されます。

`.toBeGreaterThan(number)`

浮動小数点数を比較するには、 toBeGreaterThanが使用できます。例えば、 ouncesPerCan()が１０オンスより大きい値を返すことをテストしたい場合は、以下のように書いて下さい:

test('ounces per can is more than 10', () => {
  expect(ouncesPerCan()).toBeGreaterThan(10);
});

`.toBeGreaterThanOrEqual(number)`

浮動小数点数を比較するには、 toBeGreaterThanOrEqualが使用できます。例えば、 ouncesPerCan()が少なくとも１２オンス以上の値を返すことをテストしたい場合は、以下のように書いて下さい:

test('ounces per can is at least 12', () => {
  expect(ouncesPerCan()).toBeGreaterThanOrEqual(12);
});

`.toBeLessThan(number)`

浮動小数点数を比較するには、 toBeLessThanが使用できます。例えば、 ouncesPerCan()が２０オンスより小さい値を返すことをテストしたい場合は、以下のように書いて下さい:

test('ounces per can is less than 20', () => {
  expect(ouncesPerCan()).toBeLessThan(20);
});

`.toBeLessThanOrEqual(number)`

浮動小数点数を比較するには、 toBeLessThanOrEqualが使用できます。例えば、 ouncesPerCan()が１２オンス以下の値を返すことをテストしたい場合は、以下のように書いて下さい:

test('ounces per can is at least 12', () => {
  expect(ouncesPerCan()).toBeGreaterThanOrEqual(12);
});

`.toBeInstanceOf(Class)`

オブジェクトがクラスのインスタンスであることを確認するには .toBeInstanceOf(Class)を使用して下さい。このマッチャは instanceofを内部で利用しています。

class A {}

expect(new A()).toBeInstanceOf(A);
expect(() => {}).toBeInstanceOf(Function);
expect(new A()).toBeInstanceOf(Function); // throws

`.toBeNull()`

.toBeNull() は .toBe(null)と同じですが、エラーメッセージが少し分かりやすいものになっています。そのため何かがnullであることを確認したい場合は .toBeNull()を使用して下さい。

function bloop() {
  return null;
}

test('bloop returns null', () => {
  expect(bloop()).toBeNull();
});

`.toBeTruthy()`

値がどのようなものかを気にせず、真偽値のコンテクストの中で値が真であることを確認したい場合は.toBeTruthy を使用して下さい。例えば、以下のようなアプリケーションコードがあったとします:

drinkSomeLaCroix();
if (thirstInfo()) {
  drinkMoreLaCroix();
}

thirstInfoがどんなものを返すかは特に気にしないでしょう - trueもしくは複雑な値を返すかもしれませんが、それでもコードは動作します。だからラクロワ飲料を飲んだ後にthirstInfoが真(またはそう類推される値) を返すことをテストするには、次のように書くことができます:

test('drinking La Croix leads to having thirst info', () => {
  drinkSomeLaCroix();
  expect(thirstInfo()).toBeTruthy();
});

JavaScriptでは、偽と類推される６つの値があります: false、 0、 ''、 null、 undefined、そして NaNです。他の全ては真と類推されます。

`.toBeUndefined()`

変数がundefinedであることを確認するには .toBeUndefinedを使用します。例えば、関数bestDrinkForFlavor(flavor)が'octopus'味が与えられた時にundefinedを返すことを確認したいとしましょう。タコ味の美味しい飲み物なんてありませんから:

test('the best drink for octopus flavor is undefined', () => {
  expect(bestDrinkForFlavor('octopus')).toBeUndefined();
});

expect(bestDrinkForFlavor('octopus')).toBe(undefined)とも書くことができますが、undefinedを直接コード内で参照するのは避けたほうが実務上良いでしょう。

`.toContain(item)`

アイテムが配列内にあることを確認したい場合は、.toContain を使用します。配列内のアイテムをテストするために、このマッチャは===を使用して厳密な等価性のチェックを行います。 .toContainは、ある文字列が別の文字列の部分文字列であるかをチェックすることもできます。

例えば getAllFlavors()が風味の配列を返し、limeがその中にある事を確認したいなら、このように書くことができます:

test('the flavor list contains lime', () => {
  expect(getAllFlavors()).toContain('lime');
});

`.toContainEqual(item)`

特定の構造と値を持つ要素が配列に含まれていることをチェックしたい場合は.toContainEqualを使用して下さい。配列中のアイテムをテストするために、このマッチャはオブジェクトIDではなく、再帰的に全てのフィールドの等価性を確認します。

describe('my beverage', () => {
  test('is delicious and not sour', () => {
    const myBeverage = {delicious: true, sour: false};
    expect(myBeverages()).toContainEqual(myBeverage);
  });
});

`.toEqual(value)`

2 つのオブジェクトが同じ値を持つことを確認したい場合は、.toEqual を使用します。このマッチャはオブジェクトIdを確認せずに、全てのフィールドの等価性を確認します—これは"deep equal"として知られています。例えば、 toEqual と toBeは以下のテストスイートで異なる振る舞いをするので、全てのテストがパスします:

const can1 = {
  flavor: 'grapefruit',
  ounces: 12,
};
const can2 = {
  flavor: 'grapefruit',
  ounces: 12,
};

describe('the La Croix cans on my desk', () => {
  test('have all the same properties', () => {
    expect(can1).toEqual(can2);
  });
  test('are not the exact same can', () => {
    expect(can1).not.toBe(can2);
  });
});

注意: .toEqualは２つのエラーに deep equalityを実施しません。エラーオブジェクトの messageプロパティのみを等価性の比較対象とします。エラーに対するテストは .toThrowマッチャの使用をお勧めします。

`.toHaveLength(number)`

オブジェクトが.lengthプロパティを持ち、特定の数値であるかを確認するには、.toHaveLength を使用して下さい。

配列や文字列のサイズを確認するのに特に便利です。

expect([1, 2, 3]).toHaveLength(3);
expect('abc').toHaveLength(3);
expect('').not.toHaveLength(5);

`.toMatch(regexpOrString)`

文字列が正規表現と一致することを確認するには.toMatch を使用して下さい。

例えば、essayOnTheBestFlavor() がどのようなものか正確には分からないけれども本当に長い文字列を返すこと、そして grapefruitという文字列がその中のどこかに含まれるべきであるということを知っているとしましょう。以下のコードでテストできます:

describe('an essay on the best flavor', () => {
  test('mentions grapefruit', () => {
    expect(essayOnTheBestFlavor()).toMatch(/grapefruit/);
    expect(essayOnTheBestFlavor()).toMatch(new RegExp('grapefruit'));
  });
});

このマッチャは正規表現と照合する対象に文字列も取ることができます:

describe('grapefruits are healthy', () => {
  test('grapefruits are a fruit', () => {
    expect('grapefruits').toMatch('fruit');
  });
});

`.toMatchObject(object)`

JavaScript オブジェクトが、あるオブジェクトのプロパティのサブセットに一致することを確認するには.ToMatchObject を使用して下さい。期待されるオブジェクトに含まれないプロパティを含む引数のオブジェクトについても一致します。

オブジェクトの配列を渡すこともでき、その場合はメソッドは期待する配列の対応するオブジェクトと引数の配列の各オブジェクトが( 上述のtoMatchObjectと同じ意味で) 一致する場合のみ真を返します。このAPIは引数の配列が余分な要素を持つことを受容する arrayContainingとは反対に、2つの配列がその数で一致することを確認するのに便利です。

プロパティは値またはマッチャでマッチすることができます。

const houseForSale = {
  bath: true,
  bedrooms: 4,
  kitchen: {
    amenities: ['oven', 'stove', 'washer'],
    area: 20,
    wallColor: 'white',
  },
};
const desiredHouse = {
  bath: true,
  kitchen: {
    amenities: ['oven', 'stove', 'washer'],
    wallColor: expect.stringMatching(/white|yellow/),
  },
};

test('the house has my desired features', () => {
  expect(houseForSale).toMatchObject(desiredHouse);
});

describe('toMatchObject applied to arrays arrays', () => {
  test('the number of elements must match exactly', () => {
    expect([{foo: 'bar'}, {baz: 1}]).toMatchObject([{foo: 'bar'}, {baz: 1}]);
  });

  // .arrayContaining "matches a received array which contains elements that
  // are *not* in the expected array"
  test('.toMatchObject does not allow extra elements', () => {
    expect([{foo: 'bar'}, {baz: 1}]).toMatchObject([{foo: 'bar'}]);
  });

  test('.toMatchObject is called for each elements, so extra object properties are okay', () => {
    expect([{foo: 'bar'}, {baz: 1, extra: 'quux'}]).toMatchObject([
      {foo: 'bar'},
      {baz: 1},
    ]);
  });
});

`.toHaveProperty(keyPath, value)`

オブジェクトの指定された参照keyPathのプロパティが存在するかを確認するには、.toHaveProperty を使用して下さい。 For checking deeply nested properties in an object you may use dot notation or an array containing the keyPath for deep references.

必要に応じて、 valueを指定して、対象とするオブジェクトのkeyPathの現在の値と等しいかを確認することができます。このマッチャは(toEqual()のように) 'deep equality' を利用して再帰的に全てのフィールドの等価性を確認します。

次に示す例ではネストされたプロパティを含む houseForSale オブジェクトを含んでいます。 We are using toHaveProperty to check for the existence and values of various properties in the object.

// Object containing house features to be tested
const houseForSale = {
  bath: true,
  bedrooms: 4,
  kitchen: {
    amenities: ['oven', 'stove', 'washer'],
    area: 20,
    wallColor: 'white',
    'nice.oven': true,
  },
};

test('this house has my desired features', () => {
  // Simple Referencing
  expect(houseForSale).toHaveProperty('bath');
  expect(houseForSale).toHaveProperty('bedrooms', 4);

  expect(houseForSale).not.toHaveProperty('pool');

  // Deep referencing using dot notation
  expect(houseForSale).toHaveProperty('kitchen.area', 20);
  expect(houseForSale).toHaveProperty('kitchen.amenities', [
    'oven',
    'stove',
    'washer',
  ]);

  expect(houseForSale).not.toHaveProperty('kitchen.open');

  // Deep referencing using an array containing the keyPath
  expect(houseForSale).toHaveProperty(['kitchen', 'area'], 20);
  expect(houseForSale).toHaveProperty(
    ['kitchen', 'amenities'],
    ['oven', 'stove', 'washer'],
  );
  expect(houseForSale).toHaveProperty(['kitchen', 'amenities', 0], 'oven');
  expect(houseForSale).toHaveProperty(['kitchen', 'nice.oven']);
  expect(houseForSale).not.toHaveProperty(['kitchen', 'open']);
});

`.toMatchSnapshot(propertyMatchers, snapshotName)`

この API は最も最近のスナップショットと一致することを確認します。詳細については the Snapshot Testing guide を確認して下さい。

The optional propertyMatchers argument allows you to specify asymmetric matchers which are verified instead of the exact values.

The last argument allows you option to specify a snapshot name. Otherwise, the name is inferred from the test.

注意: スナップショットテストはReactコンポーネントにおいて最も広く使われていますが、任意のシリアライズ可能な値をスナップショットとして使用することができます。

`.toMatchInlineSnapshot(propertyMatchers, inlineSnapshot)`

Ensures that a value matches the most recent snapshot. Unlike .toMatchSnapshot(), the snapshots will be written to the current source file, inline.

Check out the section on Inline Snapshots for more info.

`.toStrictEqual(value)`

Use .toStrictEqual to test that objects have the same types as well as structure.

Differences from .toEqual:

Keys with undefined properties are checked. e.g. {a: undefined, b: 2} does not match {b: 2} when using .toStrictEqual.
Object types are checked to be equal. e.g. A class instance with fields a and b will not equal a literal object with fields a and b.

class LaCroix {
  constructor(flavor) {
    this.flavor = flavor;
  }
}

describe('the La Croix cans on my desk', () => {
  test('are not semantically the same', () => {
    expect(new LaCroix('lemon')).toEqual({flavor: 'lemon'});
    expect(new LaCroix('lemon')).not.toStrictEqual({flavor: 'lemon'});
  });
});

`.toThrow(error)`

次の別名でも同様となります: .toThrowError(error)

関数が呼ばれた際にエラーを投げることを確認するには.toThrow を使用して下さい。例えば、タコ味なんて気持ち悪すぎて飲めないのでdrinkFlavor('octopus') が例外を投げることをテストしたい場合、次のように書くことができます:

test('throws on octopus', () => {
  expect(() => {
    drinkFlavor('octopus');
  }).toThrow();
});

特定のエラーがスローされることをテストしたい場合は、toThrowに引数を与えることができます。 The argument can be a string that should be contained in the error message, a class for the error, or a regex that should match the error message. 例えば、drinkFlavorはこのようにコーディングされたとしましょう:

function drinkFlavor(flavor) {
  if (flavor == 'octopus') {
    throw new DisgustingFlavorError('yuck, octopus flavor');
  }
  // Do some other stuff
}

いくつかの方法でこのエラーが投げられることをテストできます:

test('throws on octopus', () => {
  function drinkOctopus() {
    drinkFlavor('octopus');
  }

  // Test that the error message says "yuck" somewhere: these are equivalent
  expect(drinkOctopus).toThrowError(/yuck/);
  expect(drinkOctopus).toThrowError('yuck');

  // Test the exact error message
  expect(drinkOctopus).toThrowError(/^yuck, octopus flavor$/);

  // Test that we get a DisgustingFlavorError
  expect(drinkOctopus).toThrowError(DisgustingFlavorError);
});

注意：関数の中のコードはラップしてください。そうしなければエラーが補足されず、アサーションは失敗します。

`.toThrowErrorMatchingSnapshot()`

関数が呼ばれた際に直近のスナップショットと一致するエラーを投げることを確認するには、 .toThrowErrorMatchingSnapshotを使用して下さい。例えば、風味が'octopus'ならば必ずエラーを投げるdrinkFlavor関数があり、次のようなコードだったとします:

function drinkFlavor(flavor) {
  if (flavor == 'octopus') {
    throw new DisgustingFlavorError('yuck, octopus flavor');
  }
  // Do some other stuff
}

この関数のテストはこのようになります:

test('throws on octopus', () => {
  function drinkOctopus() {
    drinkFlavor('octopus');
  }

  expect(drinkOctopus).toThrowErrorMatchingSnapshot();
});

そして次のようなスナップショットを生成します:

exports[`drinking flavors throws on octopus 1`] = `"yuck, octopus flavor"`;

スナップショットテストについての詳細はReact Tree Snapshot Testingを確認して下さい。

`.toThrowErrorMatchingInlineSnapshot()`

This matcher is much like .toThrowErrorMatchingSnapshot, except instead of writing the snapshot value to a .snap file, it will be written into the source code automatically.

Check out the section on Inline Snapshots for more info.