The Jest Object

jest オブジェクトは自動的に各テストファイル内でスコープされます。jest オブジェクトのメソッドはモックの作成を補助したり、Jest全体の動作を管理することができます。

メソッド #

• jest.clearAllTimers()
• jest.disableAutomock()
• jest.enableAutomock()
• jest.fn(implementation)
• jest.isMockFunction(fn)
• jest.genMockFromModule(moduleName)
• jest.mock(moduleName, factory, options)
• jest.unmock(moduleName)
• jest.doMock(moduleName, factory, options)
• jest.dontMock(moduleName)
• jest.clearAllMocks()
• jest.resetAllMocks()
• jest.restoreAllMocks()
• jest.resetModules()
• jest.runAllTicks()
• jest.runAllTimers()
• jest.runTimersToTime(msToRun)
• jest.runOnlyPendingTimers()
• jest.setMock(moduleName, moduleExports)
• jest.setTimeout(timeout)
• jest.useFakeTimers()
• jest.useRealTimers()
• jest.spyOn(object, methodName)

リファレンス #

jest.clearAllTimers() #

タイマーシステムが保留しているあらゆるタイマーを削除します。

つまり、(まだ実行されていない) スケジュールされた全てのタイマーについて、削除され、将来にわたって実行されることはないという事です。

jest.disableAutomock() #

モジュールローダーの自動モック機能を無効にします。

このメソッドが呼び出された後は、すべての require() 関数は各モジュールの (モックではなく) の本物を返すようになります。

この関数はモックしたい依存関係が、モックが要らないものよりもはるかに少ないシナリオがある場合に便利です。 例えば、"implementation details"として分類されるのが妥当な大量の依存関係を持つモジュールのテスト書く場合、それらをモックしたいとは思わないでしょう。

"implementation details"とみなされうるような依存関係の例としては、言語に組み込みの機能(Array.prototypeメソッドなど)から広く利用されているユーティリティ機能(underscore/lo-dash、配列のユーティリティなど)やReact.jsのようなライブラリ全体にわたります。

メソッドチェーンのためにjestオブジェクトを返します。

注意: このメソッドは以前はautoMockOffと呼ばれていました。 babel-jestを使用している場合は、disableAutomockの呼び出しは自動的にコードの先頭で行われます。 この動作を避けるにはautoMockOff を明示的に使用して下さい。

jest.enableAutomock() #

モジュールローダーで自動モック機能を有効化します。

メソッドチェーンのためにjestオブジェクトを返します。

注意: このメソッドは以前はautoMockOnと呼ばれていました。 babel-jestを使用している場合は、enableAutomockの呼び出しは自動的にコードの先頭で行われます。 この動作を避けるにはautoMockOn を明示的に使用して下さい。

jest.fn(implementation) #

新しい、未使用の mock functionを返します。オプションでモックに対する実装を受け取ります。

  const mockFn = jest.fn();
  mockFn();
  expect(mockFn).toHaveBeenCalled();

  // With a mock implementation:
  const returnsTrue = jest.fn(() => true);
  console.log(returnsTrue()); // true;

jest.isMockFunction(fn) #

与えられた関数がモック関数がどうかを返します。

jest.genMockFromModule(moduleName) #

与えられた名前のモジュールに対して自動モック化システムを利用してモック化したモジュールを作成します。

自動モックが持つ機能を拡張した マニュアルモックを作成したい場合に便利です。

jest.mock(moduleName, factory, options) #

requireされた際に自動モック化されたモジュールのモックを作成します。 factory と optionsはオプションです。例えば:

// banana.js
module.exports = () => 'banana';

// __tests__/test.js
jest.mock('../banana');

const banana = require('../banana'); // banana will be explicitly mocked.

banana(); // will return 'undefined' because the function is auto-mocked.

第２引数はJestの自動モックによる設定を用いる代わりに明示的にモジュールのファクトリを指定する場合に使用します。

jest.mock('../moduleName', () => {
  return jest.fn(() => 42);
});

const moduleName = require('../moduleName'); // This runs the function specified as second argument to `jest.mock`.
moduleName(); // Will return '42';

第３引数は仮想モックを作成するのに使用します - これはシステム内のどこにも存在しないモジュールのモックです。

jest.mock('../moduleName', () => {
  /*
   * Custom implementation of a module that doesn't exist in JS,
   * like a generated module or a native module in react-native.
   */
}, {virtual: true});

警告: (setupTestFrameworkScriptFileで指定される) セットアップファイルの中でモジュールをインポートすることは、全てのセットアップファイル内でインポートされるモジュールと同様に、対象となるモジュールがモックされるのを妨げます。

jest.mockによりモックされるモジュールは、jest.mockを呼び出したファイル内でのみモックされます。 モジュールをモックしたテストの後に実行したとしても、そのモジュールをインポートする別のファイルでは、本物のモジュールがインポートされます。

メソッドチェーンのためにjestオブジェクトを返します。

jest.unmock(moduleName) #

指定したモジュールについてrequire()した際に、モジュールシステムは決してモックしたものを返さないことを設定します(例えば常に本物のモジュールを返すべき場合など)。

このAPIの最も一般的な用途は、指定されたモジュールを与えられたテストファイルでテストしようとしている場合(そのため自動的にモックをしたくない場合) です。

メソッドチェーンのためにjestオブジェクトを返します。

jest.doMock(moduleName, factory, options) #

babel-jestを使用している場合、 mock の呼び出しは自動的にコードブロックの先頭で行われます。この振る舞いを明示的に避けるにはこのメソッドを使用してください。

この関数が有用な例の１つとして、同一ファイル内で異なる振る舞いのモックを使用したい場合が挙げられます:

beforeEach(() => {
  jest.resetModules();
});

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toEqual(1);
});

test('moduleName 2', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 2);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toEqual(2);
});

メソッドチェーンのためにjestオブジェクトを返します。

jest.dontMock(moduleName) #

babel-jestを使用している場合、 unmock の呼び出しは自動的にコードブロックの先頭で行われます。この振る舞いを明示的に避けるにはこのメソッドを使用してください。

メソッドチェーンのためにjestオブジェクトを返します。

jest.clearAllMocks() #

全てのモックの mock.calls と mock.instancesプロパティを初期化します。モック化された関数の各々に.mockClear()関数を呼び出すことに相当します。

メソッドチェーンのためにjestオブジェクトを返します。

jest.resetAllMocks() #

すべてのモックの状態をリセットします。モック化された関数の各々に .mockReset() 関数を呼び出すことに相当します。

メソッドチェーンのためにjestオブジェクトを返します。

jest.restoreAllMocks() #

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

全てのモックを初期値に戻します。 モック化された関数の 各々に.mockRestore を呼び出すことに相当します。 jest.restoreAllMocks()はjest.spyOnによって作成されたモックに対してのみ動作することに気をつけて下さい。他のモックは手動で復元する必要があります。

jest.resetModules() #

モジュールのレジストリ - 全てのrequireされたモジュール - をリセットします 。テスト間でローカルの状態が競合しうるモジュールの状態をテストごとに切り離すのに役立ちます。

例:

const sum1 = require('../sum');
jest.resetModules();
const sum2 = require('../sum');
sum1 === sum2;
// > false (Both sum modules are separate "instances" of the sum module.)

テストにおける例:

beforeEach(() => {
  jest.resetModules();
});

test('works', () => {
  const sum = require('../sum');
});

test('works too', () => {
  const sum = require('../sum');
  // sum is a different copy of the sum module from the previous test.
});

メソッドチェーンのためにjestオブジェクトを返します。

jest.runAllTicks() #

micro-task キューを処理します(通常はnodeでprocess.nextTick経由でやり取りします)。

このAPIが呼ばれた場合、process.nextTick経由でキューイングされた全ての保留中のmicro-taskが実行されます。 さらに、それらmicro-task自身が新しいmicro-taskをスケジュールしている場合は、キューからmicro-taskが無くなるまで継続的に処理されます。

jest.runAllTimers() #

macro-taskキューを全て処理します(つまり、setTimeout()、setInterval()、そして setImmediate()によってキューイングされた全てのタスクです)

このAPIが呼ばれた場合、setTimeout() か setInterval()によってキューイングされた全ての保留中の "macro-tasks"が実行されます。 さらに、それらmacro-task自身が新しいmacro-taskをスケジュールしている場合は、キューからmacro-taskが無くなるまで継続的に処理されます。

このAPIは setTimeout() や setInterval()コールバックが実行された後でのみ発生するような動作を同期して確認するために、テスト中に同期的にsetTimeouts関数を動作させる場合に便利です。 詳細については Timer mocks doc を参照してください。

jest.runAllImmediates() #

setImmediate() によってキューイングされた全てのタスクを処理します。

jest.runTimersToTime(msToRun) #

macro taskキューのみを実行します(つまり、 setTimeout() か setInterval() や setImmediate()によってキューイングされた全てのタスクです)。

このAPIが呼ばれた場合、setTimeout() か setInterval()によってキューイングされたmsToRunミリ秒以内の範囲で実行される予定の全ての保留中の "macro-tasks"が、実行されます。 さらに、それらmacro-task自身が新しいmacro-taskを同じ時間枠でスケジュールしている場合は、 msToRunミリ秒の範囲で実行されるべきmacro-taskがキューから無くなるまで処理されます。

jest.runOnlyPendingTimers() #

現時点で保留中のmacro-taskのみを実行します(つまりこの時点までにsetTimeout() か setInterval()によってキューイングされたタスクのみです)。 その時点で保留中の macro-tasksが新しい macro-taskをスケジュールしている場合、それらの新しいタスクはこのAPIからの呼び出しでは実行されません。

このAPIはテスト対象のモジュールがsetTimeout()が新たなsetTimeout()をコールバック内で再帰的にスケジュールしているようなシナリオに役立ちます(コールバック内のスケジューリングは停止しないということです) これらのシナリオでは、一度に１回ずつ時間を進めることができる事が便利なのです。

jest.setMock(moduleName, moduleExports) #

指定されたモジュールについてモジュールシステムが返すべきモックオブジェクトを明示的に与えます。

場合によってモジュールシステムが通常提供する自動生成されたモックはテストで必要とされる機能を十分に満たさないことがあります。 通常そのような状況では当該のモジュールにより適したマニュアルモックを作成するべきです。 しかしとても稀ですが、マニュアルモックですら目的に対して適切でなくテスト内でモックを作成する必要があるケースがあります。

これらの稀なシナリオでは、このAPIでモジュールシステムのモックモジュールのレジストリのスロットに手動で設定することができます。

メソッドチェーンのためにjestオブジェクトを返します。

注意: このAPIの代わりにjest.mock()を利用することをお勧めします。 jest.mockAPIの第２引数はエクスポートされたモジュールのオブジェクトの代替となるモジュールのファクトリを指定できます。

jest.setTimeout(timeout) #

テストと前後のフックスクリプトでデフォルト値となるタイムアウト間隔をミリ秒単位で設定します。

注意: このメソッドが呼ばれなかった場合、デフォルトのタイムアウト間隔は５秒です。

例:

jest.setTimeout(1000); // 1 second

jest.useFakeTimers() #

Jestに標準タイマー関数の偽のバージョンを使うように指示します (setTimeout, setInterval, clearTimeout, clearInterval, nextTick, setImmediate そして clearImmediateが対象の関数です)。

メソッドチェーンのためにjestオブジェクトを返します。

jest.useRealTimers() #

Jestに標準タイマー関数の実際のバージョンを使用するように指示します。

メソッドチェーンのためにjestオブジェクトを返します。

jest.spyOn(object, methodName) #

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

jest.fnと同様の関数を作成しますが、引数に与えられたobject[methodName]へのコールも実装します。Jestのモック関数を返します。

注意: デフォルトでは、 jest.spyOn はスパイ化されたメソッドも呼び出します。 これは他の大抵のテストライブラリとは異なる振る舞いです。 元の関数を上書きしたい場合は、 jest.spyOn(object, methodName).mockImplementation(() => customImplementation) または object[methodName] = jest.fn(() => customImplementation);を使用して下さい。

例:

const video = {
  play() {
    return true;
  },
};

module.exports = video;

テストの例:

const video = require('./video');

test('plays video', () => {
  const spy = jest.spyOn(video, 'play');
  const isPlaying = video.play();

  expect(spy).toHaveBeenCalled();
  expect(isPlaying).toBe(true);

  spy.mockReset();
  spy.mockRestore();
});