Ir para o conteúdo principal
Versão: Próximo

Configurando o Jest

Tradução Beta Não Oficial

Esta página foi traduzida por PageTurner AI (beta). Não é oficialmente endossada pelo projeto. Encontrou um erro? Reportar problema →

A filosofia do Jest é funcionar perfeitamente por padrão, mas às vezes você precisa de mais poder de configuração.

Recomenda-se definir a configuração em um arquivo dedicado JavaScript, TypeScript ou JSON. O arquivo será descoberto automaticamente se for nomeado jest.config.js|ts|mjs|cjs|cts|json. Você pode usar a flag --config para passar um caminho explícito para o arquivo.

"message": "nota"

Lembre-se que o objeto de configuração resultante deve sempre ser serializável em JSON.

Open Config Examples
  • Using defineConfig from jest you should follow this:
jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  // ... Specify options here.
});
  • You can retrieve Jest's defaults from jest-config to extend them if needed:
jest.config.js
const {defineConfig} = require('jest');
const {defaults} = require('jest-config');

module.exports = defineConfig({
  moduleDirectories: [...defaults.moduleDirectories, 'bower_components'],
});
  • When using a separate Jest config, you can also extend Jest's options from another config file if needed using mergeConfig from jest:
jest.config.js
const {defineConfig, mergeConfig} = require('jest');
const jestConfig = require('./jest.config');

module.exports = mergeConfig(
  jestConfig,
  defineConfig({
    // ... Specify options here.
  }),
);
  • If your Jest config needs to be defined as a function, you can define the config like this:
jest.config.js
const {defineConfig, mergeConfig} = require('jest');
const jestConfig = require('./jest.config');

module.exports = defineConfig(() =>
  mergeConfig(
    jestConfig,
    defineConfig({
      // ... Specify options here.
    }),
  ),
);
  • The configuration also can be stored in a JSON file as a plain object:
jest.config.json
{
  "bail": 1,
  "verbose": true
}
  • Alternatively Jest's configuration can be defined through the "jest" key in the package.json of your project:
package.json
{
  "name": "my-project",
  "jest": {
    "verbose": true
  }
}
  • Also Jest's configuration json file can be referenced through the "jest" key in the package.json of your project:
package.json
{
  "name": "my-project",
  "jest": "./path/to/config.json"
}
"message": "dica"

Para ler arquivos de configuração TypeScript, o Jest requer por padrão ts-node. Você pode substituir esse comportamento adicionando um comentário docblock @jest-config-loader no topo do arquivo. Atualmente, ts-node e esbuild-register são suportados. Certifique-se que ts-node ou o loader especificado esteja instalado.

jest.config.ts
/** @jest-config-loader ts-node */
// or
/** @jest-config-loader esbuild-register */

import {defineConfig} from 'jest';

export default defineConfig({
  verbose: true,
});

Você também pode passar opções para o loader, por exemplo para habilitar transpileOnly.

jest.config.ts
/** @jest-config-loader ts-node */
/** @jest-config-loader-options {"transpileOnly": true} */

import type {defineConfig} from 'jest';

export default defineConfig({
  verbose: true,
});

Opções​

Referência​

automock [booleano]​

Padrão: false

Esta opção informa ao Jest que todos os módulos importados em seus testes devem ser mockados automaticamente. Todos os módulos usados nos testes terão uma implementação substituta, mantendo a superfície da API.

Exemplo:

utils.js
export default {
  authorize: () => 'token',
  isAuthorized: secret => secret === 'wizard',
};
__tests__/automock.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();
});
"message": "nota"

Módulos Node são mockados automaticamente quando você possui um mock manual (ex: __mocks__/lodash.js). Mais informações aqui.

Módulos core do Node.js, como fs, não são mockados por padrão. Eles podem ser mockados explicitamente com jest.mock('fs').

bail [número | booleano]​

Padrão: 0

Por padrão, o Jest executa todos os testes e exibe todos os erros no console ao finalizar. A opção de configuração bail pode ser usada para fazer o Jest parar de executar testes após n falhas. Definir bail como true é equivalente a definir bail como 1.

cacheDirectory [string]​

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

O diretório onde o Jest deve armazenar suas informações de dependência em cache.

O Jest tenta escanear sua árvore de dependências uma vez (inicialmente) e armazená-la em cache para reduzir a sobrecarga do sistema de arquivos durante a execução dos testes. Esta opção permite personalizar onde o Jest armazena esses dados de cache em disco.

clearMocks [booleano]​

Padrão: false

Limpa automaticamente chamadas, instâncias, contextos e resultados de mocks antes de cada teste. Equivalente a chamar jest.clearAllMocks() antes de cada teste. Isso não remove nenhuma implementação de mock que possa ter sido fornecida.

collectCoverage [booleano]​

Padrão: false

Indica se as informações de cobertura devem ser coletadas durante a execução dos testes. Como isso modifica retroativamente todos os arquivos executados com instruções de coleta de cobertura, pode desacelerar significativamente seus testes.

O Jest inclui dois provedores de cobertura: babel (padrão) e v8. Veja a opção coverageProvider para mais detalhes.

"message": "informação"

Os provedores de cobertura babel e v8 usam os comentários /* istanbul ignore next */ e /* c8 ignore next */ respectivamente para excluir linhas dos relatórios de cobertura. Para mais informações, consulte a documentação do istanbuljs e do c8.

collectCoverageFrom [array]​

Padrão: undefined

Um array de padrões glob indicando um conjunto de arquivos para os quais as informações de cobertura devem ser coletadas. Se um arquivo corresponder ao padrão glob especificado, as informações de cobertura serão coletadas mesmo que não existam testes para este arquivo e ele nunca seja importado no conjunto de testes.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  collectCoverageFrom: [
    '**/*.{js,jsx}',
    '!**/node_modules/**',
    '!**/vendor/**',
  ],
});

Isso coletará informações de cobertura para todos os arquivos dentro do rootDir do projeto, exceto aqueles que correspondem a **/node_modules/** ou **/vendor/**.

"message": "dica"

Cada padrão glob é aplicado na ordem especificada na configuração. Por exemplo ["!**/__tests__/**", "**/*.js"] não excluirá __tests__ porque a negação é sobrescrita pelo segundo padrão. Para fazer o glob negado funcionar neste exemplo, ele deve vir após **/*.js.

"message": "nota"

Esta opção requer que collectCoverage esteja definido como true ou que o Jest seja 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 gravar seus arquivos de cobertura.

coveragePathIgnorePatterns [array<string>]​

Padrão: ["/node_modules/"]

Um array de strings de padrões regex que são comparadas com todos os caminhos de arquivo antes da execução do teste. Se o caminho do arquivo corresponder a qualquer padrão, as informações de cobertura serão ignoradas.

Essas strings de padrão são comparadas com o caminho completo. Use o token <rootDir> para incluir o caminho do diretório raiz do seu projeto e evitar ignorar acidentalmente todos os seus arquivos em ambientes diferentes que podem ter diretórios raiz distintos. Exemplo: ["<rootDir>/build/", "<rootDir>/node_modules/"].

coverageProvider [string]​

Indica qual provedor deve ser usado para instrumentar o código para cobertura. Valores permitidos são babel (padrão) ou v8.

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

Padrão: ["clover", "json", "lcov", "text"]

Uma lista de nomes de relatores que o Jest usa ao gerar relatórios de cobertura. Qualquer relator do istanbul pode ser utilizado.

"message": "dica"

Definir essa opção substitui os valores padrão. Adicione "text" ou "text-summary" para ver um resumo da cobertura na saída do console.

Opções adicionais podem ser passadas usando a forma de tupla. Por exemplo, você pode ocultar as linhas do relatório de cobertura para todos os arquivos totalmente cobertos:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
});

Para mais informações sobre a forma do objeto de opções, consulte o tipo CoverageReporterWithOptions nas definições de tipo.

coverageThreshold [objeto]​

Padrão: undefined

Isso será usado para configurar a aplicação de limites mínimos para os resultados de cobertura. Os limites podem ser especificados como global, como um glob, e como um diretório ou caminho de arquivo. Se os limites não forem atingidos, o Jest falhará. Limites especificados como um número positivo são considerados como a porcentagem mínima necessária. Limites especificados como um número negativo representam o número máximo de entidades não cobertas permitidas.

Por exemplo, com a seguinte configuração, o Jest falhará se houver menos de 80% de cobertura de ramos, linhas e funções, ou se houver mais de 10 instruções não cobertas:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: -10,
    },
  },
});

Se globs ou caminhos forem especificados juntamente com global, os dados de cobertura para caminhos correspondentes serão subtraídos da cobertura geral e os limites serão aplicados independentemente. Os limites para globs são aplicados a todos os arquivos que correspondem ao glob. Se o arquivo especificado pelo caminho não for encontrado, um erro será retornado.

Por exemplo, com a seguinte configuração:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  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,
    },
  },
});

O Jest falhará se:

  • O diretório ./src/components tem menos de 40% de cobertura de ramos ou instruções.

  • Um dos arquivos que correspondem ao glob ./src/reducers/**/*.js tem menos de 90% de cobertura de instruções.

  • O arquivo ./src/api/very-important-module.js tem menos de 100% de cobertura.

  • Os arquivos restantes, combinados, têm menos de 50% de cobertura (global).

dependencyExtractor [string]​

Padrão: undefined

Esta opção permite o uso de um extrator de dependências personalizado. Ele deve ser um módulo Node que exporta um objeto com uma função extract. Por exemplo:

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

A função extract deve retornar um iterável (Array, Set, etc.) com as dependências encontradas no código.

Esse módulo também pode conter uma função getCacheKey para gerar uma chave de cache que determina se a lógica foi alterada e se quaisquer artefatos em cache que dependam dela devem ser descartados.

displayName [string, objeto]​

padrão: undefined

Permite que uma etiqueta seja impressa ao lado de um teste enquanto ele está sendo executado. Isso se torna mais útil em repositórios de múltiplos projetos, onde pode haver muitos arquivos de configuração do Jest. Isso indica visualmente a qual projeto um teste pertence.

jest.config.js
const {defineConfig} = require('jest');

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

Alternativamente, pode ser passado um objeto com as propriedades name e color. Isso permite uma configuração personalizada da cor de fundo do displayName. displayName assume o padrão branco quando seu valor é uma string. O Jest usa chalk para fornecer a cor. Dessa forma, todas as opções válidas de cores suportadas pelo chalk também são suportadas pelo Jest.

jest.config.js
const {defineConfig} = require('jest');

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

errorOnDeprecated [booleano]​

Padrão: false

Faz com que chamadas a APIs obsoletas lancem mensagens de erro úteis. Útil para facilitar o processo de atualização.

extensionsToTreatAsEsm [array<string>]​

Padrão: []

O Jest executará arquivos .mjs e .js com o campo type do package.json mais próximo definido como module como Módulos ECMAScript. Se você tiver outros arquivos que devem ser executados com ESM nativo, precisa especificar sua extensão aqui.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  extensionsToTreatAsEsm: ['.ts'],
});
cuidado

O suporte a ESM no Jest ainda é experimental; consulte a documentação para detalhes.

fakeTimers [objeto]​

Padrão: {}

Os temporizadores simulados podem ser úteis quando um código define um timeout longo que não queremos aguardar em um teste. Para detalhes adicionais, consulte o guia de Fake Timers e a documentação da API.

Esta opção fornece a configuração padrão de fake timers para todos os testes. Chamar jest.useFakeTimers() em um arquivo de teste usará essas opções ou as substituirá se um objeto de configuração for passado. Por exemplo, você pode instruir o Jest a manter a implementação original de process.nextTick() e ajustar o limite de temporizadores recursivos que serão executados:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    doNotFake: ['nextTick'],
    timerLimit: 1000,
  },
});
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});
  // ...
});
"message": "dica"

Em vez de incluir jest.useFakeTimers() em cada arquivo de teste, você pode habilitar temporizadores falsos globalmente para todos os testes na configuração do Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    enableGlobally: true,
  },
});

Opções de configuração:

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

Por algum motivo, você pode precisar usar a implementação legada de temporizadores falsos. Veja como habilitá-la globalmente (opções adicionais não são suportadas):

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    enableGlobally: true,
    legacyFakeTimers: true,
  },
});

forceCoverageMatch [array<string>]​

Padrão: ['']

Arquivos de teste normalmente são ignorados na coleta de cobertura de código. Com esta opção, você pode sobrescrever esse comportamento e incluir arquivos normalmente ignorados.

Por exemplo, se você tiver testes em arquivos fonte nomeados com extensão .t.js como abaixo:

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

Você pode coletar cobertura desses arquivos definindo forceCoverageMatch.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  forceCoverageMatch: ['**/*.t.js'],
});

globals [objeto]​

Padrão: {}

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

Por exemplo, o seguinte criaria uma variável global __DEV__ definida como true em todos os ambientes de teste:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  globals: {
    __DEV__: true,
  },
});
"message": "nota"

Se você especificar um valor de referência global (como objeto ou array) aqui, e algum código modificar esse valor durante a execução de um teste, essa modificação não persistirá entre execuções de teste para outros arquivos. Além disso, o objeto globals deve ser serializável em JSON, portanto não pode ser usado para especificar funções globais. Para isso, use setupFiles.

globalSetup [string]​

Padrão: undefined

Esta opção permite o uso de um módulo personalizado de configuração global, que deve exportar uma função (pode ser síncrona ou assíncrona). A função será acionada uma vez antes de todos os conjuntos de testes e receberá dois argumentos: a globalConfig do Jest e a projectConfig.

"message": "informação"

Um módulo de configuração global configurado em um projeto (usando executor multiprojeto) será acionado apenas quando você executar pelo menos um teste desse projeto.

Variáveis globais definidas via globalSetup só podem ser lidas no globalTeardown. Não é possível acessar esses globais em seus conjuntos de testes.

Embora a transformação de código seja aplicada ao arquivo de configuração vinculado, o Jest não transformará nenhum código em node_modules. Isso ocorre porque é necessário carregar os transformadores reais (ex: babel ou typescript) para realizar a transformação.

setup.js
module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPatterns);
  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.testPathPatterns);
  console.log(projectConfig.cache);

  await globalThis.__MONGOD__.stop();
};

globalTeardown [string]​

Padrão: undefined

Esta opção permite o uso de um módulo personalizado de finalização global que deve exportar uma função (pode ser síncrona ou assíncrona). A função será acionada uma vez após todos os conjuntos de testes e receberá dois argumentos: a globalConfig do Jest e a projectConfig.

"message": "informação"

Um módulo de finalização global configurado em um projeto (usando executor multiprojeto) será acionado apenas quando você executar pelo menos um teste desse projeto.

A mesma ressalva sobre transformação de node_modules aplicada ao globalSetup também se aplica ao globalTeardown.

haste [objeto]​

Padrão: undefined

Usado para configurar o comportamento do jest-haste-map, o sistema interno de rastreamento/cache de arquivos do Jest. As seguintes opções são suportadas:

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 an 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 [booleano]​

Padrão: true

Insere os globais do Jest (expect, test, describe, beforeEach etc.) no ambiente global. Se definido como false, você deve importar de @jest/globals, por exemplo:

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

jest.useFakeTimers();

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

Esta opção só é suportada usando o executor de testes padrão jest-circus.

maxConcurrency [número]​

Padrão: 5

Número que limita a quantidade de testes executados simultaneamente ao usar test.concurrent. Testes além desse limite serão enfileirados e executados quando uma vaga estiver disponível.

maxWorkers [número | string]​

Especifica o número máximo de workers que o pool criará para executar testes. No modo de execução única, o padrão é o número de núcleos disponíveis na sua máquina menos um (para a thread principal). No modo de observação, o padrão é metade dos núcleos disponíveis para garantir que o Jest não sobrecarregue sua máquina. Pode ser útil ajustar isso em ambientes com recursos limitados como CIs, mas os padrões atendem à maioria dos casos.

Para ambientes com CPUs variáveis disponíveis, você pode usar configuração baseada em porcentagem:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  maxWorkers: '50%',
});

moduleDirectories [array<string>]​

Padrão: ["node_modules"]

Array de nomes de diretórios que serão pesquisados recursivamente a partir do local do módulo requisitado. Definir esta opção substituirá o padrão. Se quiser ainda pesquisar pacotes em node_modules, inclua-o junto com outras opções:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  moduleDirectories: ['node_modules', 'bower_components'],
});
cuidado

Não é recomendado usar '.' como um dos moduleDirectories, pois isso impede que pacotes com escopo, como @emotion/react, acessem pacotes com o mesmo nome de subdiretório (react). Veja este issue para mais detalhes. Na maioria dos casos, é preferível usar a configuração moduleNameMapper em seu lugar.

moduleFileExtensions [array<string>]​

Padrão: ["js", "mjs", "cjs", "jsx", "ts", "mts", "cts", "tsx", "json", "node"]

Um array de extensões de arquivo usadas pelos seus módulos. Se você importar módulos sem especificar a extensão, o Jest procurará por essas extensões, na ordem da esquerda para a direita.

Recomendamos colocar as extensões mais usadas no seu projeto no início do array. Se você usa TypeScript, considere mover "ts" e/ou "tsx" para o começo da lista.

moduleNameMapper [objeto<string, string | array<string>>]​

Padrão: null

Um mapeamento de expressões regulares para nomes de módulos ou arrays de nomes de módulos, permitindo substituir recursos como imagens ou estilos por um único módulo.

Módulos mapeados para um alias não são mockados por padrão, independentemente do automocking estar ativado ou não.

Use o token <rootDir> para referenciar o valor de rootDir se precisar usar caminhos de arquivo.

Além disso, você pode substituir grupos capturados por regex usando backreferences numerados.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  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',
    ],
  },
});

A ordem de definição dos mapeamentos é importante. Os padrões são verificados um por um até encontrar uma correspondência. A regra mais específica deve ser listada primeiro. Isso também se aplica a arrays de nomes de módulos.

"message": "informação"

Se você fornecer nomes de módulos sem delimitadores ^$, isso pode causar erros difíceis de identificar. Por exemplo, relay substituirá todos os módulos que contêm relay como substring em seu nome: relay, react-relay e graphql-relay serão todos redirecionados para seu stub.

modulePathIgnorePatterns [array<string>]​

Padrão: []

Um array de padrões regex que são comparados com todos os caminhos de módulo antes que esses caminhos sejam considerados "visíveis" para o carregador de módulos. Se o caminho de um módulo corresponder a qualquer padrão, ele não poderá ser require() no ambiente de teste.

Essas strings de padrão são comparadas com o caminho completo. Use o token <rootDir> para incluir o caminho do diretório raiz do seu projeto e evitar ignorar acidentalmente todos os seus arquivos em ambientes com diretórios raiz diferentes.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  modulePathIgnorePatterns: ['<rootDir>/build/'],
});

modulePaths [array<string>]​

Padrão: []

Uma alternativa à variável de ambiente NODE_PATH, modulePaths é um array de caminhos absolutos para locais adicionais onde o Jest deve procurar módulos. Use o token <rootDir> para incluir o caminho do diretório raiz do seu projeto.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  modulePaths: ['<rootDir>/app/'],
});

notify [booleano]​

Padrão: false

Ativa notificações nativas do sistema operacional para resultados de testes. Para exibir notificações, o Jest precisa do pacote node-notifier, que deve ser instalado separadamente:

npm install --save-dev node-notifier
"message": "dica"

No macOS, lembre-se de permitir notificações do terminal-notifier em Preferências do Sistema > Notificações & Foco.

No Windows, o node-notifier cria uma nova entrada no menu iniciar no primeiro uso e não exibe a notificação. As notificações serão exibidas corretamente nas execuções subsequentes.

notifyMode [string]​

Padrão: failure-change

Especifica o modo de notificação. Requer notify: true.

Modos​

  • always: sempre envia uma notificação.

  • failure: envia uma notificação quando os testes falham.

  • success: envia uma notificação quando os testes passam.

  • change: envia uma notificação quando o status muda.

  • success-change: envia uma notificação quando os testes passam ou uma vez quando falham.

  • failure-change: envia uma notificação quando os testes falham ou uma vez quando passam.

openHandlesTimeout [número]​

Padrão: 1000

Exibe um aviso indicando que há prováveis alças abertas se o Jest não sair corretamente após este número de milissegundos após a conclusão. Use 0 para desativar o aviso.

preset [string]​

Padrão: undefined

Um preset que serve como base para a configuração do Jest. Deve apontar para um módulo npm contendo um arquivo jest-preset.json, jest-preset.js, jest-preset.cjs ou jest-preset.mjs na raiz.

Por exemplo, este preset foo-bar/jest-preset.js será usado da seguinte forma:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  preset: 'foo-bar',
});

Presets também podem ser relativos a caminhos do sistema de arquivos:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  preset: './node_modules/foo-bar/jest-preset.js',
});
"message": "informação"

Se você também especificou rootDir, a resolução deste arquivo será relativa a esse diretório raiz.

prettierPath [string]​

Padrão: 'prettier'

Define o caminho para o módulo prettier usado para atualizar snapshots inline.

projects [array<string | ProjectConfig>]​

Padrão: undefined

Quando a configuração projects recebe um array de caminhos ou padrões glob, o Jest executará testes em todos os projetos especificados simultaneamente. Ideal para monorepos ou quando se trabalha com múltiplos projetos.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  projects: ['<rootDir>', '<rootDir>/examples/*'],
});

Esta configuração de exemplo executará o Jest no diretório raiz e em cada pasta no diretório de exemplos. Você pode ter projetos ilimitados rodando na mesma instância do Jest.

O recurso projects também pode ser usado para executar múltiplas configurações ou múltiplos runners. Para isso, você pode passar um array de objetos de configuração. Por exemplo, para executar tanto testes quanto ESLint (via jest-runner-eslint) na mesma invocação do Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  projects: [
    {
      displayName: 'test',
    },
    {
      displayName: 'lint',
      runner: 'jest-runner-eslint',
      testMatch: ['<rootDir>/**/*.js'],
    },
  ],
});
"message": "dica"

Ao usar multi-project runner, recomenda-se adicionar um displayName para cada projeto. Isso exibirá o displayName do projeto junto aos seus testes.

"message": "nota"

Com projects ativado, o Jest copiará as opções de configuração do nível raiz para cada configuração filha durante a execução, resolvendo seus valores no contexto do filho. Tokens como <rootDir> apontarão para o diretório raiz do filho, mesmo definidos na configuração raiz.

randomize [booleano]​

Padrão: false

Equivalente à flag --randomize para randomizar a ordem dos testes em um arquivo.

reporters [array<moduleName | [moduleName, options]>]​

Padrão: undefined

Use esta opção para adicionar reporters ao Jest. Deve ser uma lista de nomes de reporters, com opções adicionais passadas via formato de tupla:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [
    'default',
    ['<rootDir>/custom-reporter.js', {banana: 'yes', pineapple: 'no'}],
  ],
});

Reporter Padrão​

Se reporters personalizados forem especificados, o reporter padrão do Jest será substituído. Se você deseja mantê-lo, 'default' deve ser passado como nome de reporter:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [
    'default',
    ['jest-junit', {outputDirectory: 'reports', outputName: 'report.xml'}],
  ],
});

Reporter do GitHub Actions​

Se incluído na lista, o reporter integrado do GitHub Actions anotará arquivos alterados com mensagens de falha de testes e (quando usado com 'silent: false') imprimirá logs com recursos de grupos do GitHub para navegação facilitada. Note que 'default' não deve ser usado neste caso pois 'github-actions' já cuida disso - lembre-se de incluir também 'summary'. Se desejar usá-lo apenas para anotações, basta incluir o reporter sem opções, pois o valor padrão de 'silent' é 'true':

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [['github-actions', {silent: false}], 'summary'],
});

Reporter de Resumo​

O reporter de resumo imprime um resumo de todos os testes. Ele faz parte do reporter padrão, portanto será habilitado se 'default' estiver na lista. Por exemplo, você pode usá-lo como reporter independente ou junto com o Reporter Silencioso:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: ['jest-silent-reporter', 'summary'],
});

O reporter summary aceita opções. Como ele está incluído no reporter default, você também pode passar as opções lá.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [['default', {summaryThreshold: 10}]],
});

A opção summaryThreshold funciona assim: se o número total de conjuntos de testes exceder esse limite, um resumo detalhado de todos os testes falhos será impresso após executar todos os testes. O padrão é 20.

Reporters Personalizados​

Quer mais reporters? Confira a longa lista de reporters incríveis no Awesome Jest.

Módulos de reporter personalizados devem exportar uma classe que recebe globalConfig, reporterOptions e reporterContext como argumentos do construtor:

custom-reporter.js
class CustomReporter {
  constructor(globalConfig, reporterOptions, reporterContext) {
    this._globalConfig = globalConfig;
    this._options = reporterOptions;
    this._context = reporterContext;
  }

  onRunComplete(testContexts, results) {
    console.log('Custom reporter output:');
    console.log('global config:', this._globalConfig);
    console.log('options for this reporter from Jest config:', this._options);
    console.log('reporter context passed from test scheduler:', this._context);
  }

  // Optionally, reporters can force Jest to exit with non zero code by returning
  // an `Error` from `getLastError()` method.
  getLastError() {
    if (this._shouldFail) {
      return new Error('Custom error reported!');
    }
  }
}

module.exports = CustomReporter;

Para a lista completa de hooks e tipos de argumentos, consulte a interface Reporter em packages/jest-reporters/src/types.ts.

resetMocks [booleano]​

Padrão: false

Reseta automaticamente o estado dos mocks antes de cada teste. Equivalente a chamar jest.resetAllMocks() antes de cada teste. Isso remove implementações falsas dos mocks mas não restaura sua implementação original.

resetModules [booleano]​

Padrão: false

Por padrão, cada arquivo de teste tem seu próprio registro de módulo independente. Habilitar resetModules vai além e reseta o registro antes de cada teste individual. Isso isola módulos entre testes, evitando conflitos de estado. Pode ser feito programaticamente com jest.resetModules().

resolver [string]​

Padrão: undefined

Esta opção permite usar um resolver personalizado. O resolver deve ser um módulo que exporta um dos seguintes:

  1. Uma função que espera uma string (caminho a resolver) como primeiro argumento e um objeto de opções como segundo. Deve retornar o caminho do módulo resolvido ou lançar erro se não encontrado. ou

  2. Um objeto com propriedades async e/ou sync. sync deve ser uma função conforme acima, e async deve ser uma função similar que retorna uma promise resolvendo com o caminho ou rejeitando com erro.

O objeto de opções fornecido aos resolvers tem a estrutura:

type ResolverOptions = {
  /** Directory to begin resolving from. */
  basedir: string;
  /** List of export conditions. */
  conditions?: Array<string>;
  /** Instance of default resolver. */
  defaultResolver: (path: string, options: ResolverOptions) => string;
  /** List of file extensions to search in order. */
  extensions?: Array<string>;
  /** List of directory names to be looked up for modules recursively. */
  moduleDirectory?: Array<string>;
  /** List of `require.paths` to use if nothing is found in `node_modules`. */
  paths?: Array<string>;
  /** Current root directory. */
  rootDir?: string;
};
"message": "dica"

O defaultResolver passado como opção é o resolvedor padrão do Jest, que pode ser útil ao criar seu próprio resolvedor personalizado. Ele aceita os mesmos argumentos que sua versão síncrona personalizada, por exemplo, (path, options), e retorna uma string ou lança um erro.

Por exemplo, se você deseja respeitar o campo "browser" do Browserify, pode usar este resolvedor:

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

module.exports = browserResolve.sync;

E adicioná-lo à configuração do Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  resolver: '<rootDir>/resolver.js',
});

O jest-resolve do Jest depende do unrs-resolver. Podemos passar opções adicionais, como modificar mainFields para resolução. Por exemplo, em projetos React Native, você pode usar esta configuração:

module.exports = (path, options) => {
  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(path, {
    ...options,
    // `unrs-resolver` option: https://github.com/unrs/unrs-resolver#main-field
    mainFields: ['react-native', 'main'],
  });
};

Você também pode usar defaultResolver para implementar um "pré-processador" que altera como o resolvedor padrão resolve módulos. Por exemplo, imagine um projeto TypeScript que precisa referenciar arquivos .js em runtime mas executa o Jest em arquivos .ts.

module.exports = (path, options) => {
  // Dynamic imports within our codebase that reference .js need to reference
  // .ts during tests.
  if (
    !options.basedir.includes('node_modules') &&
    path.endsWith('.js') &&
    (path.startsWith('../') || path.startsWith('./'))
  ) {
    path = path.replace(/\.js$/, '.ts');
  }

  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(path, options);
};

restoreMocks [booleano]​

Padrão: false

Restaura automaticamente o estado e implementação dos mocks antes de cada teste. Equivalente a chamar jest.restoreAllMocks() antes de cada teste. Isso remove implementações falsas de todos os mocks e restaura sua implementação original.

rootDir [string]​

Padrão: O diretório raiz contendo seu arquivo de configuração do Jest ou o package.json ou o pwd se nenhum package.json for encontrado

O diretório raiz que o Jest deve escanear para encontrar testes e módulos. Se sua configuração do Jest estiver no package.json e você quiser que o diretório raiz seja a raiz do repositório, esse valor padrão será o diretório do package.json.

Frequentemente, você definirá isso como 'src' ou 'lib', correspondendo ao local onde seu código está armazenado no repositório.

"message": "dica"

Usar '<rootDir>' como token em qualquer outra configuração baseada em caminho referenciará esse valor. Por exemplo, para apontar uma entrada setupFiles para some-setup.js na raiz do projeto, defina: '<rootDir>/some-setup.js'.

roots [array<string>]​

Padrão: ["<rootDir>"]

Lista de caminhos para diretórios que o Jest usará para buscar arquivos.

Útil quando você quer que o Jest busque apenas em um subdiretório específico (como src/), impedindo acesso ao resto do repositório.

"message": "informação"

Enquanto rootDir é usado principalmente como token reutilizável, roots é usado internamente pelo Jest para localizar arquivos de teste e código fonte. Isso também se aplica na busca por mocks manuais de módulos node_modules (__mocks__ precisa estar em um dos roots).

Por padrão, roots tem uma única entrada <rootDir>, mas em projetos com múltiplas raízes (ex: roots: ["<rootDir>/src/", "<rootDir>/tests/"]) isso pode variar.

runtime [string]​

Padrão: "jest-runtime"

Esta opção permite usar um runtime personalizado para executar arquivos de teste. Um runtime personalizado pode ser fornecido especificando um caminho para uma implementação de runtime.

O módulo de runtime deve exportar uma classe que estende a classe Runtime padrão do Jest ou implementa uma interface compatível com a mesma assinatura de construtor e métodos.

"message": "aviso"

Criar um runtime personalizado é um caso de uso avançado. A maioria dos usuários não precisa personalizar o runtime. Considere se seu caso de uso pode ser melhor tratado com transformers personalizados, ambientes de teste ou mocks de módulos.

Exemplo:

custom-runtime.js
const {default: Runtime} = require('jest-runtime');

class CustomRuntime extends Runtime {
  //...custom logic
}

module.exports = CustomRuntime;
custom-runtime.ts
import Runtime from 'jest-runtime';

export default class CustomRuntime extends Runtime {
  //...custom logic
}

Adicione o runtime personalizado à sua configuração do Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  runtime: './custom-runtime.js',
});

runner [string]​

Padrão: "jest-runner"

Permite usar um executor personalizado em vez do padrão do Jest. Exemplos incluem:

"message": "informação"

O valor da propriedade runner pode omitir o prefixo jest-runner- do nome do pacote.

Para criar um test-runner, exporte uma classe que aceite globalConfig no construtor e tenha um método runTests com a assinatura:

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

Se precisar restringir seu test-runner para executar apenas em série em vez de paralelo, sua classe deve ter a propriedade isSerial definida como true.

sandboxInjectedGlobals [array<string>]​

"message": "dica"

Renomeado de extraGlobals no Jest 28.

Padrão: undefined

Arquivos de teste são executados dentro de uma vm, o que torna lentas as chamadas para propriedades do contexto global (ex: Math). Com esta opção você pode especificar propriedades extras para serem definidas dentro da vm para pesquisas mais rápidas.

Por exemplo, se seus testes chamam Math frequentemente, você pode passá-lo definindo sandboxInjectedGlobals.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  sandboxInjectedGlobals: ['Math'],
});
"message": "nota"

Esta opção não tem efeito se você usar ESM nativo.

setupFiles [array]​

Padrão: []

Uma lista de caminhos para módulos que executam códigos para configurar ou preparar o ambiente de teste. Cada arquivo de setup será executado uma vez por arquivo de teste. Como cada teste roda em seu próprio ambiente, esses scripts serão executados no ambiente de teste antes de executar setupFilesAfterEnv e antes do próprio código de teste.

"message": "dica"

Se seu script de setup for um módulo CJS, ele pode exportar uma função assíncrona. O Jest chamará a função e aguardará seu resultado. Isso pode ser útil para buscar dados assincronamente. Se o arquivo for um módulo ESM, simplesmente use await de nível superior para obter o mesmo resultado.

setupFilesAfterEnv [array]​

Padrão: []

Uma lista de caminhos para módulos que executam códigos para configurar ou preparar o framework de testes antes da execução de cada arquivo de teste na suíte. Como setupFiles executa antes da instalação do framework de testes no ambiente, este script oferece a oportunidade de executar códigos imediatamente após a instalação do framework de testes, mas antes da execução do próprio código de teste.

Ou seja, os módulos setupFilesAfterEnv destinam-se a códigos repetidos em cada arquivo de teste. Com o framework instalado, os globais do Jest, o objeto jest e o expect ficam acessíveis nos módulos. Por exemplo, você pode adicionar matchers extras da biblioteca jest-extended ou chamar hooks de setup e teardown:

setup-jest.js
const matchers = require('jest-extended');
expect.extend(matchers);

afterEach(() => {
  jest.useRealTimers();
});
jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  setupFilesAfterEnv: ['<rootDir>/setup-jest.js'],
});
"message": "dica"

Se seu script de setup for um módulo CJS, ele pode exportar uma função assíncrona. O Jest chamará a função e aguardará seu resultado. Isso pode ser útil para buscar dados assincronamente. Se o arquivo for um módulo ESM, simplesmente use await de nível superior para obter o mesmo resultado.

showSeed [booleano]​

Padrão: false

Equivalente à flag --showSeed para imprimir a seed no resumo do relatório de testes.

slowTestThreshold [número]​

Padrão: 5

O número de segundos após o qual um teste é considerado lento e reportado como tal nos resultados.

snapshotFormat [objeto]​

Padrão: {escapeString: false, printBasicPrototype: false}

Permite sobrescrever opções específicas de formatação de snapshots documentadas no readme do pretty-format, com exceção de compareKeys e plugins. Por exemplo, esta configuração faria com que o formatador de snapshots não imprimisse prefixos para "Object" e "Array":

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  snapshotFormat: {
    printBasicPrototype: false,
  },
});
some.test.js
test('does not show prototypes for object and array inline', () => {
  const object = {
    array: [{hello: 'Danger'}],
  };
  expect(object).toMatchInlineSnapshot(`
    {
      "array": [
        {
          "hello": "Danger",
        },
      ],
    }
  `);
});

snapshotResolver [string]​

Padrão: undefined

O caminho para um módulo que pode resolver o caminho teste<->snapshot. Esta opção permite personalizar onde o Jest armazena arquivos de snapshot no disco.

custom-resolver.js
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: []

Uma lista de caminhos para módulos de serializadores de snapshot que o Jest deve usar em testes de snapshot.

O Jest possui serializadores padrão para tipos JavaScript nativos, elementos HTML (Jest 20.0.0+), ImmutableJS (Jest 20.0.0+) e elementos React. Veja o tutorial de teste de snapshot para mais informações.

custom-serializer.js
module.exports = {
  serialize(val, config, indentation, depth, refs, printer) {
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },

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

printer é uma função que serializa um valor usando plugins existentes.

Adicione custom-serializer à sua configuração do Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  snapshotSerializers: ['path/to/custom-serializer.js'],
});

Os testes ficariam assim:

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

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

Snapshot renderizado:

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

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

Mais informações sobre a API de serializadores podem ser encontradas aqui.

testEnvironment [string]​

Padrão: "node"

O ambiente de teste que será usado. O ambiente padrão no Jest é um ambiente Node.js. Se você está construindo uma aplicação web, pode usar um ambiente similar a um navegador através do jsdom.

Ao adicionar um docblock @jest-environment no topo do arquivo, você pode especificar outro ambiente para todos os testes desse arquivo:

/**
 * @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 para configurar o ambiente de teste. O módulo deve exportar uma classe com métodos setup, teardown e getVmContext. Você também pode passar variáveis deste módulo para seus testes atribuindo-as ao objeto this.global – elas estarão disponíveis como variáveis globais. O construtor recebe globalConfig e projectConfig como primeiro argumento, e testEnvironmentContext como segundo.

A classe pode opcionalmente expor um método assíncrono handleTestEvent para vincular eventos disparados pelo jest-circus. Normalmente, o executor de testes jest-circus pausaria até que uma promessa retornada de handleTestEvent fosse resolvida, exceto para os próximos eventos: start_describe_definition, finish_describe_definition, add_hook, add_test ou error (para a lista atualizada, consulte o tipo SyncEvent nas definições de tipos). Isso ocorre por motivos de compatibilidade com versões anteriores e assinatura process.on('unhandledRejection', callback), mas geralmente não deve ser um problema para a maioria dos casos de uso.

Quaisquer pragmas de docblock em arquivos de teste serão passados para o construtor do ambiente e podem ser usados para configuração por teste. Se o pragma não tiver um valor, estará presente no objeto com seu valor definido como uma string vazia. Se o pragma não estiver presente, não constará no objeto.

Para usar esta classe como seu ambiente personalizado, referencie-a pelo caminho completo dentro do projeto. Por exemplo, se sua classe estiver armazenada em my-custom-environment.js em alguma subpasta do seu projeto, a anotação ficaria assim:

/**
 * @jest-environment ./src/test/my-custom-environment
 */
"message": "informação"

O TestEnvironment é isolado (sandboxed). Cada suíte de testes acionará configuração/desmontagem em seu próprio TestEnvironment.

Exemplo:

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

class CustomEnvironment extends NodeEnvironment {
  constructor(config, context) {
    super(config, context);
    console.log(config.globalConfig);
    console.log(config.projectConfig);
    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 = globalThis.someGlobalObject;
});

testEnvironmentOptions [Objeto]​

Padrão: {}

Opções do ambiente de teste que serão passadas ao testEnvironment. As opções relevantes dependem do ambiente.

Por exemplo, você pode substituir opções passadas ao jsdom:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    html: '<html lang="zh-cmn-Hant"></html>',
    url: 'https://jestjs.io/',
    userAgent: 'Agent/007',
  },
});

Tanto jest-environment-jsdom quanto jest-environment-node permitem especificar customExportConditions, que controlam quais versões de uma biblioteca são carregadas de exports no package.json. jest-environment-jsdom usa ['browser'] por padrão. jest-environment-node usa ['node', 'node-addons'] por padrão.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    customExportConditions: ['react-native'],
  },
});

Essas opções também podem ser passadas via docblock, similar ao testEnvironment. A string com opções deve ser analisável por JSON.parse:

/**
 * @jest-environment jsdom
 * @jest-environment-options {"url": "https://jestjs.io/"}
 */

test('use jsdom and set the URL in this test file', () => {
  expect(window.location.href).toBe('https://jestjs.io/');
});

testFailureExitCode [número]​

Padrão: 1

O código de saída que Jest retorna quando um teste falha.

"message": "informação"

Isso não altera o código de saída em caso de erros do Jest (ex: configuração inválida).

testMatch [array<string>]​

(padrão: [ "**/__tests__/**/*.?([mc])[jt]s?(x)", "**/?(*.)+(spec|test).?([mc])[jt]s?(x)" ])

Os padrões glob que Jest usa para detectar arquivos de teste. Por padrão, procura por arquivos .js, .jsx, .ts e .tsx dentro de pastas __tests__, além de arquivos com sufixo .test ou .spec (ex: Component.test.js ou Component.spec.js). Também encontrará arquivos chamados test.js ou spec.js.

Consulte o pacote micromatch para detalhes sobre os padrões que podem ser especificados.

Veja também testRegex [string | array<string>], mas note que você não pode especificar ambas as opções.

"message": "dica"

Cada padrão glob é aplicado na ordem em que são especificados na configuração. Por exemplo, ["!**/__fixtures__/**", "**/__tests__/**/*.js"] não excluirá __fixtures__ porque a negação é sobrescrita pelo segundo padrão. Para fazer o glob negado funcionar neste exemplo, ele deve vir após **/__tests__/**/*.js.

testPathIgnorePatterns [array<string>]​

Padrão: ["/node_modules/"]

Um array de strings com padrões regex que são comparados com todos os caminhos de testes antes da execução. Se o caminho do teste corresponder a qualquer padrão, ele será ignorado.

Essas strings de padrão são comparadas com o caminho completo. Use o token <rootDir> para incluir o caminho do diretório raiz do seu projeto e evitar ignorar acidentalmente todos os seus arquivos em ambientes diferentes que podem ter diretórios raiz distintos. Exemplo: ["<rootDir>/build/", "<rootDir>/node_modules/"].

testRegex [string | array<string>]​

Padrão: (/__tests__/.*|(\\.|/)(test|spec))\\.[mc]?[jt]sx?$

O padrão ou padrões que o Jest usa para detectar arquivos de teste. Por padrão, ele procura por arquivos .js, .jsx, .ts e .tsx dentro de pastas __tests__, além de qualquer arquivo com sufixo .test ou .spec (ex: Component.test.js ou Component.spec.js). Também encontrará arquivos chamados test.js ou spec.js. Veja também testMatch [array<string>], mas note que você não pode especificar ambas as opções.

A seguir está uma visualização do regex padrão:

├── __tests__
│   └── component.spec.js # test
│   └── anything # test
├── package.json # not test
├── foo.test.js # test
├── bar.spec.jsx # test
└── component.js # not test
"message": "informação"

testRegex tentará detectar arquivos de teste usando o caminho absoluto do arquivo. Portanto, ter uma pasta com nome que corresponda ao padrão executará todos os arquivos como testes.

testResultsProcessor [string]​

Padrão: undefined

Esta opção permite usar um processador personalizado de resultados. Este processador deve ser um módulo Node que exporta uma função que recebe um objeto com a seguinte estrutura como primeiro argumento e o retorna:

{
  "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
      },
      "duration": number | null,
      "startAt": epoch | null
    },
    ...
    ],
    "perfStats": {
      "end": epoch,
      "loadTestEnvironmentEnd": epoch,
      "loadTestEnvironmentStart": epoch,
      "runtime": number,
      "setupAfterEnvEnd": epoch,
      "setupAfterEnvStart": epoch,
      "setupFilesEnd": epoch,
      "setupFilesStart": epoch,
      "slow": boolean,
      "start": epoch
    },
    "testFilePath": absolute path to test file,
    "coverage": {}
  },
  "testExecError:" (exists if there was a top-level failure) {
    "message": string
    "stack": string
  }
  ...
  ]
}

testResultsProcessor e reporters são muito semelhantes. Uma diferença é que um processador de resultados só é chamado após todos os testes terminarem. Já um reporter pode receber resultados após testes individuais e/ou conjuntos de testes serem finalizados.

testRunner [string]​

Padrão: jest-circus/runner

Esta opção permite usar um executor de testes personalizado. O padrão é jest-circus. Um executor personalizado pode ser fornecido especificando o caminho para uma implementação de executor de testes.

O módulo do executor de testes 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 dessa função pode ser encontrado em nosso pacote padrão jasmine2 test runner.

testSequencer [string]​

Padrão: @jest/test-sequencer

Esta opção permite usar um sequenciador personalizado em vez do padrão do Jest.

"message": "dica"

Tanto sort quanto shard podem opcionalmente retornar uma Promise.

Por exemplo, você pode ordenar os caminhos de testes alfabeticamente:

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

class CustomSequencer extends Sequencer {
  /**
   * Select tests for shard requested via --shard=shardIndex/shardCount
   * Sharding is applied before sorting
   */
  shard(tests, {shardIndex, shardCount}) {
    const shardSize = Math.ceil(tests.length / shardCount);
    const shardStart = shardSize * (shardIndex - 1);
    const shardEnd = shardSize * shardIndex;

    return [...tests]
      .sort((a, b) => (a.path > b.path ? 1 : -1))
      .slice(shardStart, shardEnd);
  }

  /**
   * Sort test to determine order of execution
   * Sorting is applied after sharding
   */
  sort(tests) {
    // Test structure information
    // https://github.com/jestjs/jest/blob/6b8b1404a1d9254e7d5d90a8934087a9c9899dab/packages/jest-runner/src/types.ts#L17-L21
    const copyTests = [...tests];
    return copyTests.sort((testA, testB) => (testA.path > testB.path ? 1 : -1));
  }
}

module.exports = CustomSequencer;

Adicione custom-sequencer à sua configuração do Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  testSequencer: 'path/to/custom-sequencer.js',
});

testTimeout [número]​

Padrão: 5000

Tempo limite padrão de um teste em milissegundos.

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

Padrão: {"\\.[jt]sx?$": "babel-jest"}

Um mapa de expressões regulares para caminhos de transformadores. Opcionalmente, pode-se passar uma tupla com opções de configuração como segundo argumento: {filePattern: ['path-to-transformer', {options}]}. Por exemplo, veja como configurar o babel-jest para comportamento não padrão: {'\\.js$': ['babel-jest', {rootMode: 'upward'}]}.

O Jest executa o código do seu projeto como JavaScript, portanto um transformador é necessário se você usar sintaxes não suportadas nativamente pelo Node (como JSX, TypeScript ou templates Vue). Por padrão, o Jest usará o transformador babel-jest, que carregará a configuração do Babel do seu projeto e transformará qualquer arquivo que corresponda à expressão regular /\.[jt]sx?$/ (ou seja, qualquer arquivo .js, .jsx, .ts ou .tsx). Além disso, o babel-jest injetará o plugin do Babel necessário para o hoisting de mocks mencionado em Mocking de módulos ES.

Consulte a seção Transformação de Código para mais detalhes e instruções sobre como criar seu próprio transformador.

"message": "dica"

Lembre-se que um transformer executa apenas uma vez por arquivo, a menos que o arquivo seja alterado.

Inclua explicitamente o transformer padrão babel-jest se desejar usá-lo junto com outros pré-processadores de código:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transform: {
    '\\.[jt]sx?$': 'babel-jest',
    '\\.css$': 'some-css-transformer',
  },
});

transformIgnorePatterns [array<string>]​

Padrão: ["/node_modules/", "\\.pnp\\.[^\\\/]+$"]

Um array de strings com padrões regex que são comparados com todos os caminhos de arquivos fonte antes da transformação. Se o caminho do arquivo corresponder a qualquer um dos padrões, ele não será transformado.

Fornecer padrões regex que se sobrepõem pode resultar em arquivos não sendo transformados quando você esperava que fossem. Por exemplo:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: ['/node_modules/(?!(foo|bar)/)', '/bar/'],
});

O primeiro padrão corresponderá (e portanto não transformará) arquivos dentro de /node_modules, exceto aqueles em /node_modules/foo/ e /node_modules/bar/. O segundo padrão corresponderá (e não transformará) arquivos dentro de qualquer caminho contendo /bar/. Juntos, arquivos em /node_modules/bar/ não serão transformados porque correspondem ao segundo padrão, mesmo tendo sido excluídos pelo primeiro.

Às vezes (especialmente em projetos React Native ou TypeScript) módulos de terceiros são publicados como código não transpilado. Como todos os arquivos dentro de node_modules não são transformados por padrão, o Jest não entenderá o código nesses módulos, resultando em erros de sintaxe. Para contornar isso, você pode usar transformIgnorePatterns para permitir a transpilação desses módulos. Você encontrará um bom exemplo desse caso de uso no Guia de React Native.

Essas strings de padrão são comparadas com o caminho completo. Use o token <rootDir> para incluir o caminho do diretório raiz do seu projeto e evitar ignorar acidentalmente todos os seus arquivos em ambientes com diretórios raiz diferentes.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: [
    '<rootDir>/bower_components/',
    '<rootDir>/node_modules/',
  ],
});
"message": "dica"

Se você usa pnpm e precisa converter alguns pacotes dentro de node_modules, observe que os pacotes nesta pasta (ex: node_modules/package-a/) estão vinculados simbolicamente ao caminho sob .pnpm (ex: node_modules/.pnpm/package-a@x.x.x/node_modules/package-a/). Portanto, usar <rootDir>/node_modules/(?!(package-a|@scope/pkg-b)/) diretamente não será reconhecido. A solução é usar:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: [
    '<rootDir>/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)',
    /* if config file is under '~/packages/lib-a/' */
    `${path.join(
      __dirname,
      '../..',
    )}/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)`,
    /* or using relative pattern to match the second 'node_modules/' in 'node_modules/.pnpm/@scope+pkg-b@x.x.x/node_modules/@scope/pkg-b/' */
    'node_modules/(?!.pnpm|package-a|@scope/pkg-b)',
  ],
});

Note que os nomes das pastas do pnpm sob .pnpm usam o nome do pacote + @ + número da versão. Portanto, usar / não será reconhecido, mas @ funciona corretamente.

unmockedModulePathPatterns [array<string>]​

Padrão: []

Uma matriz de strings com padrões regex que são comparados com todos os módulos antes que o carregador de módulos retorne automaticamente um mock. Se o caminho de um módulo corresponder a qualquer padrão nesta lista, ele não será mockado automaticamente pelo carregador de módulos.

Isso é útil para módulos de "utilidade" comumente usados que quase sempre são detalhes de implementação (como underscore, lodash, etc). É uma boa prática manter esta lista pequena e sempre usar chamadas explícitas de jest.mock()/jest.unmock() em testes individuais. A configuração explícita por teste facilita que outros leitores compreendam o ambiente de execução do teste.

É possível substituir essa configuração em testes individuais chamando explicitamente jest.mock() no topo do arquivo de teste.

verbose [booleano]​

Padrão: false ou true se houver apenas um arquivo de teste para executar

Indica se cada teste individual deve ser relatado durante a execução. Todos os erros ainda serão mostrados no final após a execução.

waitForUnhandledRejections [booleano]​

Dá uma volta no loop de eventos para lidar com rejectionHandled, uncaughtException ou unhandledRejection.

Sem essa flag, o Jest pode relatar falsos positivos (ex: rejeição tratada relatada como erro) ou deixar de relatar rejeições não tratadas (ou relatá-las para outro caso de teste).

Esta opção pode adicionar uma sobrecarga perceptível para conjuntos de testes rápidos.

watchPathIgnorePatterns [array<string>]​

Padrão: []

Um array de padrões RegExp comparados com todos os caminhos de arquivos fonte antes de reexecutar testes no modo de observação. Se o caminho do arquivo corresponder a qualquer padrão, quando atualizado, não acionará a reexecução dos testes.

Estes padrões comparam-se com o caminho completo. Use o token <rootDir> para incluir o caminho do diretório raiz do projeto e evitar ignorar acidentalmente arquivos em ambientes com diretórios raiz diferentes. Exemplo: ["<rootDir>/node_modules/"].

Mesmo sem especificação, o observador ignora alterações em pastas de controle de versão (.git, .hg, .sl). Outros arquivos/diretórios ocultos (iniciados com .) são observados por padrão. Lembre-se de escapar o ponto ao adicioná-los a watchPathIgnorePatterns, pois é um caractere especial do RegExp.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  watchPathIgnorePatterns: ['<rootDir>/\\.tmp/', '<rootDir>/bar/'],
});

watchPlugins [array<string | [string, Object]>]​

Padrão: []

Esta opção permite usar plugins de observação personalizados. Saiba mais sobre watch plugins aqui.

Exemplos de watch plugins incluem:

"message": "informação"

Os valores em watchPlugins podem omitir o prefixo jest-watch- do nome do pacote.

watchman [booleano]​

Padrão: true

Define se deve usar watchman para rastreamento de arquivos.

workerIdleMemoryLimit [número|string]​

Padrão: undefined

Especifica o limite de memória para workers antes de serem reciclados, funcionando principalmente como solução alternativa para este problema;

Após um worker executar um teste, seu uso de memória é verificado. Se exceder o valor especificado, o worker é terminado e reiniciado. O limite pode ser especificado de várias formas, e Math.floor é usado para converter o resultado em valor inteiro:

  • <= 1 - O valor é considerado uma porcentagem da memória do sistema. Ex: 0.5 define o limite como metade da memória total

  • \> 1 - Considerado um valor fixo em bytes. Devido à regra anterior, para especificar 1 byte (valor incomum), use 1.1.

  • Com unidades:

    • 50% - Porcentagem da memória total do sistema
    • 100KB, 65MB, etc - Limites fixos com unidades:
      • K / KB - Kilobytes (x1000)
      • KiB - Kibibytes (x1024)
      • M / MB - Megabytes
      • MiB - Mebibytes
      • G / GB - Gigabytes
      • GiB - Gibibytes
cuidado

Limites de memória baseados em porcentagem não funcionam em workers Linux do CircleCI devido à memória do sistema ser reportada incorretamente.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  workerIdleMemoryLimit: 0.2,
});

// [string]​

Esta opção permite comentários no package.json. Inclua o texto do comentário como o valor desta chave:

package.json
{
  "name": "my-project",
  "jest": {
    "//": "Comment goes here",
    "verbose": true
  }
}

workerThreads​

Padrão: false

Define se devem ser usados worker threads para paralelização. Por padrão, são usados processos filhos.

O uso de worker threads pode ajudar a melhorar o desempenho.

cuidado

Este é um recurso experimental. Lembre-se que as worker threads usam structured clone em vez de JSON.stringify() para serializar mensagens. Isso significa que objetos JavaScript nativos como BigInt, Map ou Set serão serializados corretamente. No entanto, propriedades adicionais definidas em Error, Map ou Set não serão passadas na etapa de serialização. Para mais detalhes, consulte o artigo sobre structured clone.