Jestの設定
Jestの哲学はデフォルトでうまく動作することですが、時にはより細かい設定が必要になることもあります。
設定は、専用の JavaScript、TypeScript、または JSON ファイルで定義することをおすすめします。 ファイル名が jest.config.js|ts|mjs|cjs|json
の場合、ファイルは自動的に発見されます。 --config
フラグを使用すると、ファイルに明示的なパスを渡すことができます。
出力される構成は、常に JSON 形式でシリアライズ可能でなければならないことに注意してください。
設定ファイルは、次のようにオブジェクトをエクスポートするだけです。
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
verbose: true,
};
module.exports = config;
import type {Config} from 'jest';
const config: Config = {
verbose: true,
};
export default config;
または、オブジェクトを返す関数をエクスポートします。
- JavaScript
- TypeScript
/** @returns {Promise<import('jest').Config>} */
module.exports = async () => {
return {
verbose: true,
};
};
import type {Config} from 'jest';
export default async (): Promise<Config> => {
return {
verbose: true,
};
};
TypeScript 設定ファイルを読み込むために、Jest は ts-node
を必要とします。 このパッケージがプロジェクトにインストールされていることを確認してください。
設定は JSON ファイルにプレーンオブジェクトとし て保存することもできます。
{
"bail": 1,
"verbose": true
}
その他には、Jest の設定をプロジェクトの package.json
の "jest"
キーで定義することもできます。
{
"name": "my-project",
"jest": {
"verbose": true
}
}
オプション
Jest のデフォルトを jest-config
から取得し、次のように必要に応じて拡張できます。
- JavaScript
- TypeScript
const {defaults} = require('jest-config');
/** @type {import('jest').Config} */
const config = {
moduleFileExtensions: [...defaults.moduleFileExtensions, 'mts', 'cts'],
};
module.exports = config;
import type {Config} from 'jest';
import {defaults} from 'jest-config';
const config: Config = {
moduleFileExtensions: [...defaults.moduleFileExtensions, 'mts'],
};
export default config;
automock
[boolean]bail
[number | boolean]cacheDirectory
[string]clearMocks
[boolean]collectCoverage
[boolean]collectCoverageFrom
[array]coverageDirectory
[string]coveragePathIgnorePatterns
[array<string>]coverageProvider
[string]coverageReporters
[array<string | [string, options]>]coverageThreshold
[object]dependencyExtractor
[string]displayName
[string, object]errorOnDeprecated
[boolean]extensionsToTreatAsEsm
[array<string>]fakeTimers
[object]forceCoverageMatch
[array<string>]globals
[object]globalSetup
[string]globalTeardown
[string]haste
[object]injectGlobals
[boolean]maxConcurrency
[number]maxWorkers
[number | string]moduleDirectories
[array<string>]moduleFileExtensions
[array<string>]moduleNameMapper
[object<string, string | array<string>>]modulePathIgnorePatterns
[array<string>]modulePaths
[array<string>]notify
[boolean]notifyMode
[string]preset
[string]prettierPath
[string]projects
[array<string | ProjectConfig>]reporters
[array<moduleName | [moduleName, options]>]resetMocks
[boolean]resetModules
[boolean]resolver
[string]restoreMocks
[boolean]rootDir
[string]roots
[array<string>]runner
[string]sandboxInjectedGlobals
[array<string>]setupFiles
[array]setupFilesAfterEnv
[array]showSeed
[boolean]slowTestThreshold
[number]snapshotFormat
[object]snapshotResolver
[string]snapshotSerializers
[array<string>]testEnvironment
[string]testEnvironmentOptions
[Object]testFailureExitCode
[number]testMatch
[array<string>]testPathIgnorePatterns
[array<string>]testRegex
[string | array<string>]testResultsProcessor
[string]testRunner
[string]testSequencer
[string]testTimeout
[number]transform
[object<string, pathToTransformer | [pathToTransformer, object]>]transformIgnorePatterns
[array<string>]unmockedModulePathPatterns
[array<string>]verbose
[boolean]watchPathIgnorePatterns
[array<string>]watchPlugins
[array<string | [string, Object]>]watchman
[boolean]workerIdleMemoryLimit
[number|string]//
[string]
リファレンス
automock
[boolean]
デフォルト: false
このオプションにより、Jestはインポートされたすべてのモジュールを自動的にモックします。 テストで使用されるすべてのモジュールは、APIのインターフェースを維持したまま代替の実装を持つことになります。
例:
export default {
authorize: () => 'token',
isAuthorized: secret => secret === 'wizard',
};
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();
});
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.
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パターンに一致すれば、ファイルにテストが存在せずテストスイートが必要としないファイルであってもカバレッジ情報を収集します。
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
collectCoverageFrom: [
'**/*.{js,jsx}',
'!**/node_modules/**',
'!**/vendor/**',
],
};
module.exports = config;
import type {Config} from 'jest';
const config: Config = {
collectCoverageFrom: [
'**/*.{js,jsx}',
'!**/node_modules/**',
'!**/vendor/**',
],
};
export default config;
上記の設定ではプロジェクトの rootDir
配下の**/node_modules/**
または**/vendor/**
に一致するものを除いたすべてのファイルからカバレッジ情報を取得します。
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
.
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.
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:
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
};
module.exports = config;
import type {Config} from 'jest';
const config: Config = {
coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
};
export default 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:
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
coverageThreshold: {
global: {
branches: 80,
functions: 80,
lines: 80,
statements: -10,
},
},
};
module.exports = config;
import type {Config} from 'jest';
const config: Config = {
coverageThreshold: {
global: {
branches: 80,
functions: 80,
lines: 80,
statements: -10,
},
},
};
export default 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:
- JavaScript
- TypeScript
/** @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;
import type {Config} from 'jest';
const config: 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,
},
},
};
export default 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.
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
displayName: 'CLIENT',
};
module.exports = config;
import type {Config} from 'jest';
const config: Config = {
displayName: 'CLIENT',
};
export default 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.
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
displayName: {
name: 'CLIENT',
color: 'blue',
},
};
module.exports = config;
import type {Config} from 'jest';
const config: Config = {
displayName: {
name: 'CLIENT',
color: 'blue',
},
};
export default 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.
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
extensionsToTreatAsEsm: ['.ts'],
};
module.exports = config;
import type {Config} from 'jest';
const config: Config = {
extensionsToTreatAsEsm: ['.ts'],
};
export default config;
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:
- JavaScript
- TypeScript
/** @type {import('jest').Config} */
const config = {
fakeTimers: {
doNotFake: ['nextTick'],
timerLimit: 1000,
},
};
module.exports = config;