Expect

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

メソッド #

リファレンス #

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);
});

マッチャ は、2つのキーを持つオブジェクトを返す必要があります。 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 = received === expected;

    const message = pass
      ? () => this.utils.matcherHint('.not.toBe') + '\n\n' +
        `Expected value to not be (using ===):\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 ===):\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 ===):
      "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(mock);
  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.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) #

jest バージョン19.0.0+で利用可能 #

expect.stringContaining(string)は期待された文字列とぴったり一致する受け取った文字列と一致します。

expect.stringMatching(regexp) #

expect.stringMatching(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 #

Jest バージョン20.0.0+で利用可能 #

追加のマッチャをチェーンするためにに完了した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');
});

また、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 #

Jest バージョン20.0.0+で利用可能 #

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

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

test('fetchData() rejects to be error', () => {
  // make sure to add a return statement
  return expect(Promise.reject('octopus')).rejects.toBeDefined();
});

また、async/awaitを.rejectsと組み合わせて使うことができます。さらに、このコードでは理由に'octopus'を含んでいることをテストします:

test('fetchData() rejects to be error', async () => {
  const drinkOctopus = new Promise(() => {
      throw new DisgustingFlavorError('yuck, octopus flavor');
  });

  await expect(drinkOctopus).rejects.toMatch('octopus');
});

.toBe(value) #

toBe は値が期待した通りのものかのみを確認します。 ===により厳密な等価性を検証します。

例えば以下のコードでは 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) #

モック関数が期待した回数だけ呼ばれたことを確認するには.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');
});

.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、あるいは ``を返すかもしれませんが、それでもコードは動作します。 だからラクロワ飲料を飲んだ後でエラーが無いことをテストしたければ、このように書くことができます:

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

JavaScriptでは、偽と類推される６つの値があります: false、 `、''、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、 `、''、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 を使用して下さい。リスト中のアイテムをテストするのには ===を使用し、厳密に等価性を確認します。

例えば 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 を使用して下さい。 オブジェクト内で深くネストされたプロパティを確認するには、 深い階層の参照のためのdot notationを使用して下さい。

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

次に示す例ではネストされたプロパティを含む houseForSale オブジェクトを含んでいます。 toHavePropertyを利用してオブジェクト内の様々なプロパティの存在と値の確認を行っています。

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

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');
});

.toMatchSnapshot(optionalString) #

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

また、オプションでのスナップショットの名前を指定できます。指定がなければ、名前はテストから推測されます。

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

.toThrow(error) #

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

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

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

特定のエラーがスローされることをテストしたい場合は、toThrowに引数を与えることができます。 引数はエラーメッセージの文字列か、エラーのクラスか、エラーがマッチするべき正規表現です。 例えば、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 the exact error message
  expect(drinkOctopus).toThrowError('yuck, octopus flavor');

  // Test that the error message says "yuck" somewhere
  expect(drinkOctopus).toThrowError(/yuck/);

  // 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を確認して下さい。