next

Edit

Configuring Jest

Jest の構成はプロジェクトの package.json または jest.config.js か jest.config.ts ファイル、または --config <path/to/file.js|ts|cjs|mjs|json> オプションを通して設定できます。 package.json に Jest の構成を保存する場合は、Jest が設定を見つけられるように "jest" キーをトップレベルに設定する必要があります：

{
  "name": "my-project",
  "jest": {
    "verbose": true
  }
}

またはJavaScriptファイルで

// jest.config.js
// Sync object
module.exports = {
  verbose: true,
};

// Or async function
module.exports = async () => {
  return {
    verbose: true,
  };
};

Or through TypeScript (if ts-node is installed):

// jest.config.ts
import type {Config} from '@jest/types';

// Sync object
const config: Config.InitialOptions = {
  verbose: true,
};
export default config;

// Or async function
export default async (): Promise<Config.InitialOptions> => {
  return {
    verbose: true,
  };
};

出力される構成はJSON形式でシリアライズできなければならないことに留意して下さい。

--config オプションを使用した場合、JSON ファイルには "jest" キーを含んではいけません。

{
  "bail": 1,
  "verbose": true
}

オプション

オプションを指定することで package.json内でのJestの動作をコントロールできます。Jestの哲学はそのままでも十分に動作することですが、時としてより強力な設定が必要となることもあるでしょう。

デフォルト

Jest のデフォルトオプションを取得して、必要に応じて展開することができます。

// jest.config.js
const {defaults} = require('jest-config');
module.exports = {
  // ...
  moduleFileExtensions: [...defaults.moduleFileExtensions, 'ts', 'tsx'],
  // ...
};

リファレンス

automock [boolean]

デフォルト: false

このオプションは、テスト内でインポートしたすべてのモジュールを自動的にモックするするように Jest に伝えます。テスト内で使われるすべてのモジュールは、同じ API のシグネチャを持つ限り、他の実装に置き換えることができるということです。

例:

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

test('if utils mocked automatically', () => {
  // Public methods of `utils` are now mock functions
  expect(utils.authorize.mock).toBeTruthy();
  expect(utils.isAuthorized.mock).toBeTruthy();

  // You can provide them with your own implementation
  // or pass the expected return value
  utils.authorize.mockReturnValue('mocked_token');
  utils.isAuthorized.mockReturnValue(true);

  expect(utils.authorize()).toBe('mocked_token');
  expect(utils.isAuthorized('not_wizard')).toBeTruthy();
});

注意：手動モックがある場合、ノードモジュールは自動的にモックされます（例: __mocks__/lodash.js). 詳細はこちら .

デフォルトでは fsのようなコア機能のモジュールはモックされません。それらのモジュールは jest.mock('fs')のように明示的にモックする必要があります。

bail [number | boolean]

デフォルト: 0

デフォルトでは、Jest はすべてのテストを実行し、完了時にすべてのエラーをコンソールに生成します。 bail オプションにより、指定した回数テストが失敗した場合にテストを中止することができます。 true に設定した場合は、 1 に設定するのと同じになります。

cacheDirectory [string]

デフォルト: "/tmp/<path>"

Jestがキャッシュする依存情報を格納するディレクトリを指定します。

Jestはテスト実行中に必要となるかもしれないファイルシステムを集めやすくするため、依存関係のツリーを一度(前もって) 読み込んでキャッシュします。 この設定オプションによりJestがディスク上にキャッシュを格納する場所を指定できます。

clearMocks [boolean]

デフォルト: false

Automatically clear mock calls and instances before every test. Equivalent to calling jest.clearAllMocks() before each test. このオプションは与えられたモックの実装を削除することはしません。

collectCoverage [boolean]

デフォルト: false

テスト実行中にカバレッジ情報を取得するかどうかを指定します。 カバレッジ取得を指定して実行される全てのファイルについて書き換えるので、テストが大幅に遅くなることがあります。

collectCoverageFrom [array]

デフォルト: undefined

カバレッジ情報を取得する対象のファイルを指定する globパターンの配列を設定します。 ファイルが指定されたglobパターンに一致すれば、ファイルにテストが存在せずテストスイートが必要としないファイルであってもカバレッジ情報を収集します。

例:

{
  "collectCoverageFrom": [
    "**/*.{js,jsx}",
    "!**/node_modules/**",
    "!**/vendor/**"
  ]
}

上記の設定ではプロジェクトの rootDir配下の**/node_modules/** または**/vendor/**に一致するものを除いたすべてのファイルからカバレッジ情報を取得します。

注意: このオプションを使用するにはcollectCoverageパラメータがtrueに設定されているか--coverageオプションを付けてjestを実行する必要があります。

Help: If you are seeing coverage output such as...

=============================== Coverage summary ===============================
Statements   : Unknown% ( 0/0 )
Branches     : Unknown% ( 0/0 )
Functions    : Unknown% ( 0/0 )
Lines        : Unknown% ( 0/0 )
================================================================================
Jest: Coverage data for global was not found.

Most likely your glob patterns are not matching any files. Refer to the micromatch documentation to ensure your globs are compatible.

coverageDirectory [string]

デフォルト: undefined

カバレッジ情報を出力するファイルを格納するディレクトリを指定します。

coveragePathIgnorePatterns [array<string>]

デフォルト: ["/node_modules/"]

テスト実行前に全てのファイルのパスに対して照合する正規表現パターンの配列を指定します。指定したパターンのいずれかに一致したファイルはカバレッジ情報が取得されません。

パターン文字列はフルパスに対して照合されます。 <rootDir> 文字列トークンをプロジェクトのルートディレクトリとして指定することで、異なるルートディレクトリを持ちうる異なる環境のファイルを誤って無視してしまうことを防ぐことができます。 例: ["<rootDir>/build/", "<rootDir>/node_modules/"]。

coverageProvider [string]

テストカバレッジの計測に使用するプロバイダを指定します。使用可能な値は babel (デフォルト) または v8 です。

Note that using v8 is considered experimental. V8を使用する場合にはBabelではなく、V8の組み込みのコードカバレッジ機能を使用します。 この機能は十分にテストされておらず、Node の直近のリリースでも改修が加えられています。 ノードの最新バージョン(この執筆時点ではv14)を使用することで、より良い結果が得られるでしょう。

coverageReporters [array<string | [string, options]>]

Default: ["json", "lcov", "text", "clover"]

カバレッジリポートを出力する際に Jest が使用するリポータのリストです。 任意の istanbul reporter が使用できます。

注意: このオプションを設定した場合、既定値は上書きされます。コンソール出力でカバレッジ情報を確認するには"text" または "text-summary"をリストに追加して下さい。

注: タプルを使用して、istanbulレポーターに追加のオプションを渡すことができます。例えば:

["json", ["lcov", {"projectRoot": "../../"}]]

オプション オブジェクトに関する追加情報については、 種類定義 の CoverageReporterWithOptions 型を参照してください。

coverageThreshold [object]

デフォルト: undefined

このオプションはカバレッジ取得結果の最小しきい値を強制的に設定します。 しきい値は、 global、 glob およびディレクトリもしくはファイルパスを指定できます。 しきい値に到達しなかった場合、Jest はテストが失敗したと判定します。 正の値で指定されたしきい値を、最小限求められるカバレッジのパーセンテージとして設定します。 負のしきい値を設定することで、カバーされなかった部分の最大許容量を指定します。

たとえば、以下の設定では、ブランチ、行、関数でカバレッジが 80% を下回るものがあるか、または 10 個以上のステートメントがカバーされていなかった場合、Jest はテストが失敗したと判定します。

{
  ...
  "jest": {
    "coverageThreshold": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": -10
      }
    }
  }
}

もし glob またはパスが global として指定されていれば、一致したパスのカバレッジデータは全体のカバレッジからは除外され、独自のしきい値が適用されます。 glob へのしきい値はその globs と一致する全てのファイルに適用されます。 指定されたパスのファイルが見つからない場合は、エラーが返されます。

例えば、以下の設定では：

{
  ...
  "jest": {
    "coverageThreshold": {
      "global": {
        "branches": 50,
        "functions": 50,
        "lines": 50,
        "statements": 50
      },
      "./src/components/": {
        "branches": 40,
        "statements": 40
      },
      "./src/reducers/**/*.js": {
        "statements": 90
      },
      "./src/api/very-important-module.js": {
        "branches": 100,
        "functions": 100,
        "lines": 100,
        "statements": 100
      }
    }
  }
}

Jest は以下の状況ではテストが失敗したと判断します：

  • ./src/components ディレクトリで、ブランチまたはステートメントのカバレッジが 40% 未満。
  • ./src/reducers/**/*.js のglob表現に一致するファイルの1つのカバレッジが 90% 未満。
  • ./src/api/very-important-module.js ファイルのカバレッジが 100% 未満。
  • 残りのファイルのカバレッジが 50% 未満 (global で設定)。

dependencyExtractor [string]

デフォルト: undefined

このオプションで、独自の依存関係抽出ツールを指定できます。 extract 関数でオブジェクトをエクスポートするnode モジュールである必要があります。例えば:

const crypto = require('crypto');
const fs = require('fs');

module.exports = {
  extract(code, filePath, defaultExtract) {
    const deps = defaultExtract(code, filePath);
    // Scan the file and add dependencies in `deps` (which is a `Set`)
    return deps;
  },
  getCacheKey() {
    return crypto
      .createHash('md5')
      .update(fs.readFileSync(__filename))
      .digest('hex');
  },
};

The extract function should return an iterable (Array, Set, etc.) with the dependencies found in the code.

That module can also contain a getCacheKey function to generate a cache key to determine if the logic has changed and any cached artifacts relying on it should be discarded.

displayName [string, object]

デフォルト: undefined

実行中に、テストの横にラベルを表示できます。 多くの Jest の設定ファイルがあるマルチプロジェクト・リポジトリで役立ちます。 This visually tells which project a test belongs to. Here are sample valid values.

module.exports = {
  displayName: 'CLIENT',
};

or

module.exports = {
  displayName: {
    name: 'CLIENT',
    color: 'blue',
  },
};

As a secondary option, an object with the properties name and color can be passed. This allows for a custom configuration of the background color of the displayName. displayName defaults to white when its value is a string. Jest uses chalk to provide the color. As such, all of the valid options for colors supported by chalk are also supported by jest.

errorOnDeprecated [boolean]

デフォルト: false

廃止された API を呼び出している場合に役に立つエラーメッセージを出力します。アップグレードのプロセスを楽にするのに役立ちます。

extensionsToTreatAsEsm [array<string>]

デフォルト: []

Jest will run .mjs and .js files with nearest package.json's type field set to module as ECMAScript Modules. If you have any other files that should run with native ESM, you need to specify their file extension here.

Note: Jest's ESM support is still experimental, see its docs for more details.

{
  ...
  "jest": {
    "extensionsToTreatAsEsm": [".ts"]
  }
}

extraGlobals [array<string>]

デフォルト: undefined

Test files run inside a vm, which slows calls to global context properties (e.g. Math). With this option you can specify extra properties to be defined inside the vm for faster lookups.

For example, if your tests call Math often, you can pass it by setting extraGlobals.

{
  ...
  "jest": {
    "extraGlobals": ["Math"]
  }
}

forceCoverageMatch [array<string>]

デフォルト: ['']

テストファイル自体は、通常コードカバレッジの収集対象から除外されます。このオプションを使うことで、このふるまいを上書きし、通常は無視されるファイルをコードカバレッジに含めることができます。

たとえば、次のような .t.js 拡張子を持つソースファイルがある時、

// sum.t.js

export function sum(a, b) {
  return a + b;
}

if (process.env.NODE_ENV === 'test') {
  test('sum', () => {
    expect(sum(1, 2)).toBe(3);
  });
}

forceCoverageMatch を設定することで、これらのファイルからカバレッジを集めることができます。

{
  ...
  "jest": {
    "forceCoverageMatch": ["**/*.t.js"]
  }
}

globals [object]

デフォルト: {}

全テスト環境で利用できるグローバル変数の配列を指定します。

例えば、下記の設定はグローバル変数 __DEV__ は全てのテスト環境において trueとなります。

{
  ...
  "jest": {
    "globals": {
      "__DEV__": true
    }
  }
}

（オブジェクトや配列のような）グローバル参照値を指定して一部のコードでテスト中にその値に変更を加える場合は、その変更は異なるテストファイルで実行されるテスト間で保存されない ことに注意して下さい。 In addition, the globals object must be json-serializable, so it can't be used to specify global functions. For that, you should use setupFiles.

globalSetup [string]

デフォルト: undefined

このオプションでは、カスタムのグローバルセットアップモジュールを指定することができます。モジュールでは、すべてのテストスイーツの前に一度だけトリガされる非同期関数をエクスポートします。 This function gets Jest's globalConfig object as a parameter.

Note: A global setup module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project.

注意: globalSetup で定義されているグローバル変数は、 globalTeardownでのみ取得できます。 テストスイートでここで定義したグローバル変数を取得することはできません。

Note: While code transformation is applied to the linked setup-file, Jest will not transform any code in node_modules. This is due to the need to load the actual transformers (e.g. babel or typescript) to perform transformation.

例:

// setup.js
module.exports = async () => {
  // ...
  // Set reference to mongod in order to close the server during teardown.
  global.__MONGOD__ = mongod;
};

// teardown.js
module.exports = async function () {
  await global.__MONGOD__.stop();
};

globalTeardown [string]

デフォルト: undefined

このオプションでは、カスタムのグローバルティアダウンモジュールを指定することができます。モジュールでは、すべてのテストスイーツの後に一度だけトリガされる非同期関数をエクスポートします。 This function gets Jest's globalConfig object as a parameter.

Note: A global teardown module configured in a project (using multi-project runner) will be triggered only when you run at least one test from this project.

Note: The same caveat concerning transformation of node_modules as for globalSetup applies to globalTeardown.

haste [object]

デフォルト: undefined

This will be used to configure the behavior of jest-haste-map, Jest's internal file crawler/cache system. The following options are supported:

type HasteConfig = {
  // Whether to hash files using SHA-1.
  computeSha1?: boolean;
  // The platform to use as the default, e.g. 'ios'.
  defaultPlatform?: string | null;
  // Path to a custom implementation of Haste.
  hasteImplModulePath?: string;
  // All platforms to target, e.g ['ios', 'android'].
  platforms?: Array<string>;
  // Whether to throw on error on module collision.
  throwOnModuleCollision?: boolean;
};

injectGlobals [boolean]

Default: true

Insert Jest's globals (expect, test, describe, beforeEach etc.) into the global environment. If you set this to false, you should import from @jest/globals, e.g.

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

jest.useFakeTimers();

test('some test', () => {
  expect(Date.now()).toBe(0);
});

Note: This option is only supported using the default jest-circus. test runner

maxConcurrency [number]

Default: 5

test.concurrent使用時に同時実行可能なテスト数を指定します。ここで指定した数を超えるテストはキューに入り、スロットが空き次第実行されます。

moduleDirectories [array<string>]

デフォルト: ["node_modules"]

必要なモジュールの格納場所から上方向に再帰的に探索を行うディレクトリ名の配列を指定します。 このオプションを指定することで既定値が上書きされるため、 node_modules内でパッケージの探索を行いたい場合は、他のオプションに加えて次の配列を追加して下さい: ["node_modules", "bower_components"]

moduleFileExtensions [array<string>]

Default: ["js", "jsx", "ts", "tsx", "json", "node"]

An array of file extensions your modules use. If you require modules without specifying a file extension, these are the extensions Jest will look for, in left-to-right order.

We recommend placing the extensions most commonly used in your project on the left, so if you are using TypeScript, you may want to consider moving "ts" and/or "tsx" to the beginning of the array.

moduleNameMapper [object<string, string | array<string>>]

デフォルト: null

A map from regular expressions to module names or to arrays of module names that allow to stub out resources, like images or styles with a single module.

別名にマップされているモジュールはデフォルトでは自動モック機能が有効かどうかに関わらずモックされません。

ファイルパスでrootDirを使いたい場合は、<rootDir>文字列トークンを設定して下さい。

加えて、正規表現によりキャプチャした文字列を数字付きの後方参照を使って代入することができます。

例:

{
  "moduleNameMapper": {
    "^image![a-zA-Z0-9$_-]+$": "GlobalImageStub",
    "^[./a-zA-Z0-9$_-]+\\.png$": "<rootDir>/RelativeImageStub.js",
    "module_name_(.*)": "<rootDir>/substituted_module_$1.js",
    "assets/(.*)": [
      "<rootDir>/images/$1",
      "<rootDir>/photos/$1",
      "<rootDir>/recipes/$1"
    ]
  }
}

マッピングが定義されている順序が重要です。パターンは適合するまで順に一つずつチェックされます。 最も具体的なルールは最初にリストされるべきです。これはモジュール名の配列でも同様です。

注意: モジュール名を 正規表現^$による境界なしでモジュール名を指定するとエラーの特定が困難となることがあります。 例えば relayという表現では relayを名前に含む全てのモジュール名の置換を行います: relay, react-relay そして graphql-relayの全てが指定したスタブに置き換わります。

modulePathIgnorePatterns [array<string>]

デフォルト: []

モジュールローダーから'見える'状態となる前に全てのモジュールパスに対して照合する正規表現の文字列の配列を指定します。 与えられたモジュールのパスがこの正規表現に一致した場合、テスト環境では当該モジュールはrequire()できなくなります。

パターン文字列はフルパスに対して照合されます。 <rootDir> 文字列トークンをプロジェクトのルートディレクトリとして指定することで、異なるルートディレクトリを持ちうる異なる環境のファイルを誤って無視してしまうことを防ぐことができます。 例: [「< rootDir > ビルド/」]。

modulePaths [array<string>]

デフォルト: []

NODE_PATH 環境変数を設定する代わりの API として、modulePaths にはモジュールの依存関係の解決を行う際の追加のロケーションの絶対パスの配列を指定します。 プロジェクトのルートディレクトリへのパスを指定するには<rootDir> 文字列トークンを使用して下さい。 例: ["<rootDir>/app/"]。

notify [boolean]

デフォルト: false

テスト結果の通知機能を有効にします。

注意: Jest は node-notifier を使用してデスクトップ通知を表示します。 On Windows, it creates a new start menu entry on the first use and not display the notification. Notifications will be properly displayed on subsequent runs

notifyMode [string]

Default: failure-change

通知のモードを指定します。notify: true が必要です。

モード

  • always: 常に通知を送ります。
  • failure: テストが失敗した場合に通知を送ります。
  • success: テストが成功した場合に通知を送ります。
  • change: ステータスが変化した場合に通知を送ります。
  • success-change: テストが成功したか、一度失敗した場合に通知を送ります。
  • failure-change: テストが失敗したとき、またはパスするようになった場合に通知を送ります。

preset [string]

デフォルト: undefined

A preset that is used as a base for Jest's configuration. A preset should point to an npm module that has a jest-preset.json or jest-preset.js file at the root.

For example, this preset foo-bar/jest-preset.js will be configured as follows:

{
  "preset": "foo-bar"
}

Presets may also be relative to filesystem paths.

{
  "preset": "./node_modules/foo-bar/jest-preset.js"
}

prettierPath [string]

Default: 'prettier'

Sets the path to the prettier node module used to update inline snapshots.

プロジェクト [array<string | projectconfig>]

デフォルト: undefined

projects設定がパスやglobパターンの配列で与えられた場合、Jestは指定されたプロジェクト全てで同時にテストを実行します。 このオプションはmonorepo構成のプロジェクトや同時に複数のプロジェクトに従事している時に効果を発揮します。

{
  "projects": ["<rootDir>", "<rootDir>/examples/*"]
}

この例の設定ではJestはルートディレクトリと同時にexamples配下の各ディレクトリでテストを実行します。同じJestのインスタンスで無制限に複数のプロジェクトのテストを実行できます。

プロジェクト機能は、複数の設定や複数のランナーを走らせるためにも使用できます。 For this purpose, you can pass an array of configuration objects. たとえば、テストと ESLint (via jest-runner-eslint) の両方を Jest の同じ呼び出しで実行するには、次のような設定を書きます。

{
  "projects": [
    {
      "displayName": "test"
    },
    {
      "displayName": "lint",
      "runner": "jest-runner-eslint",
      "testMatch": ["<rootDir>/**/*.js"]
    }
  ]
}

Note: When using multi-project runner, it's recommended to add a displayName for each project. This will show the displayName of a project next to its tests.

reporters [array<modulename | [modulename, options]>]

デフォルト: undefined

Jestにカスタムレポーターを追加するにはこの設定オプションを指定します。 カスタムレポーターは、 onRunStart、onTestStart、onTestResult、 onRunComplete メソッドを実装したクラスであり、各イベントが発生した場合にこれらのメソッドが呼ばれます。

カスタムレポーターが指定された場合、デフォルトのJestのレポーターは上書きされます。デフォルトのレポーターも併せて使用する場合は、モジュール名にdefaultを指定できます。

以下の設定はデフォルトのレポーターを上書きします。

{
  "reporters": ["<rootDir>/my-custom-reporter.js"]
}

以下の設定はJestが提供するデフォルトのレポーターに加えてカスタムレポーターを使用します。

{
  "reporters": ["default", "<rootDir>/my-custom-reporter.js"]
}

加えて、カスタムレポーターは第2引数にoptionsオプションを渡すことで設定を行うことができます。

{
  "reporters": [
    "default",
    ["<rootDir>/my-custom-reporter.js", {"banana": "yes", "pineapple": "no"}]
  ]
}

カスタムレポーターのモジュールはコンストラクタ引数にGlobalConfigとレポーターオプションをとるクラスとして定義されなければなりません。

レポーターの例:

// my-custom-reporter.js
class MyCustomReporter {
  constructor(globalConfig, options) {
    this._globalConfig = globalConfig;
    this._options = options;
  }

  onRunComplete(contexts, results) {
    console.log('Custom reporter output:');
    console.log('GlobalConfig: ', this._globalConfig);
    console.log('Options: ', this._options);
  }
}

module.exports = MyCustomReporter;
// or export default MyCustomReporter;

カスタムレポーターはgetLastError()メソッドでエラーを返すことでJestを0でない戻り値で終了させることができます。

class MyCustomReporter {
  // ...
  getLastError() {
    if (this._shouldFail) {
      return new Error('my-custom-reporter.js reported an error');
    }
  }
}

For the full list of methods and argument types see Reporter interface in packages/jest-reporters/src/types.ts

resetMocks [boolean]

デフォルト: false

Automatically reset mock state before every test. Equivalent to calling jest.resetAllMocks() before each test. このオプションはあらゆるモックに見せかけの実装を削除させますが、モックを最初の時点の実装に戻すものではありません。

resetModules [boolean]

デフォルト: false

By default, each test file gets its own independent module registry. Enabling resetModules goes a step further and resets the module registry before running each individual test. This is useful to isolate modules for every test so that the local module state doesn't conflict between tests. プログラム内で jest.resetModules()を利用することでも同様のことができます。

resolver [string]

デフォルト: undefined

カスタムのリゾルバを利用する場合はこのオプションを指定します。 このリゾルバは、第1引数に依存関係の解決に用いるパスの文字列を、第2引数に以下の構造のオブジェクトを受け取る関数をエクスポートするnodeモジュールでなければなりません:

{
  "basedir": string,
  "defaultResolver": "function(request, options)",
  "extensions": [string],
  "moduleDirectory": [string],
  "paths": [string],
  "packageFilter": "function(pkg, pkgdir)",
  "rootDir": [string]
}

関数は解決されるべきモジュールへのパスかモジュールが見つからなければエラーを返します。

Note: the defaultResolver passed as an option is the Jest default resolver which might be useful when you write your custom one. 独自のリゾルバと同じ引数を取ります。例: (request, options).

たとえば、Browserifyの "browser" フィールドを利用したい場合は、以下のように設定します。

{
  ...
  "jest": {
    "resolver": "<rootDir>/resolver.js"
  }
}

// resolver.js
const browserResolve = require('browser-resolve');

module.exports = browserResolve.sync;

By combining defaultResolver and packageFilter we can implement a package.json "pre-processor" that allows us to change how the default resolver will resolve modules. For example, imagine we want to use the field "module" if it is present, otherwise fallback to "main":

{
  ...
  "jest": {
    "resolver": "my-module-resolve"
  }
}

// my-module-resolve package

module.exports = (request, options) => {
  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(request, {
    ...options,
    // Use packageFilter to process parsed `package.json` before the resolution (see https://www.npmjs.com/package/resolve#resolveid-opts-cb)
    packageFilter: pkg => {
      return {
        ...pkg,
        // Alter the value of `main` before resolving the package
        main: pkg.module || pkg.main,
      };
    },
  });
};

restoreMocks [boolean]

デフォルト: false

Automatically restore mock state before every test. Equivalent to calling jest.restoreAllMocks() before each test. このオプションを指定することで、あらゆるモックに見せかけの実装を削除させ、モックを最初の時点の実装に戻させることができます。

rootDir [string]

Default: The root of the directory containing your Jest config file or the package.json or the pwd if no package.json is found

Jestがテストとモジュールをその範囲内で探索するルートディレクトリを指定します。 package.jsonにJestの設定を記述してルートディレクトリをリポジトリのルートをしたい場合、この設定のパラメータ値はデフォルトのpackage.jsonが格納されているディレクトリとなります。

多くの場合、リポジトリのどこにソースコードを格納するかによって、 'src' または 'lib'に設定されるでしょう。

パスを指定する他のオプションで'<rootDir>'を文字列トークンとして利用する場合は、このオプションの値を参照することに注意して下さい。 このため、例えばsetupFilesオプションのエントリポイントをルートディレクトリ直下の env-setup.jsファイルとしたい場合は、このオプションの値は ["<rootDir>/env-setup.js"]となるでしょう。

roots [array<string>]

デフォルト: ["<rootDir>"]

Jestがその中でファイルを探索するのに使用するディレクトリのパスを使用します。

Jestに単一のサブディレクトリのみを探索させ(リポジトリ内にsrc/ディレクトリがあるなど)、リポジトリの残りの場所にはアクセスさせたくない場合に有用です。

注意: rootDirが他の設定オプションで再利用されるトークンとして最も頻繁に使われる一方で、roots はJestの内部でテストファイルやソースコードファイルを見つけるのに使われます。 これは node_modules から手動モック用にモジュールを見つける際にも適用されます（__mocks__ も roots の中にある必要があります）。

注意： デフォルトでは、 roots は <rootDir> のみをエントリとして持ちますが、1つのプロジェクトで複数の roots を設定したい場合は、例えば次のように設定します: roots: ["<rootDir>/src/", "<rootDir>/tests/"]。

runner [string]

デフォルト: "jest-runner"

このオプションを使用すると、Jest のデフォルトのテストランナーのかわりに、カスタムのランナーを使用できます。ランナーの例としては、次のものがあります。

Note: The runner property value can omit the jest-runner- prefix of the package name.

テストランナーを書くには、コンストラクタに globalConfig を取り、以下のシグネチャを持つ runTests メソッドを定義したクラスをエクスポートします。

async runTests(
  tests: Array<Test>,
  watcher: TestWatcher,
  onStart: OnTestStart,
  onResult: OnTestSuccess,
  onFailure: OnTestFailure,
  options: TestRunnerOptions,
): Promise<void>

If you need to restrict your test-runner to only run in serial rather than being executed in parallel your class should have the property isSerial to be set as true.

setupFiles [array]

デフォルト: []

A list of paths to modules that run some code to configure or set up the testing environment. Each setupFile will be run once per test file. 各テストは個々の環境でテストを実行するため、これらのスクリプトはテスト環境にてテストコードそれ自身の実行前に直ちに実行されます。

It's also worth noting that setupFiles will execute before setupFilesAfterEnv.

setupFilesAfterEnv [array]

デフォルト: []

A list of paths to modules that run some code to configure or set up the testing framework before each test file in the suite is executed. setupFilesで指定したスクリプトはテストフレームワークを環境にインストールする前に実行されるため、このオプションで指定したスクリプトファイルは環境にテストフレームワークがインストールされた直後のタイミングでコードを実行することができます。

If you want a path to be relative to the root directory of your project, please include <rootDir> inside a path's string, like "<rootDir>/a-configs-folder".

例えばJestはjasmineのAPIにモンキーパッチを当てて動作するjasmineのプラグインをいくつか提供しています。 If you wanted to add even more jasmine plugins to the mix (or if you wanted some custom, project-wide matchers for example), you could do so in these modules.

Note: setupTestFrameworkScriptFile is deprecated in favor of setupFilesAfterEnv.

Example setupFilesAfterEnv array in a jest.config.js:

module.exports = {
  setupFilesAfterEnv: ['./jest.setup.js'],
};

Example jest.setup.js file

jest.setTimeout(10000); // in milliseconds

slowTestThreshold [number]

Default: 5

The number of seconds after which a test is considered as slow and reported as such in the results.

snapshotResolver [string]

デフォルト: undefined

The path to a module that can resolve test<->スナップショットのパスです。このオプションでJest がスナップショットファイルの保存先を設定できます。

Example snapshot resolver module:

module.exports = {
  // resolves from test to snapshot path
  resolveSnapshotPath: (testPath, snapshotExtension) =>
    testPath.replace('__tests__', '__snapshots__') + snapshotExtension,

  // resolves from snapshot to test path
  resolveTestPath: (snapshotFilePath, snapshotExtension) =>
    snapshotFilePath
      .replace('__snapshots__', '__tests__')
      .slice(0, -snapshotExtension.length),

  // Example test path, used for preflight consistency check of the implementation above
  testPathForConsistencyCheck: 'some/__tests__/example.test.js',
};

snapshotSerializers [array<string>]

デフォルト: []

Jestがスナップショットテストに利用するスナップショットのシリアライザーのモジュールのパスのリストを指定します。

Jest は組み込みの JavaScript 型、HTML 要素 (Jest バージョン20.0.0+)、ImmutableJS (Jest バージョン20.0.0+)、そして React 要素に対応したデフォルトのシリアライザーを備えています。 詳細については snapshot test tutorial を参照してください。

シリアライザー モジュールの例:

// my-serializer-module
module.exports = {
  serialize(val, config, indentation, depth, refs, printer) {
    return 'Pretty foo: ' + printer(val.foo);
  },

  test(val) {
    return val && val.hasOwnProperty('foo');
  },
};

printer is a function that serializes a value using existing plugins.

my-serializer-moduleをシリアライザーとして使用する場合は、下記のような設定になります。

{
  ...
  "jest": {
    "snapshotSerializers": ["my-serializer-module"]
  }
}

最終的にテストは下記のようになります:

test(() => {
  const bar = {
    foo: {
      x: 1,
      y: 2,
    },
  };

  expect(bar).toMatchSnapshot();
});

レンダリングされたスナップショット:

Pretty foo: Object {
  "x": 1,
  "y": 2,
}

シリアライザーの依存関係を暗黙的から明示的なものにするには、Jest の設定に snapshotSerializers へのパスを追加する代わりに、expect.addSnapshotSerializer を呼び出してテストファイルに対応するモジュールを追加することもできます。

More about serializers API can be found here.

testEnvironment [string]

Default: "node"

テスト実行時に使用されるテスト環境を指定します。 The default environment in Jest is a Node.js environment. If you are building a web app, you can use a browser-like environment through jsdom instead.

By adding a @jest-environment docblock at the top of the file, you can specify another environment to be used for all tests in that file:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

テスト環境のセットアップに使用する独自のモジュールを作成できます。 The module must export a class with setup, teardown and getVmContext methods. 変数を this.global オブジェクトに束縛することで、このモジュールからテストスイートに変数を渡すこともできます。つまり、テストスイーツ内でグローバル変数をして使用することができるようになります。

The class may optionally expose an asynchronous handleTestEvent method to bind to events fired by jest-circus. 通常、jest-circusテストランナーはhandleTestEventの以下のイベントを除く非同期処理の完了を待ちます：start_describe_definition, finish_describe_definition, add_hook, add_test もしくは error (最新の一覧については SyncEvent type in the types definitions を参照) That is caused by backward compatibility reasons and process.on('unhandledRejection', callback) signature, but that usually should not be a problem for most of the use cases.

Any docblock pragmas in test files will be passed to the environment constructor and can be used for per-test configuration. If the pragma does not have a value, it will be present in the object with its value set to an empty string. If the pragma is not present, it will not be present in the object.

To use this class as your custom environment, refer to it by its full path within the project. For example, if your class is stored in my-custom-environment.js in some subfolder of your project, then the annotation might looke like this:

/**
 * @jest-environment ./src/test/my-custom-environment
 */

注意：テスト環境はサンドボックス化されます。各テストスイートは、設定と破棄を自身のテスト環境で実行します。

例:

// my-custom-environment
const NodeEnvironment = require('jest-environment-node');

class CustomEnvironment extends NodeEnvironment {
  constructor(config, context) {
    super(config, context);
    this.testPath = context.testPath;
    this.docblockPragmas = context.docblockPragmas;
  }

  async setup() {
    await super.setup();
    await someSetupTasks(this.testPath);
    this.global.someGlobalObject = createGlobalObject();

    // Will trigger if docblock contains @my-custom-pragma my-pragma-value
    if (this.docblockPragmas['my-custom-pragma'] === 'my-pragma-value') {
      // ...
    }
  }

  async teardown() {
    this.global.someGlobalObject = destroyGlobalObject();
    await someTeardownTasks();
    await super.teardown();
  }

  getVmContext() {
    return super.getVmContext();
  }

  async handleTestEvent(event, state) {
    if (event.name === 'test_start') {
      // ...
    }
  }
}

module.exports = CustomEnvironment;

// my-test-suite
/**
 * @jest-environment ./my-custom-environment
 */
let someGlobalObject;

beforeAll(() => {
  someGlobalObject = global.someGlobalObject;
});

testEnvironmentOptions [Object]

デフォルト: {}

testEnvironment に渡されるテスト環境のオプションです。 The relevant options depend on the environment. For example, you can override options given to jsdom such as {userAgent: "Agent/007"}.

testFailureExitCode [number]

デフォルト: 1

The exit code Jest returns on test failure.

Note: This does not change the exit code in the case of Jest errors (e.g. invalid configuration).

testMatch [array<string>]

(default: [ "**/__tests__/**/*.[jt]s?(x)", "**/?(*.)+(spec|test).[jt]s?(x)" ])

テストファイルを検出するのにJestが使用するglobパターンを指定します。 By default it looks for .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any files with a suffix of .test or .spec (e.g. Component.test.js or Component.spec.js). test.js または spec.js といったファイルについても同様に見つけます。

See the micromatch package for details of the patterns you can specify.

See also testRegex [string | array<string>], but note that you cannot specify both options.

testPathIgnorePatterns [array<string>]

デフォルト: ["/node_modules/"]

テスト実行前に全てのファイルのパスに対して照合する正規表現パターンの配列を指定します。テストパスがパターンのいずれかにマッチした場合、そのテストはスキップされます。

パターン文字列はフルパスに対して照合されます。 <rootDir> 文字列トークンをプロジェクトのルートディレクトリとして指定することで、異なるルートディレクトリを持ちうる異なる環境のファイルを誤って無視してしまうことを防ぐことができます。 例: ["<rootDir>/build/", "<rootDir>/node_modules/"]。

testRegex [string | array<string>]

Default: (/__tests__/.*|(\\.|/)(test|spec))\\.[jt]sx?$

The pattern or patterns Jest uses to detect test files. By default it looks for .js, .jsx, .ts and .tsx files inside of __tests__ folders, as well as any files with a suffix of .test or .spec (e.g. Component.test.js or Component.spec.js). test.js または spec.js といったファイルについても同様に見つけます。 See also testMatch [array<string>], but note that you cannot specify both options.

以下はデフォルトの正規表現を可視化したものです。

├── __tests__
│   └── component.spec.js # test
│   └── anything # test
├── package.json # not test
├── foo.test.js # test
├── bar.spec.jsx # test
└── component.js # not test

Note: testRegex will try to detect test files using the absolute file path, therefore, having a folder with a name that matches it will run all the files as tests

testResultsProcessor [string]

デフォルト: undefined

独自の results processor を利用する場合はこのオプションを指定します。 results processor は、以下の構造のオブジェクトを第一引数として期待する関数をエクスポートする node モジュールで、引数に取ったオブジェクトを返す必要があります：

{
  "success": boolean,
  "startTime": epoch,
  "numTotalTestSuites": number,
  "numPassedTestSuites": number,
  "numFailedTestSuites": number,
  "numRuntimeErrorTestSuites": number,
  "numTotalTests": number,
  "numPassedTests": number,
  "numFailedTests": number,
  "numPendingTests": number,
  "numTodoTests": number,
  "openHandles": Array<Error>,
  "testResults": [{
    "numFailingTests": number,
    "numPassingTests": number,
    "numPendingTests": number,
    "testResults": [{
      "title": string (message in it block),
      "status": "failed" | "pending" | "passed",
      "ancestorTitles": [string (message in describe blocks)],
      "failureMessages": [string],
      "numPassingAsserts": number,
      "location": {
        "column": number,
        "line": number
      }
    },
    ...
    ],
    "perfStats": {
      "start": epoch,
      "end": epoch
    },
    "testFilePath": absolute path to test file,
    "coverage": {}
  },
  ...
  ]
}

testRunner [string]

Default: jest-circus/runner

This option allows the use of a custom test runner. The default is jest-circus. A custom test runner can be provided by specifying a path to a test runner implementation.

テストランナーのモジュールは、下記のシグネチャを持つ関数をエクスポートしなければなりません:

function testRunner(
  globalConfig: GlobalConfig,
  config: ProjectConfig,
  environment: Environment,
  runtime: Runtime,
  testPath: string,
): Promise<TestResult>;

このような関数の例は、デフォルトの jasmine2 test runner packageで確認できます。

testSequencer [string]

Default: @jest/test-sequencer

このオプションを使用すると、Jest の標準のものに代わり独自のシーケンサーを指定できます。 sort オプションで Promise を返すことができます。

例:

Sort test path alphabetically.

// testSequencer.js
const Sequencer = require('@jest/test-sequencer').default;

class CustomSequencer extends Sequencer {
  sort(tests) {
    // Test structure information
    // https://github.com/facebook/jest/blob/6b8b1404a1d9254e7d5d90a8934087a9c9899dab/packages/jest-runner/src/types.ts#L17-L21
    const copyTests = Array.from(tests);
    return copyTests.sort((testA, testB) => (testA.path > testB.path ? 1 : -1));
  }
}

module.exports = CustomSequencer;

Jest の設定ファイルで以下のように使用します：

{
  "testSequencer": "path/to/testSequencer.js"
}

testTimeout [number]

Default: 5000

Default timeout of a test in milliseconds.

testURL [string]

Default: http://localhost

このオプションは、jsdom 環境の URL を指定します。location.href などのプロパティに反映されます。

timers [string]

デフォルト: real

この値を legacy または fake に設定すると、 setTimeoutなどの関数に偽のタイマーを使用できます。 偽のタイマーはテストでは待ちたくないような長いタイムアウト時間を設定するようなコードがある時に役立ちます。

値が modernの場合、Jest 独自のレガシーな実装の代わりに@sinonjs/fake-timers が使用されます。 Jest のバージョン27 では、こちらがデフォルトの実装になります。

transform [object<string, pathToTransformer | [pathToTransformer, object]>]

Default: {"\\.[jt]sx?$": "babel-jest"}

正規表現からtransformerへのパスへのマップを指定します。 transformerはソースファイルを変換する同期処理を行う関数を提供するモジュールです。 For example, if you wanted to be able to use a new language feature in your modules or tests that aren't yet supported by node, you might plug in one of many compilers that compile a future version of JavaScript to a current one. 例: examples/typescript の例や webpack tutorial を参照してください。

Examples of such compilers include:

You can pass configuration to a transformer like {filePattern: ['path-to-transformer', {options}]} For example, to configure babel-jest for non-default behavior, {"\\.js$": ['babel-jest', {rootMode: "upward"}]}

Note: a transformer is only run once per file unless the file has changed. During the development of a transformer it can be useful to run Jest with --no-cache to frequently delete Jest's cache.

Note: when adding additional code transformers, this will overwrite the default config and babel-jest is no longer automatically loaded. If you want to use it to compile JavaScript or Typescript, it has to be explicitly defined by adding {"\\.[jt]sx?$": "babel-jest"} to the transform property. babel-jest pluginを参照して下さい。

A transformer must be an object with at least a process function, and it's also recommended to include a getCacheKey function. If your transformer is written in ESM you should have a default export with that object.

transformIgnorePatterns [array<string>]

Default: ["/node_modules/", "\\.pnp\\.[^\\\/]+$"]

変換前に全てのソースコードファイルのパスに対して照合する正規表現パターンの配列を指定します。パスがパターンのいずれかにマッチした場合、そのファイルは変換されません。

パターン文字列はフルパスに対して照合されます。 <rootDir> 文字列トークンをプロジェクトのルートディレクトリとして指定することで、異なるルートディレクトリを持ちうる異なる環境のファイルを誤って無視してしまうことを防ぐことができます。

例:["<rootDir>/bower_components/", "<rootDir>/node_modules/"]。

Sometimes it happens (especially in React Native or TypeScript projects) that 3rd party modules are published as untranspiled. Since all files inside node_modules are not transformed by default, Jest will not understand the code in these modules, resulting in syntax errors. To overcome this, you may use transformIgnorePatterns to allow transpiling such modules. You'll find a good example of this use case in React Native Guide.

unmockedModulePathPatterns [array<string>]

デフォルト: []

モジュールローダーが自動的にモック返す前に全てのモジュールに対して照合する正規表現パターンの配列を指定します。 モジュールのパスがリスト中のいずれかのパターンにマッチした場合、モジュールローダーによる自動的なモック化は行われません。

このオプションは(underscore/lo-dashなどのような) ほぼ常にプライベートな処理の実装には、ほぼいつも利用される一般的に'ユーティリティ' モジュールに関して役に立ちます。 出来るだけこのリストを小さく保ち、個々のテスト内でjest.mock()/jest.unmock()を常に明示的に使用することが大抵の場合でベストプラクティスとなります。 明示的にテスト前にセットアップを行うことで、テストを読む他の人がそのテストがなぜその環境で実行されるのかを理解するのがとても簡単にになります。

個々のテストにおいて、テストファイルの先頭でjest.mock()を明示的に呼び出す事でこの設定を上書きすることが可能です。

verbose [boolean]

デフォルト: false

Indicates whether each individual test should be reported during the run. All errors will also still be shown on the bottom after execution. Note that if there is only one test file being run it will default to true.

watchPathIgnorePatterns [array<string>]

デフォルト: []

ウォッチモードでテストを再実行する前に、全てのソースファイルのパスと照合させる正規表現パターンの配列です。 ファイルのパスがパターンのどれかに一致していれば、ファイルが更新された際にテストを再実行しません。

正規表現パターンはフルパスに対して照合されます。 <rootDir> 文字列トークンをプロジェクトのルートディレクトリとして指定することで、異なるルートディレクトリを持ちうる異なる環境のファイルを誤って無視してしまうことを防ぐことができます。 例： ["<rootDir>/node_modules/"]

Even if nothing is specified here, the watcher will ignore changes to any hidden files and directories, i.e. files and folders that begin with a dot (.).

watchPlugins [array<string | [string, object]>]

デフォルト: []

This option allows you to use custom watch plugins. Read more about watch plugins here.

Examples of watch plugins include:

Note: The values in the watchPlugins property value can omit the jest-watch- prefix of the package name.

watchman [boolean]

Default: true

Whether to use watchman for file crawling.

// [string]

No default

This option allows comments in package.json. Include the comment text as the value of this key anywhere in package.json.

例:

{
  "name": "my-project",
  "jest": {
    "//": "Comment goes here",
    "verbose": true
  }
}
← The Jest ObjectJest CLI Options →