バージョン: 次へ

Jestオブジェクト

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

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

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

情報

このページの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)`

モジュールが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.

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>`

ドキュメントについてはMock FunctionsページのTypeScript使用法セクションを参照してください。

`jest.mocked(source, options?)`

ドキュメントについてはMock Functionsページの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()を使用して動的にインポートする必要があります。
最後に、動的インポートをサポートする環境が必要です。初期設定についてはUsing Babelを参照してください。その後、Babel設定にプラグインbabel-plugin-dynamic-import-nodeまたは同等のものを追加して、Nodeで動的インポートを有効にします。

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の第二引数は期待されるエクスポートオブジェクトではなく、モジュールファクトリ関数です。

`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.onGenerateMock(cb)`

Jestがモジュールのモックを生成するたびに呼び出されるコールバック関数を登録します。このコールバックにより、モックが他のテストに渡される前に修正できます。

コールバックのパラメータ:

modulePath: string - モック対象モジュールの絶対パス
moduleMock: T - Jestが生成したモジュールのモックオブジェクト。返却前に修正または置換可能

動作:

複数のコールバックが連続する onGenerateMock 呼び出しで登録された場合、登録順に呼び出されます
各コールバックは前のコールバックの出力を moduleMock として受け取ります。これにより同一モックへの複数段階の変換が可能です

jest.onGenerateMock((modulePath, moduleMock) => {
  // Inspect the module name and decide how to transform the mock
  if (modulePath.includes('Database')) {
    // For demonstration, let's replace a method with our own custom mock
    moduleMock.connect = jest.fn().mockImplementation(() => {
      console.log('Connected to mock DB');
    });
  }

  // Return the (potentially modified) mock
  return moduleMock;
});

// Apply mock for module
jest.mock('./Database');

// Later in your tests
import Database from './Database';
// The `Database` mock now has any transformations applied by our callback

メモ

onGenerateMock コールバックは以下の手動モックでは呼び出されません:

__mocks__ フォルダ内のモック
jest.mock('moduleName', () => { ... }) で明示的に提供されたファクトリ

`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.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の使用方法の詳細についてはMock Functionsページを参照してください。

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

スパイ対象メソッドと`using`キーワード

コードベースが"明示的なリソース管理"のトランスパイルを設定している場合（例: TypeScript >= 5.2 または @babel/plugin-proposal-explicit-resource-managementプラグインを使用している場合）、spyOnをusingキーワードと組み合わせて使用できます:

test('logs a warning', () => {
  using spy = jest.spyOn(console, 'warn');
  doSomeThingWarnWorthy();
  expect(spy).toHaveBeenCalled();
});

このコードは次のものと意味的に同等です:

test('logs a warning', () => {
  let spy;
  try {
    spy = jest.spyOn(console, 'warn');
    doSomeThingWarnWorthy();
    expect(spy).toHaveBeenCalled();
  } finally {
    spy.mockRestore();
  }
});

これにより、スパイは現在のコードブロックを抜けると自動的に元の値に復元されます。

さらに一歩進めて、コードブロックを使用してモックをテストの一部に限定することもでき、可読性を損なうことはありません。

test('testing something', () => {
  {
    using spy = jest.spyOn(console, 'warn');
    setupStepThatWillLogAWarning();
  }
  // here, console.warn is already restored to the original value
  // your test can now continue normally
});

メモ

Symbol.disposeが存在しないという警告が表示される場合は、次のコードでポリフィルを追加する必要があります:

if (!Symbol.dispose) {
  Object.defineProperty(Symbol, 'dispose', {
    get() {
      return Symbol.for('nodejs.dispose');
    },
  });
}

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

Jest 22.1.0以降、jest.spyOnメソッドはオプションの第三引数としてaccessType（'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>`

ドキュメントについてはMock FunctionsページのTypeScript Usageセクションを参照してください。

`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?)`

グローバルなDate、performance、time、timer 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()`

グローバルなdate、performance、time、timer 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.jsでは通常process.nextTick経由）の両方を完全に消化します。

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

これはテスト中にsetTimeoutsを同期的に実行し、setTimeout()やsetInterval()のコールバック実行後に発生する挙動を同期的にアサートする場合に特に有用です。詳細はタイマーモックドキュメントを参照してください。

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

requestAnimationFrameでスケジュールされたコールバックを実行するために必要なミリ秒数だけすべてのタイマーを進めます。advanceTimersToNextFrame()はrequestAnimationFrameを使用してスケジュールされたコードを実行する便利な方法です。

情報

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

`jest.clearAllTimers()`

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

つまり、スケジュール済みだがまだ実行されていないタイマーがある場合、それらはクリアされ将来実行される機会が永久に失われます。

`jest.getTimerCount()`

まだ実行されていないフェイクタイマーの数を返します。

`jest.now()`

現在のクロックの時刻をミリ秒で返します。リアルタイマーを使用している場合やDateがモックされている場合はDate.now()と同等です。レガシータイマーなどのその他のケースでは、Date.now()やperformance.now()などのカスタムモックを実装する際に役立ちます。

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

フェイクタイマーが使用する現在のシステム時刻を設定します。プログラム実行中にユーザーがシステムクロックを変更する状況をシミュレートします。現在時刻には影響しますが、jest.setSystemTime()の呼び出し自体がタイマー発火を直接引き起こすことはありません。タイマーはこの関数を呼び出さなかった場合と全く同じタイミングで発火します。

情報

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

`jest.setTimerTickMode(mode)`

フェイクタイマーが時間を進める方法を設定できます。

設定オプション：

type TimerTickMode =
  | {mode: 'manual'}
  | {mode: 'nextAsync'}
  | {mode: 'interval'; delta?: number};

manual: タイマーはティックAPI（jest.advanceTimersByTime(ms), jest.runAllTimers()など）への明示的な手動呼び出しなしでは進みません。
nextAsync: クロックはイベントループを継続的に中断し、モードが変更されるまで次のタイマーを実行します。
interval: これはadvanceTimers: trueをadvanceTimeDeltaと共に指定するのと同じです。デルタが指定されない場合、デフォルトで20が使用されます。

情報

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

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

waitBeforeRetryは再試行前に待機するミリ秒数です。

jest.retryTimes(3, {waitBeforeRetry: 1000});

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

retryImmediatelyオプションは失敗直後にテストを再試行します。このオプションが指定されていない場合、テストはJestがファイル内の他の全テストの実行を終えてから再試行されます。

jest.retryTimes(3, {retryImmediately: 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.onGenerateMock(cb)​

jest.resetModules()​

jest.isolateModules(fn)​

jest.isolateModulesAsync(fn)​

モック関数​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.replaceProperty(object, propertyKey, value)​

jest.spyOn(object, methodName)​

スパイ対象メソッドとusingキーワード​

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.advanceTimersToNextFrame()​

jest.clearAllTimers()​

jest.getTimerCount()​

jest.now()​

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

jest.setTimerTickMode(mode)​

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.onGenerateMock(cb)`

`jest.resetModules()`

`jest.isolateModules(fn)`

`jest.isolateModulesAsync(fn)`

モック関数

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

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

`jest.spyOn(object, methodName)`

スパイ対象メソッドと`using`キーワード

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

`jest.clearAllTimers()`

`jest.getTimerCount()`

`jest.now()`

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

`jest.setTimerTickMode(mode)`

`jest.getRealSystemTime()`

その他

`jest.getSeed()`

`jest.isEnvironmentTornDown()`

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`