26.4

Edit

Configuring Jest

Jestの設定は、プロジェクトの package.json ファイルか、 jest.config.jsファイルまたは --config <path/to/file.js|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,
  };
};

出力される構成は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();
});

Note: Node modules are automatically mocked when you have a manual mock in place (e.g.: __mocks__/lodash.js). More info here.

Note: Core modules, like fs, are not mocked by default. They can be mocked explicitly, like 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

テスト実行中にカバレッジ情報を取得するかどうかを指定します。 Because these retrofits all executed files with coverage collection statements, it may significantly slow down your tests.

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/"]

An array of regexp pattern strings that are matched against all file paths before executing the test. If the file path matches any of the patterns, coverage information will be skipped.

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

coverageProvider [string]

Indicates which provider should be used to instrument code for coverage. Allowed values are babel (default) or 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 が使用できます。

Note: Setting this option overwrites the default values. Add "text" or "text-summary" to see a coverage summary in the console output.

Note: You can pass additional options to the istanbul reporter using the tuple form. 例：

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

For the additional information about the options object shape you can refer to CoverageReporterWithOptions type in the type definitions.

coverageThreshold [object]

デフォルト: undefined

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

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

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

もし glob またはパスが global として指定されていれば、一致したパスのカバレッジデータは全体のカバレッジからは除外され、独自のしきい値が適用されます。 glob へのしきい値はその globs と一致する全てのファイルに適用されます。 If the file specified by path is not found, an error is returned.

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

{
  ...
  "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

This option allows the use of a custom dependency extractor. It must be a node module that exports an object with an extract function. E.g.:

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

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

Allows for a label to be printed alongside a test while it is running. This becomes more useful in multi-project repositories where there can be many jest configuration files. 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

Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process.

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

デフォルト: ['']

Test files are normally ignored from collecting code coverage. With this option, you can overwrite this behavior and include otherwise ignored files in code coverage.

たとえば、次のような .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.

Note: Any global variables that are defined through globalSetup can only be read in globalTeardown. You cannot retrieve globals defined here in your test suites.

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.

maxConcurrency [number]

Default: 5

A number limiting the number of tests that are allowed to run at the same time when using test.concurrent. Any test above this limit will be queued and executed once a slot is released.

moduleDirectories [array<string>]

デフォルト: ["node_modules"]

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

moduleFileExtensions [array<string>]

Default: ["js", "json", "jsx", "ts", "tsx", "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"
    ]
  }
}

The order in which the mappings are defined matters. Patterns are checked one by one until one fits. The most specific rule should be listed first. This is true for arrays of module names as well.

注意: モジュール名を 正規表現^$による境界なしでモジュール名を指定するとエラーの特定が困難となることがあります。 例えば 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

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

Beware: Jest uses node-notifier to display desktop notifications. 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

Specifies notification mode. Requires 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.

projects [array<string | ProjectConfig>]

デフォルト: undefined

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

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

This example configuration will run Jest in the root directory as well as in every folder in the examples directory. You can have an unlimited amount of projects running in the same Jest instance.

プロジェクト機能は、複数の設定や複数のランナーを走らせるためにも使用できます。 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 メソッドを実装したクラスであり、各イベントが発生した場合にこれらのメソッドが呼ばれます。

If custom reporters are specified, the default Jest reporters will be overridden. To keep default reporters, default can be passed as a module name.

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

{
  "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": "browser-resolve"
  }
}

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"

This option allows you to use a custom runner instead of Jest's default test runner. Examples of runners include:

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<->snapshot path. This config option lets you customize where Jest stores snapshot files on disk.

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]

デフォルト: "jsdom"

テスト実行時に使用されるテスト環境を指定します。 Jest のデフォルトの環境は、 jsdom を介したブラウザライクな環境です。 Node環境によるサービスを構築する場合は、 nodeオプションを指定することでnodeライクな環境を代わりに使うことができます。

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

テスト環境のセットアップに使用する独自のモジュールを作成できます。 モジュールは、setup、 teardown および runScript メソッドを持つクラスをエクスポートする必要があります。 変数を this.global オブジェクトに束縛することで、このモジュールからテストスイートに変数を渡すこともできます。つまり、テストスイーツ内でグローバル変数をして使用することができるようになります。

The class may optionally expose an asynchronous handleTestEvent method to bind to events fired by jest-circus. Normally, jest-circus test runner would pause until a promise returned from handleTestEvent gets fulfilled, except for the next events: start_describe_definition, finish_describe_definition, add_hook, add_test or error (for the up-to-date list you can look at 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 it's value set to an empty string. If the pragma is not present, it will not be present in the object.

Note: TestEnvironment is sandboxed. Each test suite will trigger setup/teardown in their own TestEnvironment.

例:

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

  runScript(script) {
    return super.runScript(script);
  }

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

module.exports = CustomEnvironment;

// my-test-suite
let someGlobalObject;

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

testEnvironmentOptions [Object]

デフォルト: {}

testEnvironment に渡されるテスト環境のオプションです。 The relevant options depend on the environment. 例えば、 {userAgent: "Agent/007"} など、 jsdom に与えられたオプションを上書きできます。

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/"]

An array of regexp pattern strings that are matched against all test paths before executing the test. If the test path matches any of the patterns, it will be skipped.

パターン文字列はフルパスに対して照合されます。 <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": bool,
  "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]

デフォルト: jasmine2

This option allows the use of a custom test runner. The default is jasmine2. 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

This option allows you to use a custom sequencer instead of Jest's default. sort may optionally return a 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

This option sets the URL for the jsdom environment. It is reflected in properties such as 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を参照して下さい。

transformIgnorePatterns [array<string>]

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

An array of regexp pattern strings that are matched against all source file paths before transformation. If the test path matches any of the patterns, it will not be transformed.

パターン文字列はフルパスに対して照合されます。 <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.

// [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 →