バージョン: 29.7

Jest オブジェクト

jest オブジェクトは、すべてのテストファイル内で自動的にスコープに入ります。jest オブジェクト内のメソッドは、モックの作成や Jest の全体的な動作の制御に役立ちます。また、import {jest} from '@jest/globals' を使用して明示的にインポートすることもできます。

情報

このページの TypeScript の例は、Jest API を明示的にインポートした場合にのみ、ドキュメントどおりに動作します

import {expect, jest, test} from '@jest/globals';

TypeScript での Jest の設定方法の詳細については、入門ガイドを参照してください。

メソッド

モックモジュール
モック関数
フェイクタイマー
その他

モックモジュール

`jest.disableAutomock()`

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

情報

このメソッドを有効にするには、automock 設定オプションで自動モックを有効にする必要があります。詳細については、構成オプションのドキュメントも参照してください。

JavaScript
TypeScript

/** @type {import('jest').Config} */
const config = {
  automock: true,
};

module.exports = config;

import type {Config} from 'jest';

const config: Config = {
  automock: true,
};

export default config;

disableAutomock() が呼び出されると、すべての require() は (モックされたバージョンではなく) 各モジュールの実際のバージョンを返します。

utils.js
export default {
  authorize: () => {
    return 'token';
  },
};

__tests__/disableAutomocking.js
import utils from '../utils';

jest.disableAutomock();

test('original implementation', () => {
  // now we have the original implementation,
  // even if we set the automocking in a jest configuration
  expect(utils.authorize()).toBe('token');
});

これは通常、モックしたい依存関係の数が、モックしたくない依存関係の数よりもはるかに少ない場合に役立ちます。たとえば、モジュールの「実装の詳細」として合理的に分類できる多数の依存関係を使用するモジュールのテストを作成する場合、それらをモックしたくない可能性があります。

「実装の詳細」と見なされる可能性のある依存関係の例としては、言語組み込み (例: Array.prototype メソッド) から、非常に一般的なユーティリティメソッド (例: underscore、lodash、配列ユーティリティなど) や、React.js などのライブラリ全体まで、幅広いものがあります。

チェーンするために jest オブジェクトを返します。

ヒント

babel-jest を使用する場合、disableAutomock() の呼び出しはコードブロックの先頭に自動的に巻き上げられます。この動作を明示的に回避したい場合は、autoMockOff() を使用します。

`jest.enableAutomock()`

モジュールローダーでの自動モックを有効にします。

情報

自動モックの詳細については、automock 設定オプションのドキュメントを参照してください。

例

utils.js
export default {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};

__tests__/enableAutomocking.js
jest.enableAutomock();

import utils from '../utils';

test('original implementation', () => {
  // now we have the mocked implementation,
  expect(utils.authorize._isMockFunction).toBeTruthy();
  expect(utils.isAuthorized._isMockFunction).toBeTruthy();
});

チェーンするために jest オブジェクトを返します。

ヒント

babel-jest を使用する場合、enableAutomock の呼び出しはコードブロックの先頭に自動的に巻き上げられます。この動作を明示的に回避したい場合は、autoMockOn を使用します。

`jest.createMockFromModule(moduleName)`

モジュールの名前が与えられた場合、自動モックシステムを使用して、モジュールのモックバージョンを生成します。

これは、自動モックの動作を拡張する手動モックを作成する場合に役立ちます。

JavaScript
TypeScript

utils.js
module.exports = {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};

__tests__/createMockFromModule.test.js
const utils = jest.createMockFromModule('../utils');

utils.isAuthorized = jest.fn(secret => secret === 'not wizard');

test('implementation created by jest.createMockFromModule', () => {
  expect(jest.isMockFunction(utils.authorize)).toBe(true);
  expect(utils.isAuthorized('not wizard')).toBe(true);
});

utils.ts
export const utils = {
  authorize: () => {
    return 'token';
  },
  isAuthorized: (secret: string) => secret === 'wizard',
};

__tests__/createMockFromModule.test.ts
const {utils} =
  jest.createMockFromModule<typeof import('../utils')>('../utils');

utils.isAuthorized = jest.fn((secret: string) => secret === 'not wizard');

test('implementation created by jest.createMockFromModule', () => {
  expect(jest.isMockFunction(utils.authorize)).toBe(true);
  expect(utils.isAuthorized('not wizard')).toBe(true);
});

これは、createMockFromModule が次のデータ型をモックする方法です

`Function`

新しいモック関数を作成します。新しい関数には正式なパラメーターはなく、呼び出されると undefined を返します。この機能は async 関数にも適用されます。

`Class`

新しいクラスを作成します。元のクラスのインターフェイスは維持され、すべてのクラスメンバ関数とプロパティはモックされます。

`Object`

新しい深くクローンされたオブジェクトを作成します。オブジェクトキーは維持され、それらの値はモックされます。

`Array`

元の配列を無視して、新しい空の配列を作成します。

`Primitives`

元のプロパティと同じプリミティブ値を持つ新しいプロパティを作成します。

例

example.js
module.exports = {
  function: function square(a, b) {
    return a * b;
  },
  asyncFunction: async function asyncSquare(a, b) {
    const result = (await a) * b;
    return result;
  },
  class: new (class Bar {
    constructor() {
      this.array = [1, 2, 3];
    }
    foo() {}
  })(),
  object: {
    baz: 'foo',
    bar: {
      fiz: 1,
      buzz: [1, 2, 3],
    },
  },
  array: [1, 2, 3],
  number: 123,
  string: 'baz',
  boolean: true,
  symbol: Symbol.for('a.b.c'),
};

__tests__/example.test.js
const example = jest.createMockFromModule('../example');

test('should run example code', () => {
  // creates a new mocked function with no formal arguments.
  expect(example.function.name).toBe('square');
  expect(example.function).toHaveLength(0);

  // async functions get the same treatment as standard synchronous functions.
  expect(example.asyncFunction.name).toBe('asyncSquare');
  expect(example.asyncFunction).toHaveLength(0);

  // creates a new class with the same interface, member functions and properties are mocked.
  expect(example.class.constructor.name).toBe('Bar');
  expect(example.class.foo.name).toBe('foo');
  expect(example.class.array).toHaveLength(0);

  // creates a deeply cloned version of the original object.
  expect(example.object).toEqual({
    baz: 'foo',
    bar: {
      fiz: 1,
      buzz: [],
    },
  });

  // creates a new empty array, ignoring the original array.
  expect(example.array).toHaveLength(0);

  // creates a new property with the same primitive value as the original property.
  expect(example.number).toBe(123);
  expect(example.string).toBe('baz');
  expect(example.boolean).toBe(true);
  expect(example.symbol).toEqual(Symbol.for('a.b.c'));
});

`jest.mock(moduleName, factory, options)`

モジュールが必要なときに、自動モックバージョンでモジュールをモックします。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.

2 番目の引数を使用して、Jest の自動モック機能を使用する代わりに実行される明示的なモジュールファクトリーを指定できます。

JavaScript
TypeScript

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

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

// The optional type argument provides typings for the module factory
jest.mock<typeof import('../moduleName')>('../moduleName', () => {
  return jest.fn(() => 42);
});

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

デフォルトエクスポートを持つ ES6 モジュールに factory パラメーターを使用する場合、__esModule: true プロパティを指定する必要があります。このプロパティは通常、Babel/TypeScript によって生成されますが、ここでは手動で設定する必要があります。デフォルトのエクスポートをインポートする場合、エクスポートオブジェクトから default という名前のプロパティをインポートする指示になります。

import moduleName, {foo} from '../moduleName';

jest.mock('../moduleName', () => {
  return {
    __esModule: true,
    default: jest.fn(() => 42),
    foo: jest.fn(() => 43),
  };
});

moduleName(); // Will return 42
foo(); // Will return 43

3 番目の引数を使用して、仮想モックを作成できます。これは、システム内のどこにも存在しないモジュールのモックです。

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

注意

(setupFilesAfterEnv で指定されているように) セットアップファイルでモジュールをインポートすると、該当のモジュールと、インポートするすべてのモジュールのモックが妨げられます。

jest.mock でモックされたモジュールは、jest.mock を呼び出すファイルでのみモックされます。モジュールをインポートする別のファイルは、モジュールをモックするテストファイルの後に実行されたとしても、元の実装を取得します。

チェーンするために jest オブジェクトを返します。

ヒント

TypeScript でテストを作成しますか？モックされたモジュールに型を付けるには、jest.Mocked ユーティリティ型または jest.mocked() ヘルパーメソッドを使用してください。

`jest.Mocked<Source>`

ドキュメントについては、モック関数のページの TypeScript の使用の章を参照してください。

`jest.mocked(source, options?)`

ドキュメントについては、モック関数のページの TypeScript の使用の章を参照してください。

`jest.unmock(moduleName)`

モジュールシステムが、指定されたモジュールのモックバージョンを require() から返してはならない (つまり、常に実際のモジュールを返す必要がある) ことを示します。

この API の最も一般的な用途は、特定のテストがテストしようとしているモジュール (したがって、自動的にモックしたくない) を指定することです。

チェーンするために jest オブジェクトを返します。

`jest.deepUnmock(moduleName)`

モジュールシステムが、指定されたモジュールとその依存関係のモックバージョンを返してはならないことを示します。

チェーンするために jest オブジェクトを返します。

`jest.doMock(moduleName, factory, options)`

babel-jest を使用する場合、mock の呼び出しはコードブロックの先頭に自動的に巻き上げられます。この動作を明示的に回避したい場合は、このメソッドを使用します。

これが役立つ場合の 1 つの例は、同じファイル内でモジュールを異なる方法でモックしたい場合です

JavaScript
TypeScript

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

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

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

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

test('moduleName 1', () => {
  // The optional type argument provides typings for the module factory
  jest.doMock<typeof import('../moduleName')>('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(1);
});

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

ES6 インポートで jest.doMock() を使用するには、追加の手順が必要です。テストで require を使用したくない場合は、次の手順に従います

__esModule: true プロパティを指定する必要があります (jest.mock() API の詳細を参照してください)。
静的な ES6 モジュールインポートはファイルの先頭に巻き上げられるため、代わりに import() を使用して動的にインポートする必要があります。
最後に、動的インポートをサポートする環境が必要です。初期設定については、Babelの使用を参照してください。次に、Nodeで動的インポートを有効にするために、プラグインbabel-plugin-dynamic-import-node、または同等のものをBabelの設定に追加してください。

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

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return {
      __esModule: true,
      default: 'default1',
      foo: 'foo1',
    };
  });
  return import('../moduleName').then(moduleName => {
    expect(moduleName.default).toBe('default1');
    expect(moduleName.foo).toBe('foo1');
  });
});

test('moduleName 2', () => {
  jest.doMock('../moduleName', () => {
    return {
      __esModule: true,
      default: 'default2',
      foo: 'foo2',
    };
  });
  return import('../moduleName').then(moduleName => {
    expect(moduleName.default).toBe('default2');
    expect(moduleName.foo).toBe('foo2');
  });
});

チェーンするために jest オブジェクトを返します。

`jest.dontMock(moduleName)`

babel-jestを使用する場合、unmockへの呼び出しはコードブロックの先頭に自動的に巻き上げられます。この動作を明示的に回避したい場合は、このメソッドを使用してください。

チェーンするために jest オブジェクトを返します。

`jest.setMock(moduleName, moduleExports)`

指定されたモジュールに対して、モジュールシステムが返すモックオブジェクトを明示的に提供します。

場合によっては、モジュールシステムが通常提供する自動生成されたモックが、テストのニーズに十分ではない場合があります。通常、そのような状況では、対象のモジュールに対してより適切な手動モックを作成する必要があります。ただし、ごくまれに、手動モックでさえ目的に適さず、テスト内で自分でモックを構築する必要がある場合があります。

このようなまれなシナリオでは、このAPIを使用して、モジュールシステムのモックモジュールレジストリのスロットを手動で埋めることができます。

チェーンするために jest オブジェクトを返します。

情報

代わりにjest.mock()を使用することをお勧めします。jest.mock APIの2番目の引数は、予期されるエクスポートされたモジュールオブジェクトではなく、モジュールファクトリーです。

`jest.requireActual(moduleName)`

モックではなく実際のモジュールを返します。モジュールがモック実装を受け取るべきかどうかに関するすべてのチェックをバイパスします。

JavaScript
TypeScript

jest.mock('../myModule', () => {
  // Require the original module to not be mocked...
  const originalModule = jest.requireActual('../myModule');

  return {
    __esModule: true, // Use it when dealing with esModules
    ...originalModule,
    getRandom: jest.fn(() => 10),
  };
});

const getRandom = require('../myModule').getRandom;

getRandom(); // Always returns 10

jest.mock('../myModule', () => {
  // Require the original module to not be mocked...
  const originalModule =
    jest.requireActual<typeof import('../myModule')>('../myModule');

  return {
    __esModule: true, // Use it when dealing with esModules
    ...originalModule,
    getRandom: jest.fn(() => 10),
  };
});

const getRandom = require('../myModule').getRandom;

getRandom(); // Always returns 10

`jest.requireMock(moduleName)`

実際のモジュールではなくモックモジュールを返します。モジュールを通常どおりに要求すべきかどうかに関するすべてのチェックをバイパスします。

`jest.resetModules()`

モジュールレジストリ（必要なすべてのモジュールのキャッシュ）をリセットします。これは、テスト間でローカル状態が競合する可能性のあるモジュールを分離するのに役立ちます。

例

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.isolateModules(fn)`

jest.isolateModules(fn)は、jest.resetModules()よりもさらに一歩進んでおり、コールバック関数内でロードされるモジュールのサンドボックスレジストリを作成します。これは、テスト間でローカルモジュール状態が競合しないように、すべてのテストで特定のモジュールを分離するのに役立ちます。

let myModule;
jest.isolateModules(() => {
  myModule = require('myModule');
});

const otherCopyOfMyModule = require('myModule');

`jest.isolateModulesAsync(fn)`

jest.isolateModulesAsync()は、jest.isolateModules()と同等ですが、非同期コールバック用です。呼び出し側は、isolateModulesAsyncの完了をawaitする必要があります。

let myModule;
await jest.isolateModulesAsync(async () => {
  myModule = await import('myModule');
  // do async stuff here
});

const otherCopyOfMyModule = await import('myModule');

モック関数

`jest.fn(implementation?)`

新しい未使用のモック関数を返します。オプションで、モック実装を取ります。

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

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

ヒント

TypeScriptの使用方法の詳細については、モック関数ページを参照してください。

`jest.isMockFunction(fn)`

指定された関数がモック関数であるかどうかを判断します。

`jest.replaceProperty(object, propertyKey, value)`

object[propertyKey]をvalueに置き換えます。プロパティは、オブジェクトにすでに存在している必要があります。同じプロパティを複数回置き換えることができます。Jestの置き換えられたプロパティを返します。

注意

ゲッターまたはセッターとして定義されているプロパティをモックするには、代わりにjest.spyOn(object, methodName, accessType)を使用してください。関数をモックするには、代わりにjest.spyOn(object, methodName)を使用してください。

ヒント

jest.replacePropertyで置き換えられたすべてのプロパティは、afterEachメソッドでjest.restoreAllMocksを呼び出すことで、元の値に復元できます。

例

const utils = {
  isLocalhost() {
    return process.env.HOSTNAME === 'localhost';
  },
};

module.exports = utils;

テストの例

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

afterEach(() => {
  // restore replaced property
  jest.restoreAllMocks();
});

test('isLocalhost returns true when HOSTNAME is localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'localhost'});
  expect(utils.isLocalhost()).toBe(true);
});

test('isLocalhost returns false when HOSTNAME is not localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'not-localhost'});
  expect(utils.isLocalhost()).toBe(false);
});

`jest.spyOn(object, methodName)`

jest.fnに似たモック関数を作成しますが、object[methodName]への呼び出しも追跡します。Jestのモック関数を返します。

注意

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

ヒント

jest.spyOnはモックであるため、afterEachフックに渡されるコールバックの本体でjest.restoreAllMocksを呼び出すことで、初期状態を復元できます。

例

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

module.exports = video;

テストの例

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

afterEach(() => {
  // restore the spy created with spyOn
  jest.restoreAllMocks();
});

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

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

`jest.spyOn(object, methodName, accessType?)`

Jest 22.1.0以降では、jest.spyOnメソッドは、ゲッターまたはセッターをそれぞれスパイする場合に役立つaccessTypeのオプションの3番目の引数（'get'または'set'のいずれか）を受け取ります。

例

const video = {
  // it's a getter!
  get play() {
    return true;
  },
};

module.exports = video;

const audio = {
  _volume: false,
  // it's a setter!
  set volume(value) {
    this._volume = value;
  },
  get volume() {
    return this._volume;
  },
};

module.exports = audio;

テストの例

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

afterEach(() => {
  // restore the spy created with spyOn
  jest.restoreAllMocks();
});

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

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

test('plays audio', () => {
  const spy = jest.spyOn(audio, 'volume', 'set'); // we pass 'set'
  audio.volume = 100;

  expect(spy).toHaveBeenCalled();
  expect(audio.volume).toBe(100);
});

`jest.Replaced<Source>`

ドキュメントについては、モック関数のページのTypeScriptの使用の章を参照してください。

`jest.Spied<Source>`

ドキュメントについては、モック関数のページのTypeScriptの使用の章を参照してください。

`jest.clearAllMocks()`

すべてのモックのmock.calls、mock.instances、mock.contexts、およびmock.resultsプロパティをクリアします。すべてのモック関数で.mockClear()を呼び出すのと同じです。

チェーンするために jest オブジェクトを返します。

`jest.resetAllMocks()`

すべてのモックの状態をリセットします。すべてのモック関数で.mockReset()を呼び出すのと同じです。

チェーンするために jest オブジェクトを返します。

`jest.restoreAllMocks()`

すべてのモックと置き換えられたプロパティを元の値に戻します。すべてのモック関数で.mockRestore()を呼び出し、すべての置き換えられたプロパティで.restore()を呼び出すのと同じです。jest.restoreAllMocks()は、jest.spyOn()で作成されたモックと、jest.replaceProperty()で置き換えられたプロパティでのみ機能することに注意してください。他のモックでは、手動で復元する必要があります。

フェイクタイマー

`jest.useFakeTimers(fakeTimersConfig?)`

グローバルな日付、パフォーマンス、時間、およびタイマーAPIのフェイクバージョンを使用するようにJestに指示します。フェイクタイマーの実装は、@sinonjs/fake-timersによってサポートされています。

フェイクタイマーは、Date、performance.now()、queueMicrotask()、setImmediate()、clearImmediate()、setInterval()、clearInterval()、setTimeout()、clearTimeout()を、フェイククロックから時間を取得する実装に置き換えます。

Node環境ではprocess.hrtime、process.nextTick()が、JSDOM環境ではrequestAnimationFrame()、cancelAnimationFrame()、requestIdleCallback()、cancelIdleCallback()も置き換えられます。

構成オプション

type FakeableAPI =
  | 'Date'
  | 'hrtime'
  | 'nextTick'
  | 'performance'
  | 'queueMicrotask'
  | 'requestAnimationFrame'
  | 'cancelAnimationFrame'
  | 'requestIdleCallback'
  | 'cancelIdleCallback'
  | 'setImmediate'
  | 'clearImmediate'
  | 'setInterval'
  | 'clearInterval'
  | 'setTimeout'
  | 'clearTimeout';

type FakeTimersConfig = {
  /**
   * If set to `true` all timers will be advanced automatically by 20 milliseconds
   * every 20 milliseconds. A custom time delta may be provided by passing a number.
   * The default is `false`.
   */
  advanceTimers?: boolean | number;
  /**
   * List of names of APIs that should not be faked. The default is `[]`, meaning
   * all APIs are faked.
   */
  doNotFake?: Array<FakeableAPI>;
  /**
   * Use the old fake timers implementation instead of one backed by `@sinonjs/fake-timers`.
   * The default is `false`.
   */
  legacyFakeTimers?: boolean;
  /** Sets current system time to be used by fake timers, in milliseconds. The default is `Date.now()`. */
  now?: number | Date;
  /**
   * The maximum number of recursive timers that will be run when calling `jest.runAllTimers()`.
   * The default is `100_000` timers.
   */
  timerLimit?: number;
};

jest.useFakeTimers()を呼び出すと、元のタイマーがjest.useRealTimers()で復元されるまで、ファイル内のすべてのテストでフェイクタイマーが使用されます。

jest.useFakeTimers()またはjest.useRealTimers()は、トップレベル、testブロック内など、どこからでも呼び出すことができます。これはグローバルな操作であり、同じファイル内の他のテストに影響を与えることに注意してください。同じテストファイルでjest.useFakeTimers()をもう一度呼び出すと、内部状態（タイマーカウントなど）がリセットされ、指定されたオプションを使用してフェイクタイマーが再インストールされます。

test('advance the timers automatically', () => {
  jest.useFakeTimers({advanceTimers: true});
  // ...
});

test('do not advance the timers and do not fake `performance`', () => {
  jest.useFakeTimers({doNotFake: ['performance']});
  // ...
});

test('uninstall fake timers for the rest of tests in the file', () => {
  jest.useRealTimers();
  // ...
});

レガシーフェイクタイマー

何らかの理由で、レガシー実装のフェイクタイマーを使用する必要がある場合があります。これは、このように有効にできます（追加のオプションはサポートされていません）。

jest.useFakeTimers({
  legacyFakeTimers: true,
});

レガシーフェイクタイマーは、setImmediate()、clearImmediate()、setInterval()、clearInterval()、setTimeout()、clearTimeout()をJestのモック関数に置き換えます。Node環境ではprocess.nextTick()が、JSDOM環境ではrequestAnimationFrame()、cancelAnimationFrame()も置き換えられます。

チェーンするために jest オブジェクトを返します。

`jest.useRealTimers()`

グローバルな日付、パフォーマンス、時間、およびタイマーAPIの元の実装を復元するようにJestに指示します。たとえば、各テストの後にタイマーを復元するために、afterEachフック内でjest.useRealTimers()を呼び出すことができます。

afterEach(() => {
  jest.useRealTimers();
});

test('do something with fake timers', () => {
  jest.useFakeTimers();
  // ...
});

test('do something with real timers', () => {
  // ...
});

チェーンするために jest オブジェクトを返します。

`jest.runAllTicks()`

マイクロタスクキュー（通常、nodeでprocess.nextTickを介してインターフェースされる）を使い果たします。

このAPIが呼び出されると、process.nextTickを介してキューに入れられた保留中のすべてのマイクロタスクが実行されます。さらに、これらのマイクロタスク自体が新しいマイクロタスクをスケジュールした場合、キューに残っているマイクロタスクがなくなるまで、それらが継続的に使い果たされます。

`jest.runAllTimers()`

マクロタスクキュー（つまり、setTimeout()、setInterval()、およびsetImmediate()によってキューに入れられたすべてのタスク）とマイクロタスクキュー（通常、nodeでprocess.nextTickを介してインターフェースされる）の両方を使い果たします。

このAPIが呼び出されると、保留中のすべてのマクロタスクとマイクロタスクが実行されます。これらのタスク自体が新しいタスクをスケジュールした場合、キューに残っているタスクがなくなるまで、それらが継続的に使い果たされます。

これは、テスト中にsetTimeout()やsetInterval()のコールバックが実行された後にのみ発生するはずの動作について、同期的にアサートするために、setTimeoutを同期的に実行するのに役立つことがよくあります。詳しくはタイマーモックのドキュメントをご覧ください。

`jest.runAllTimersAsync()`

jest.runAllTimers()の非同期版です。これにより、スケジュールされたPromiseのコールバックがタイマーを実行する前に実行されるようになります。

情報

この関数は、レガシーなフェイクタイマーの実装を使用している場合は利用できません。

`jest.runAllImmediates()`

setImmediate()によってキューイングされたすべてのタスクを使い果たします。

情報

この関数は、レガシーなフェイクタイマーの実装を使用している場合にのみ利用可能です。

`jest.advanceTimersByTime(msToRun)`

マクロタスクキュー（つまり、setTimeout()、setInterval()、およびsetImmediate()によってキューイングされたすべてのタスク）のみを実行します。

このAPIが呼び出されると、すべてのタイマーがmsToRunミリ秒進められます。setTimeout()またはsetInterval()経由でキューイングされ、この時間内に実行されるはずの保留中の「マクロタスク」はすべて実行されます。さらに、これらのマクロタスクが同じ時間内に実行されるはずの新しいマクロタスクをスケジュールする場合、それらはmsToRunミリ秒以内に実行されるはずのマクロタスクがキューに残らなくなるまで実行されます。

`jest.advanceTimersByTimeAsync(msToRun)`

jest.advanceTimersByTime(msToRun)の非同期版です。これにより、スケジュールされたPromiseのコールバックがタイマーを実行する前に実行されるようになります。

情報

この関数は、レガシーなフェイクタイマーの実装を使用している場合は利用できません。

`jest.runOnlyPendingTimers()`

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

これは、テスト対象のモジュールが、コールバックが別のsetTimeout()を再帰的にスケジュールするsetTimeout()をスケジュールするようなシナリオ（つまり、スケジュールが止まらない場合）に役立ちます。これらのシナリオでは、一度に1ステップずつ時間を進めることができると便利です。

`jest.runOnlyPendingTimersAsync()`

jest.runOnlyPendingTimers()の非同期版です。これにより、スケジュールされたPromiseのコールバックがタイマーを実行する前に実行されるようになります。

情報

この関数は、レガシーなフェイクタイマーの実装を使用している場合は利用できません。

`jest.advanceTimersToNextTimer(steps)`

必要なミリ秒だけすべてのタイマーを進め、次のタイムアウト/インターバルのみが実行されるようにします。

オプションで、stepsを指定して、次のタイムアウト/インターバルをsteps回実行できます。

`jest.advanceTimersToNextTimerAsync(steps)`

jest.advanceTimersToNextTimer(steps)の非同期版です。これにより、スケジュールされたPromiseのコールバックがタイマーを実行する前に実行されるようになります。

情報

この関数は、レガシーなフェイクタイマーの実装を使用している場合は利用できません。

`jest.clearAllTimers()`

タイマーシステムから保留中のタイマーをすべて削除します。

つまり、タイマーがスケジュールされている場合（ただし、まだ実行されていない場合）、それらはクリアされ、将来実行される機会がなくなります。

`jest.getTimerCount()`

実行を待っているフェイクタイマーの数を返します。

`jest.now()`

現在のクロックの時刻をミリ秒単位で返します。これは、実際のタイマーが使用されている場合、またはDateがモックされている場合はDate.now()と同等です。それ以外の場合（レガシータイマーなど）は、Date.now()、performance.now()などのカスタムモックを実装するのに役立つ場合があります。

`jest.setSystemTime(now?: number | Date)`

フェイクタイマーで使用される現在のシステム時刻を設定します。プログラムの実行中にユーザーがシステムクロックを変更するのをシミュレートします。現在の時刻に影響を与えますが、それ自体は、たとえばタイマーを起動させる原因にはなりません。タイマーはjest.setSystemTime()の呼び出しがなくても実行されるはずだったとおりに正確に実行されます。

情報

この関数は、レガシーなフェイクタイマーの実装を使用している場合は利用できません。

`jest.getRealSystemTime()`

時刻をモックすると、Date.now()もモックされます。何らかの理由で実際の現在の時刻にアクセスする必要がある場合は、この関数を呼び出すことができます。

情報

この関数は、レガシーなフェイクタイマーの実装を使用している場合は利用できません。

その他

`jest.getSeed()`

Jestを実行するたびに、擬似乱数ジェネレーターやその他の場所で使用できるシード値がランダムに生成されます。

ヒント

テストレポートの概要にシードを出力するには、--showSeedフラグを使用します。シードの値を手動で設定するには、--seed=<num> CLI引数を使用します。

`jest.isEnvironmentTornDown()`

テスト環境が破棄された場合はtrueを返します。

`jest.retryTimes(numRetries, options?)`

失敗したテストが合格するか、最大リトライ回数を使い果たすまで、n回実行します。

jest.retryTimes(3);

test('will fail', () => {
  expect(true).toBe(false);
});

logErrorsBeforeRetryオプションが有効になっている場合、テストが失敗した原因となったエラーがコンソールに記録されます。

jest.retryTimes(3, {logErrorsBeforeRetry: true});

test('will fail', () => {
  expect(true).toBe(false);
});

チェーンするために jest オブジェクトを返します。

注意

jest.retryTimes()は、テストファイルの一番上またはdescribeブロックで宣言する必要があります。

情報

この関数は、デフォルトのjest-circusランナーでのみ利用可能です。

`jest.setTimeout(timeout)`

テストファイル内のすべてのテストおよびbefore/afterフックのデフォルトのタイムアウト間隔（ミリ秒単位）を設定します。これは、この関数が呼び出されたテストファイルにのみ影響します。このメソッドが呼び出されない場合のデフォルトのタイムアウト間隔は5秒です。

例

jest.setTimeout(1000); // 1 second

ヒント

同じファイル内の異なるテストにタイムアウト間隔を設定するには、個々のテストのtimeoutオプションを使用します。

すべてのテストファイルのタイムアウトを設定する場合は、testTimeout設定オプションを使用します。

メソッド
モックモジュール
モック関数
フェイクタイマー
その他

メソッド​

モックモジュール​

jest.disableAutomock()​

jest.enableAutomock()​

jest.createMockFromModule(moduleName)​

Function​

Class​

Object​

Array​

Primitives​

jest.mock(moduleName, factory, options)​

jest.Mocked<Source>​

jest.mocked(source, options?)​

jest.unmock(moduleName)​

jest.deepUnmock(moduleName)​

jest.doMock(moduleName, factory, options)​

jest.dontMock(moduleName)​

jest.setMock(moduleName, moduleExports)​

jest.requireActual(moduleName)​

jest.requireMock(moduleName)​

jest.resetModules()​

jest.isolateModules(fn)​

jest.isolateModulesAsync(fn)​

モック関数​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.replaceProperty(object, propertyKey, value)​

jest.spyOn(object, methodName)​

jest.spyOn(object, methodName, accessType?)​

jest.Replaced<Source>​

jest.Spied<Source>​

jest.clearAllMocks()​

jest.resetAllMocks()​

jest.restoreAllMocks()​

フェイクタイマー​

jest.useFakeTimers(fakeTimersConfig?)​

jest.useRealTimers()​

jest.runAllTicks()​

jest.runAllTimers()​

jest.runAllTimersAsync()​

jest.runAllImmediates()​

jest.advanceTimersByTime(msToRun)​

jest.advanceTimersByTimeAsync(msToRun)​

jest.runOnlyPendingTimers()​

jest.runOnlyPendingTimersAsync()​

jest.advanceTimersToNextTimer(steps)​

jest.advanceTimersToNextTimerAsync(steps)​

jest.clearAllTimers()​

jest.getTimerCount()​

jest.now()​

jest.setSystemTime(now?: number | Date)​

jest.getRealSystemTime()​

その他​

jest.getSeed()​

jest.isEnvironmentTornDown()​

jest.retryTimes(numRetries, options?)​

jest.setTimeout(timeout)​

メソッド

モックモジュール

`jest.disableAutomock()`

`jest.enableAutomock()`

`jest.createMockFromModule(moduleName)`

`Function`

`Class`

`Object`

`Array`

`Primitives`

`jest.mock(moduleName, factory, options)`

`jest.Mocked<Source>`

`jest.mocked(source, options?)`

`jest.unmock(moduleName)`

`jest.deepUnmock(moduleName)`

`jest.doMock(moduleName, factory, options)`

`jest.dontMock(moduleName)`

`jest.setMock(moduleName, moduleExports)`

`jest.requireActual(moduleName)`

`jest.requireMock(moduleName)`

`jest.resetModules()`

`jest.isolateModules(fn)`

`jest.isolateModulesAsync(fn)`

モック関数

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

`jest.replaceProperty(object, propertyKey, value)`

`jest.spyOn(object, methodName)`

`jest.spyOn(object, methodName, accessType?)`

`jest.Replaced<Source>`

`jest.Spied<Source>`

`jest.clearAllMocks()`

`jest.resetAllMocks()`

`jest.restoreAllMocks()`

フェイクタイマー

`jest.useFakeTimers(fakeTimersConfig?)`

`jest.useRealTimers()`

`jest.runAllTicks()`

`jest.runAllTimers()`

`jest.runAllTimersAsync()`

`jest.runAllImmediates()`

`jest.advanceTimersByTime(msToRun)`

`jest.advanceTimersByTimeAsync(msToRun)`

`jest.runOnlyPendingTimers()`

`jest.runOnlyPendingTimersAsync()`

`jest.advanceTimersToNextTimer(steps)`

`jest.advanceTimersToNextTimerAsync(steps)`

`jest.clearAllTimers()`

`jest.getTimerCount()`

`jest.now()`

`jest.setSystemTime(now?: number | Date)`

`jest.getRealSystemTime()`

その他

`jest.getSeed()`

`jest.isEnvironmentTornDown()`

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`