next

Edit

Configuring Jest

Jest's configuration can be defined in the package.json file of your project, or through a jest.config.js, or jest.config.ts file or through the --config <path/to/file.js|ts|cjs|mjs|json> option. Se você deseja usar o seu arquivo package.json para armazenar a configuração do Jest, a chave "jest" deve ser adicionada no nível superior para que o Jest saiba como encontrar sua configuração:

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

Ou através de 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,
  };
};

Por favor, tenha em mente que a configuração resultante deve ser JSON-serializável.

Ao usar a opção --config, o arquivo JSON não deve conter uma chave "jest":

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

Opções

Estas opções permitem você controlar o comportamento do Jest em seu package.json. A filosofia do Jest é funcionar bem por padrão, mas às vezes você precisa de mais poder de configuração.

Padrões / Defaults

Você pode recuperar opções de padrão do Jest's para expandi-las, se necessário:

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

Referência

automock [boolean]

Padrão: false

Esta opção diz ao Jest que todos os módulos importados em seus testes devem ser simulados (mockados) automaticamente. Todos os módulos utilizados nos seus testes terão uma implementação de substituição, mantendo a superfície da API.

Exemplo:

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

//__tests__/automocking.test.js
import utils from '../utils';

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

Nota: Os Node modules são mockados automaticamente quando você tem um mock manual definido (por exemplo, __mocks__/lodash.js). Mais informações aqui.

Observação: módulos core, como o fs, não são simulados (mocked, em inglês) por padrão. Eles podem ser simulados explicitamente, como em jest.mock('fs').

bail [number | boolean]

Default: 0

By default, Jest runs all tests and produces all errors into the console upon completion. The bail config option can be used here to have Jest stop running tests after n failures. Setting bail to true is the same as setting bail to 1.

cacheDirectory [string]

Padrão: "/tmp/<path>"

O diretório onde o Jest deve armazenar as informações de suas dependências cacheadas.

O Jest tenta escanear sua árvore de dependências uma vez (antecipadamente) e a cacheia para facilitar algumas varreduras no filesystem que precisam acontecer enquanto seus testes estão rodando. Esta opção permite você personalizar aonde o Jest armazena aquela informação cacheada em disco.

clearMocks [boolean]

Padrão: false

Automatically clear mock calls and instances before every test. Equivalent to calling jest.clearAllMocks() before each test. Isso não remove qualquer implementação de simulação (mock, em inglês) que pode ter sido fornecida.

collectCoverage [boolean]

Padrão: false

Indica se a informação de cobertura deve ser coletada enquanto o teste é executado. Devido à isso adicionar a todos os arquivos executados declarações de coleta de cobertura, ele pode tornar os seus testes significantemente mais lentos.

collectCoverageFrom [array]

Padrão: undefined

An array of glob patterns indicating a set of files for which coverage information should be collected. If a file matches the specified glob pattern, coverage information will be collected for it even if no tests exist for this file and it's never required in the test suite.

Exemplo:

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

This will collect coverage information for all the files inside the project's rootDir, except the ones that match **/node_modules/** or **/vendor/**.

Observação: Esta opção requer que collectCoverage seja verdadeiro ou o Jest deverá ser invocado com --coverage.

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]

Padrão: undefined

O diretório onde o Jest deve salvar os seus arquivos de cobertura.

coveragePathIgnorePatterns [array<string>]

Padrão: ["/node_modules/"]

Um array com um padrão regex que corresponda com todos os diretórios antes de executar os testes. Se o diretório corresponder qualquer uma das regex, as informações da coleta serão ignoradas.

Estes padrões de string devem corresponder com o diretório completo. Use a opção <rootDir> para incluir o caminho para o diretório raiz do seu projeto, para evitar que ele ignore acidentalmente todos os seus arquivos em diferentes ambientes que podem ter diretórios raiz diferentes. Exemplo: ["<rootDir>/build/", "<rootDir>/node_modules/"].

coverageProvider [string]

Indica quais providers devem ser usado para tratar os códigos para coverage. Valores permitidos são: babel (default) ou v8.

Note that using v8 is considered experimental. Isto usa o code coverage embutido no V8 em vez de uma baseada no Babel. Isto não está tão bem testado. Também sofreu melhorias com o lançamento das últimas versões do Node. Usando a última versão (v14 no momento desta escrita) produzirá melhores resultado.

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

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

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

Nota: Esta opção sobrescreve os valores padrão. Adicione "text" ou "text-summary" para ver um resumo da cobertura na saída do console.

Note: You can pass additional options to the istanbul reporter using the tuple form. For example:

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

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

coverageThreshold [object]

Padrão: undefined

Isto será usado para configurar a imposição de limite mínimo para os resultados de cobertura. 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:

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

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:

{
  ...
  "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 will fail if:

  • The ./src/components directory has less than 40% branch or statement coverage.
  • One of the files matching the ./src/reducers/**/*.js glob has less than 90% statement coverage.
  • The ./src/api/very-important-module.js file has less than 100% coverage.
  • Every remaining file combined has less than 50% coverage (global).

dependencyExtractor [string]

Padrão: 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]

padrão: 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',
};

ou

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]

Padrão: false

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

extensionsToTreatAsEsm [array<string>]

Padrão: []

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

Padrão: 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>]

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.

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

globals [object]

Padrão: {}

Um conjunto de variáveis globais que precisam estar disponíveis em todos os ambientes de teste.

Por exemplo, a configuração a seguir criaria uma variável global __DEV__ definida como true em todos os ambientes de teste:

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

Note que, se você especificar um valor de referência global (como um objeto ou array) aqui, e algum código modificar este valor durante a execução de um teste, a modificação não será mantida ao longo da execução de testes para outros arquivos de teste. 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]

Padrão: undefined

This option allows the use of a custom global setup module which exports an async function that is triggered once before all test suites. 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.

Exemplo:

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

Padrão: undefined

This option allows the use of a custom global teardown module which exports an async function that is triggered once after all test suites. 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]

Padrão: 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

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

Padrão: ["/node_modules/"]

Uma array de nomes de diretórios a serem pesquisados recursivamente a partir da localização do módulo requerente. Setting this option will override the default, if you wish to still search node_modules for packages include it along with any other options: ["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>>]

Padrão: 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.

Módulos que são mapeados para um alias são não simuláveis por padrão, independentemente se auto simulação (automocking, em inglês) está habilitado ou não.

Use o token string <rootDir> para se referir ao valor rootDir se você quiser usar caminhos de arquivo.

Além disso, você pode substituir os grupos regex capturados usando referências anteriores numeradas.

Exemplo:

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

Nota: Se você fornecer o nome do módulo sem limites ^$ pode causar erros difíceis de detectar. Por exemplo, o relay irá substituir todos os módulos que contêm o relay como uma subsequência de caracteres em seu nome: relay, react-relay e graphql-relay vão todos serem apontados para seu esboço.

modulePathIgnorePatterns [array<string>]

Padrão: []

Uma array de sequências de padrões regexp que são comparados contra todos os caminhos de módulo, antes desses caminhos serem considerados 'visíveis' para o carregador de módulos. Se o caminho de um determinado módulo coincide com qualquer um dos padrões, não será capaz de dar require() no ambiente de teste.

Estes padrões de string devem corresponder com o diretório completo. Use a opção <rootDir> para incluir o caminho para o diretório raiz do seu projeto, para evitar que ele ignore acidentalmente todos os seus arquivos em diferentes ambientes que podem ter diretórios raiz diferentes. Exemplo: ["<rootDir>/build/"].

modulePaths [array<string>]

Padrão: []

An alternative API to setting the NODE_PATH env variable, modulePaths is an array of absolute paths to additional locations to search when resolving modules. Use o token string <rootDir> para incluir o caminho para o diretório raiz do seu projeto. Exemplo: ["<rootDir>/app/"].

notify [boolean]

Padrão: false

Ativa notificações para os resultados do teste.

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.

Modes

  • always: always send a notification.
  • failure: send a notification when tests fail.
  • success: send a notification when tests pass.
  • change: send a notification when the status changed.
  • success-change: send a notification when tests pass or once when it fails.
  • failure-change: send a notification when tests fail or once when it passes.

preset [string]

Padrão: 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>]

Padrão: undefined

Quando a configuração projects é fornecida com um array de caminhos ou padrões glob, Jest executará testes em todos os projetos especificados ao mesmo tempo. Isso é ótimo para monorepos ou quando trabalhando em vários projetos ao mesmo tempo.

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

Este exemplo de configuração irá executar Jest no diretório raiz, bem como em todas as pastas nos diretórios do exemplo. Você pode ter uma quantidade ilimitada de projetos em execução na mesma instância Jest.

The projects feature can also be used to run multiple configurations or multiple runners. For this purpose, you can pass an array of configuration objects. For example, to run both tests and ESLint (via jest-runner-eslint) in the same invocation of 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]>]

Padrão: undefined

Use essa opção de configuração para adicionar reportadores personalizados ao Jest. Um reportador personalizado é uma classe que implementa métodos onRunStart, onTestStart, onTestResult, onRunComplete que serão chamados quando qualquer um desses eventos ocorrer.

Se os reportadores personalizados forem especificados, os reportadores padrão do Jest serão substituídos. Para manter os reportadores padrão, default pode ser passado como um nome de módulo.

Isto irá sobrepor os reportadores padrão:

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

Isto irá usar reportador personalizado além dos reportadores padrão que o Jest fornece:

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

Além disso, os reportadores personalizados podem ser configurados passando um objeto de options como um segundo argumento:

{
  "reporters": [
    "default",
    ["<rootDir>/meu-reportador-customizado.js", {"banana": "yes", "pineapple": "no"}]
  ]
}

Módulos reportador personalizados devem definir uma classe que leva um GlobalConfig e opções de reportador como argumentos do construtor:

Exemplo de reportador:

// 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;

Os reportadores personalizados também podem forçar Jest para sair com código "non-0", retornando um erro de métodos getLastError()

class MyCustomReporter {
  // ...
  getLastError() {
    if (this._shouldFail) {
      return new Error('meu-reportador-customizado.js reportou um erro');
    }
  }
}

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

resetMocks [boolean]

Padrão: false

Automatically reset mock state before every test. Equivalent to calling jest.resetAllMocks() before each test. Isto levará a quaisquer simulações terem suas implementações falsas removidas mas não restaura sua implementação inicial.

resetModules [boolean]

Padrão: 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. Isso pode ser feito por meio de programação usando jest.resetModules().

resolver [string]

Padrão: undefined

Esta opção permite o uso de um resolvedor personalizado. Esse resolvedor deve ser um módulo Node que exporta uma função esperando uma string como o primeiro argumento para resolver o caminho e um objeto com a seguinte estrutura como o segundo argumento:

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

A função deve ou retornar um caminho para o módulo que deve ser resolvido ou lançar um erro se o módulo não pode ser encontrado.

Note: the defaultResolver passed as an option is the Jest default resolver which might be useful when you write your custom one. It takes the same arguments as your custom one, e.g. (request, options).

For example, if you want to respect Browserify's "browser" field, you can use the following configuration:

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

Padrão: false

Automatically restore mock state before every test. Equivalent to calling jest.restoreAllMocks() before each test. This will lead to any mocks having their fake implementations removed and restores their initial implementation.

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

O diretório raiz que Jest deve escanear para testes e módulos dentro. Se você colocar sua configuração do Jest dentro de seu package.json e quer que o diretório raiz seja a raiz de seu repositório, o valor padrão para este parâmetro de configuração será o diretório do package.json.

Muitas vezes, você vai querer definir este para 'src' ou 'lib', correspondente a onde em seu repositório o código é armazenado.

Observe que usando '<rootDir>' com um token string em qualquer outra configuração baseados em caminho irá se referir de volta a esse valor. Então, por exemplo, se você quer que sua configuração de entrada setupFiles aponte para o arquivo env-setup.js na raiz do seu projeto, você poderia definir seu valor como ["<rootDir>/env-setup.js"].

roots [array<string>]

Padrão: ["<rootDir>"]

Uma lista de caminhos para diretórios que Jest deve usar para pesquisar por arquivos.

Há momentos onde você quer que Jest procure apenas em um único sub-diretório (como os casos onde você tem um diretório src/ em seu repositório), mas impedi-lo de acessar o resto do repositório.

Nota: Enquanto rootDir é principalmente usado como um token para ser reutilizado em outras opções de configuração, roots é usado internamente por Jest para localizar arquivos de teste e arquivos fonte. This applies also when searching for manual mocks for modules from node_modules (__mocks__ will need to live in one of the roots).

Nota: Por padrão roots tem uma única entrada <rootDir> mas há casos onde você pode querer ter mútiplos roots dentro de um projeto, por exemplo roots: ["<rootDir>/src/", "<rootDir>/tests/"].

runner [string]

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

To write a test-runner, export a class with which accepts globalConfig in the constructor, and has a runTests method with the signature:

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]

Padrão: []

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. Como cada teste é executado em seu próprio ambiente, esses scripts serão executados no ambiente de teste imediatamente antes de executarem o código de teste em si.

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

setupFilesAfterEnv [array]

Padrão: []

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. Como o setupFiles é executado antes que o framework de teste é instalado no ambiente, este arquivo de script apresenta-lhe a oportunidade de executar algum código imediatamente depois que o framework de teste tiver sido instalado no ambiente.

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

Por exemplo, Jest vem com vários plugins para jasmine que trabalham por "mokey-patching" a API do 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]

Padrão: 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>]

Padrão: []

A list of paths to snapshot serializer modules Jest should use for snapshot testing.

Jest has default serializers for built-in JavaScript types, HTML elements (Jest 20.0.0+), ImmutableJS (Jest 20.0.0+) and for React elements. See snapshot test tutorial for more information.

Exemplo de módulo serializador:

// 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.

To use my-serializer-module as a serializer, configuration would be as follows:

{
  ...
  "jest": {
    "snapshotSerializers": ["meu-modulo-serializador"]
  }
}

Finalmente, os testes seriam os seguintes:

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

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

Snapshot renderizado:

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

Para tornar uma dependência explícita ao invés de implícita, você pode chamar expect.addSnapshotSerializer para adicionar um módulo para um arquivo de teste individual em vez de adicionar o seu caminho para snapshotSerializers na configuração do Jest.

More about serializers API can be found here.

testEnvironment [string]

Default: "node"

O ambiente de teste que será usado para testes. 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();
});

Você pode criar seu próprio módulo que será usado para configurar o ambiente de teste. The module must export a class with setup, teardown and getVmContext methods. You can also pass variables from this module to your test suites by assigning them to this.global object – this will make them available in your test suites as global variables.

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 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
 */

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

Exemplo:

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

Padrão: {}

Test environment options that will be passed to the testEnvironment. The relevant options depend on the environment. For example, you can override options given to jsdom such as {userAgent: "Agent/007"}.

testFailureExitCode [number]

Default: 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)" ])

Os padrões glob que Jest usa para detectar arquivos de teste. 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). It will also find files called test.js or 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>]

Padrão: ["/node_modules/"]

Uma array de padrões strings de regexp que são comparadas contra todos os caminhos de teste antes de executar o teste. Se o caminho de teste coincide com qualquer um dos padrões, ele será ignorado.

Estes padrões de string devem corresponder com o diretório completo. Use a opção <rootDir> para incluir o caminho para o diretório raiz do seu projeto, para evitar que ele ignore acidentalmente todos os seus arquivos em diferentes ambientes que podem ter diretórios raiz diferentes. Exemplo: ["<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). It will also find files called test.js or spec.js. See also testMatch [array<string>], but note that you cannot specify both options.

O seguinte é uma visualização do padrão regex:

├── __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]

Padrão: undefined

This option allows the use of a custom results processor. This processor must be a node module that exports a function expecting an object with the following structure as the first argument and return it:

{
  "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": caminho absoluto para o arquivo,
    "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.

O módulo executador de teste deve exportar uma função com a seguinte assinatura:

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

Um exemplo de tal função pode ser encontrado em nosso padrão 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.

Exemplo:

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;

Use it in your Jest config file like this:

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

testTimeout [number]

Default: 5000

Default timeout of a test in milliseconds.

testURL [string]

Default: http://localhost

Esta opção define a URL para o ambiente jsdom. É refletida em propriedades tais como location.href.

timers [string]

Padrão: real

Setting this value to legacy or fake allows the use of fake timers for functions such as setTimeout. Temporizadores falsos são úteis quando um pedaço de código define um "timeout" longo que não queremos esperar em um teste.

If the value is modern, @sinonjs/fake-timers will be used as implementation instead of Jest's own legacy implementation. This will be the default fake implementation in Jest 27.

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

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

Um mapa de expressões regulares para caminhos para transformadores. Um transformador é um módulo que fornece uma função síncrona para transformar os arquivos de origem. 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. Example: see the examples/typescript example or the 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. Veja 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\\.[^\\\/]+$"]

Uma array de string padrão de regexp são comparados contra todos os caminhos de arquivo de origem, antes da transformação. Se o caminho de teste coincide com qualquer um dos padrões, isso não será transformado.

Estes padrões de string devem corresponder com o diretório completo. Use a opção <rootDir> para incluir o caminho para o diretório raiz do seu projeto, para evitar que ele ignore acidentalmente todos os seus arquivos em diferentes ambientes que podem ter diretórios raiz diferentes.

Exemplo: ["<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>]

Padrão: []

Uma array de strings padrão de regexp que são comparados com todos os módulos antes do carregador de módulo automaticamente retornar uma simulação (mock, em inglês) para eles. Se o caminho de um módulo coincide com qualquer um dos padrões nesta lista, ele não será automaticamente simulado (mocked, em inglês) pelo carregador de módulo.

Isso é útil para alguns módulos 'utility' comumente usados, que quase sempre são usados como detalhes de implementação (como underscore/lo-dash, etc). Geralmente é uma prática recomendada manter essa lista tão pequena quanto possível e sempre usar explicitamente chamadas jest.mock()/jest.unmock() nos testes individuais. Instalação explícita por teste é muito mais fácil para outros leitores do teste raciocinarem sobre o ambiente em que o teste será executado.

É possível substituir essa configuração nos testes individuais chamando explicitamente jest.mock() na parte superior do arquivo de teste.

verbose [boolean]

Padrão: 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>]

Padrão: []

Uma série de padrões de RegExp que são compatíveis com todos os caminhos de arquivos de origem antes de executar novamente os testes no modo de observação. Se o caminho do arquivo corresponder a qualquer um dos padrões, quando ele for atualizado, ele não irá realizar uma nova execução de testes.

Esses padrões coincidem com um caminho completo. Use a opção <rootDir> para incluir o caminho para o diretório raiz do seu projeto, para evitar que ele ignore acidentalmente todos os seus arquivos em diferentes ambientes que podem ter diretórios raiz diferentes. Exemplo: ["<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]>]

Padrão: []

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.

Exemplo:

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