メインコンテンツへスキップ
Version: 29.7

Jestの設定

Jestの哲学はデフォルトでうまく動作することですが、時にはより細かい設定が必要になることもあります。

設定は、専用の JavaScript、TypeScript、または JSON ファイルで定義することをおすすめします。 ファイル名が jest.config.js|ts|mjs|cjs|json の場合、ファイルは自動的に発見されます。 --config フラグを使用すると、ファイルに明示的なパスを渡すことができます。

note

出力される構成は、常に JSON 形式でシリアライズ可能でなければならないことに注意してください。

設定ファイルは、次のようにオブジェクトをエクスポートするだけです。

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

module.exports = config;

または、オブジェクトを返す関数をエクスポートします。

/** @returns {Promise<import('jest').Config>} */
module.exports = async () => {
  return {
    verbose: true,
  };
};
tip

TypeScript 設定ファイルを読み込む ために、Jest は ts-node を必要とします。 このパッケージがプロジェクトにインストールされていることを確認してください。

設定は JSON ファイルにプレーンオブジェクトとして保存することもできます。

jest.config.json
{
  "bail": 1,
  "verbose": true
}

その他には、Jest の設定をプロジェクトの package.json の "jest" キーで定義することもできます。

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

オプション​

info

Jest のデフォルトを jest-config から取得し、次のように必要に応じて拡張できます。

const {defaults} = require('jest-config');

/** @type {import('jest').Config} */
const config = {
  moduleFileExtensions: [...defaults.moduleFileExtensions, 'mts', 'cts'],
};

module.exports = config;

リファレンス​

automock [boolean]​

デフォルト: false

このオプションにより、Jestはインポートされたすべてのモジュールを自動的にモックします。 テストで使用されるすべてのモジュールは、APIのインターフェースを維持したまま代替の実装を持つことになります。

例:

utils.js
export default {
  authorize: () => 'token',
  isAuthorized: secret => secret === 'wizard',
};
__tests__/automock.test.js
import utils from '../utils';

test('if utils mocked automatically', () => {
  // `utils` のパブリックメソッドは、ここで mock 関数です
  expect(utils.authorize.mock).toBeTruthy();
  expect(utils.isAuthorized.mock).toBeTruthy();

  // それらに自分の実装を提供するか、
  // 期待される返り値を渡せます
  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.

Node.js core modules, like fs, are not mocked by default. それらのモジュールは jest.mock('fs')のように明示的にモックする必要があります。

bail [number | boolean]​

デフォルト: 0

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

cacheDirectory [string]​

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

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

Jest attempts to scan your dependency tree once (up-front) and cache it in order to ease some of the filesystem churn that needs to happen while running tests. この設定オプションによりJestがディスク上にキャッシュを格納する場所を指定できます。

clearMocks [boolean]​

デフォルト: false

各テストの実行前に、モックコール、インスタンス、コンテキスト、結果を自動的にクリアします。 Equivalent to calling jest.clearAllMocks() before each test. このオプションは与えられたモックの実装を削除することはしません。

collectCoverage [boolean]​

デフォルト: false

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

Jest ships with two coverage providers: babel (default) and v8. See the coverageProvider option for more details.

info

The babel and v8 coverage providers use /* istanbul ignore next */ and /* c8 ignore next */ comments to exclude lines from coverage reports, respectively. For more information, you can view the istanbuljs documentation and the c8 documentation.

collectCoverageFrom [array]​

デフォルト: undefined

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

/** @type {import('jest').Config} */
const config = {
  collectCoverageFrom: [
    '**/*.{js,jsx}',
    '!**/node_modules/**',
    '!**/vendor/**',
  ],
};

module.exports = config;

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

tip

Each glob pattern is applied in the order they are specified in the config. For example ["!**/__tests__/**", "**/*.js"] will not exclude __tests__ because the negation is overwritten with the second pattern. In order to make the negated glob work in this example it has to come after **/*.js.

note

This option requires collectCoverage to be set to true or Jest to be invoked with --coverage.

ヘルプ:

以下のようなカバレッジ出力が表示されている場合は、

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

The directory where Jest should output its coverage files.

coveragePathIgnorePatterns [array<string>]​

Default: ["/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.

These pattern strings match against the full path. Use the <rootDir> string token to include the path to your project's root directory to prevent it from accidentally ignoring all of your files in different environments that may have different root directories. Example: ["<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.

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

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

A list of reporter names that Jest uses when writing coverage reports. Any istanbul reporter can be used.

tip

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

Additional options can be passed using the tuple form. For example, you may hide coverage report lines for all fully-covered files:

/** @type {import('jest').Config} */
const config = {
  coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
};

module.exports = config;

オプションのオブジェクトの形の詳細な情報については、型定義 内の CoverageReporterWithOptions を参照してください。

coverageThreshold [object]​

デフォルト: undefined

This will be used to configure minimum threshold enforcement for coverage results. Thresholds can be specified as global, as a glob, and as a directory or file path. If thresholds aren't met, jest will fail. Thresholds specified as a positive number are taken to be the minimum percentage required. Thresholds specified as a negative number represent the maximum number of uncovered entities allowed.

For example, with the following configuration jest will fail if there is less than 80% branch, line, and function coverage, or if there are more than 10 uncovered statements:

/** @type {import('jest').Config} */
const config = {
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: -10,
    },
  },
};

module.exports = config;

If globs or paths are specified alongside global, coverage data for matching paths will be subtracted from overall coverage and thresholds will be applied independently. Thresholds for globs are applied to all files matching the glob. If the file specified by path is not found, an error is returned.

For example, with the following configuration:

/** @type {import('jest').Config} */
const config = {
  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,
    },
  },
};

module.exports = config;

Jest will fail if:

  • ./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 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]​

default: 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.

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

module.exports = config;

Alternatively, 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.

/** @type {import('jest').Config} */
const config = {
  displayName: {
    name: 'CLIENT',
    color: 'blue',
  },
};

module.exports = config;

errorOnDeprecated [boolean]​

デフォルト: false

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

extensionsToTreatAsEsm [array<string>]​

Default: []

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.

/** @type {import('jest').Config} */
const config = {
  extensionsToTreatAsEsm: ['.ts'],
};

module.exports = config;
caution

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

fakeTimers [object]​

Default: {}

The fake timers may be useful when a piece of code sets a long timeout that we don't want to wait for in a test. For additional details see Fake Timers guide and API documentation.

This option provides the default configuration of fake timers for all tests. Calling jest.useFakeTimers() in a test file will use these options or will override them if a configuration object is passed. For example, you can tell Jest to keep the original implementation of process.nextTick() and adjust the limit of recursive timers that will be run:

/** @type {import('jest').Config} */
const config = {
  fakeTimers: {
    doNotFake: ['nextTick'],
    timerLimit: 1000,
  },
};

module.exports = config;
fakeTime.test.js
// install fake timers for this file using the options from Jest configuration
jest.useFakeTimers();

test('increase the limit of recursive timers for this and following tests', () => {
  jest.useFakeTimers({timerLimit: 5000});
  // ...
});
tip

Instead of including jest.useFakeTimers() in each test file, you can enable fake timers globally for all tests in your Jest configuration:

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

module.exports = config;

Configuration options:

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

type ModernFakeTimersConfig = {
  /**
   * 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>;
  /** Whether fake timers should be enabled for all test files. The default is `false`. */
  enableGlobally?: boolean;
  /**
   * 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;
  /** Maximum number of recursive timers that will be run. The default is `100_000` timers. */
  timerLimit?: number;
};
Legacy Fake Timers

For some reason you might have to use legacy implementation of fake timers. Here is how to enable it globally (additional options are not supported):

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

module.exports = config;

forceCoverageMatch [array<string>]​

Default: ['']

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.

For example, if you have tests in source files named with .t.js extension as following:

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

You can collect coverage from those files with setting forceCoverageMatch.

/** @type {import('jest').Config} */
const config = {
  forceCoverageMatch: ['**/*.t.js'],
};

module.exports = config;

globals [object]​

Default: {}

A set of global variables that need to be available in all test environments.

For example, the following would create a global __DEV__ variable set to true in all test environments:

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

module.exports = config;
note

ここで (オブジェクトや配列のような) グローバルな参照値を指定して、一部のコードでテスト中にその値に変更を加える場合は、その変更は異なるテストファイルで実行されるテスト間で保存されないことに注意してください。 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 option allows the use of a custom global setup module, which must export a function (it can be sync or async). この関数はすべてのテストスイートの前に一度トリガーされ、Jest の globalConfig と projectConfig の2つの引数を受け取ります。

info

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.

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

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 function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPattern);
  console.log(projectConfig.cache);

  // Set reference to mongod in order to close the server during teardown.
  globalThis.__MONGOD__ = mongod;
};
teardown.js
module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPattern);
  console.log(projectConfig.cache);

  await globalThis.__MONGOD__.stop();
};

globalTeardown [string]​

デフォルト: undefined

This option allows the use of a custom global teardown module which must export a function (it can be sync or async). この関数はすべてのテストスイートの後に一度トリガーされ、Jest の globalConfig と projectConfig の2つの引数を受け取ります。

info

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.

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;
  /** Force use of Node's `fs` APIs rather than shelling out to `find` */
  forceNodeFilesystemAPI?: boolean;
  /**
   * Whether to follow symlinks when crawling for files.
   *   This options cannot be used in projects which use watchman.
   *   Projects with `watchman` set to true will error if this option is set to true.
   */
  enableSymlinks?: boolean;
  /** 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;
  /** Custom HasteMap module */
  hasteMapModulePath?: string;
  /** Whether to retain all files, allowing e.g. search for tests in `node_modules`. */
  retainAllFiles?: 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

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.

maxWorkers [number | string]​

テスト実行のためにworker-poolが生成するworkerの最大数を指定します。 In single run mode, this defaults to the number of the cores available on your machine minus one for the main thread. In watch mode, this defaults to half of the available cores on your machine to ensure Jest is unobtrusive and does not grind your machine to a halt. It may be useful to adjust this in resource limited environments like CIs but the defaults should be adequate for most use-cases.

For environments with variable CPUs available, you can use percentage based configuration:

/** @type {import('jest').Config} */
const config = {
  maxWorkers: '50%',
};

module.exports = config;