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

Opções da CLI do 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 →

O executor de linha de comando jest oferece várias opções úteis. Você pode executar jest --help para ver todas as opções disponíveis. Muitas das opções listadas abaixo também podem ser combinadas para executar testes exatamente como desejar. Todas as opções de Configuração do Jest também podem ser especificadas pela CLI.

Aqui está uma visão geral rápida:

Executando a partir da linha de comando​

Executar todos os testes (padrão):

jest

Executar apenas os testes especificados por padrão ou nome de arquivo:

jest my-test #or
jest path/to/my-test.js

Executar testes relacionados a arquivos alterados com base no hg/git (arquivos não commitados):

jest -o

Executar testes relacionados a path/to/fileA.js e path/to/fileB.js:

jest --findRelatedTests path/to/fileA.js path/to/fileB.js

Executar testes que correspondam a este nome de spec (basicamente, corresponde ao nome em describe ou test).

jest -t name-of-spec

Executar modo de observação (watch mode):

jest --watch #runs jest -o by default
jest --watchAll #runs all tests

O modo de observação também permite especificar o nome ou caminho de um arquivo para focar em um conjunto específico de testes.

Usando com gerenciador de pacotes​

Se você executar o Jest através do seu gerenciador de pacotes, ainda pode passar argumentos de linha de comando diretamente como argumentos do Jest.

Em vez de:

jest -u -t="ColorPicker"

você pode usar:

npm test -- -u -t="ColorPicker"

Suporte a argumentos em camelCase e hifenizados​

O Jest suporta formatos de argumentos em camelCase e hifenizados. Os exemplos a seguir terão resultados idênticos:

jest --collect-coverage
jest --collectCoverage

Argumentos também podem ser misturados:

jest --update-snapshot --detectOpenHandles

Opções​

"message": "nota"

Opções da CLI têm precedência sobre os valores do Configuration.

Referência​

jest <regexForTestFiles>​

Quando você executa jest com um argumento, esse argumento é tratado como uma expressão regular para correspondência de arquivos em seu projeto. É possível executar conjuntos de testes fornecendo um padrão. Apenas os arquivos que corresponderem ao padrão serão selecionados e executados. Dependendo do seu terminal, talvez seja necessário colocar esse argumento entre aspas: jest "my.*(complex)?pattern". No Windows, você precisará usar / como separador de caminho ou escapar \ como \\.

--bail[=<n>]​

Apelido: -b. Encerra imediatamente o conjunto de testes após n falhas de suíte de teste. O padrão é 1.

--cache​

Define se o cache deve ser usado. O padrão é true. Desative o cache usando --no-cache.

cuidado

O cache só deve ser desativado se você estiver enfrentando problemas relacionados a cache. Em média, desativar o cache torna o Jest pelo menos duas vezes mais lento.

Se quiser inspecionar o cache, use --showConfig e verifique o valor de cacheDirectory. Se precisar limpar o cache, use --clearCache.

--changedFilesWithAncestor​

Executa testes relacionados às alterações atuais e às alterações do último commit. Comporta-se de forma semelhante a --onlyChanged.

--changedSince​

Executa testes relacionados às alterações desde o branch ou hash de commit fornecido. Se o branch atual divergir do branch fornecido, apenas alterações locais serão testadas. Comporta-se de forma semelhante a --onlyChanged.

--ci​

Quando esta opção é fornecida, o Jest assume que está sendo executado em um ambiente de CI. Isso altera o comportamento quando um novo snapshot é encontrado. Em vez do comportamento normal de armazenar automaticamente um novo snapshot, o teste falhará e exigirá que o Jest seja executado com --updateSnapshot.

--clearCache​

Exclui o diretório de cache do Jest e encerra a execução sem rodar os testes. Irá excluir o cacheDirectory se a opção for fornecida, ou o diretório de cache padrão do Jest. O diretório de cache padrão pode ser encontrado executando jest --showConfig.

cuidado

Limpar o cache reduzirá o desempenho.

--clearMocks​

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.

--collectCoverageFrom=<glob>​

Padrão glob relativo ao rootDir que corresponde aos arquivos dos quais as informações de cobertura precisam ser coletadas.

--colors​

Força a exibição de cores na saída de resultados de teste mesmo quando o stdout não é um TTY.

"message": "nota"

Alternativamente, você pode definir a variável de ambiente FORCE_COLOR=true para ativar cores forçadamente ou FORCE_COLOR=false para desativar. O uso de FORCE_COLOR sobre todas as outras verificações de suporte a cores.

--config=<path>​

Alias: -c. O caminho para um arquivo de configuração do Jest que especifica como encontrar e executar testes. Se nenhum rootDir estiver definido na configuração, o diretório contendo o arquivo de configuração será considerado o rootDir do projeto. Também pode ser um valor codificado em JSON que o Jest usará como configuração.

--coverage[=<boolean>]​

Alias: --collectCoverage. Indica que as informações de cobertura de testes devem ser coletadas e relatadas na saída. Opcionalmente passe <boolean> para substituir a opção definida na configuração.

--coverageDirectory=<path>​

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

--coverageProvider=<provider>​

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

--debug​

Exibe informações de depuração sobre sua configuração do Jest.

--detectOpenHandles​

Tenta coletar e exibir handles abertos que impedem o Jest de encerrar corretamente. Use em casos onde você precisa usar --forceExit para o Jest encerrar, para rastrear possíveis causas. Implica --runInBand, fazendo os testes rodarem em série. Implementado usando async_hooks. Esta opção tem penalidade significativa de desempenho e deve ser usada apenas para depuração.

--env=<environment>​

O ambiente de teste usado para todos os testes. Pode apontar para qualquer arquivo ou módulo node. Exemplos: jsdom, node ou path/to/my-environment.js.

--errorOnDeprecated​

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

--expand​

Alias: -e. Use esta flag para mostrar diferenças completas e erros ao invés de um patch.

--filter=<file>​

Caminho para um módulo que exporta uma função de filtragem. Esta função assíncrona recebe uma lista de caminhos de testes que podem ser manipulados para excluir testes da execução e deve retornar um objeto com formato { filtered: Array<string> } contendo os testes que devem ser executados pelo Jest. Especialmente útil quando usado com infraestrutura de testes para filtrar testes conhecidamente problemáticos.

my-filter.js
// This filter when applied will only run tests ending in .spec.js (not the best way to do it, but it's just an example):
const filteringFunction = testPath => testPath.endsWith('.spec.js');

module.exports = testPaths => {
  const allowedPaths = testPaths.filter(filteringFunction); // ["path1.spec.js", "path2.spec.js", etc]

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>​

Encontra e executa os testes que cobrem uma lista separada por espaços de arquivos fonte passados como argumentos. Útil para integração com hooks de pre-commit para executar a quantidade mínima necessária de testes. Pode ser usado com --coverage para incluir cobertura de testes para os arquivos fonte, sem necessidade de argumentos --collectCoverageFrom duplicados.

--forceExit​

Força o Jest a encerrar após a conclusão de todos os testes. Útil quando recursos configurados pelo código de teste não podem ser limpos adequadamente.

cuidado

Este recurso é uma solução de emergência. Se o Jest não encerrar ao final da execução dos testes, significa que recursos externos ainda estão sendo retidos ou temporizadores pendentes existem no seu código. Recomenda-se liberar recursos externos após cada teste para garantir que o Jest possa encerrar corretamente. Use --detectOpenHandles para ajudar a rastrear o problema.

--help​

Exibe informações de ajuda, semelhantes a esta página.

--ignoreProjects <project1> ... <projectN>​

Ignora os testes dos projetos especificados. O Jest usa o atributo displayName na configuração para identificar cada projeto. Ao usar esta opção, defina um displayName para todos os projetos.

--injectGlobals​

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.

--json​

Imprime os resultados dos testes em JSON. Este modo envia todas outras saídas de teste e mensagens do usuário para stderr.

--lastCommit​

Executa todos os testes afetados por alterações de arquivo no último commit. Comporta-se como --onlyChanged.

--listTests​

Lista todos os arquivos de teste que o Jest executará com os argumentos fornecidos e encerra.

--logHeapUsage​

Registra o uso de heap após cada teste. Útil para depurar vazamentos de memória. Use com --runInBand e --expose-gc no Node.

--maxConcurrency=<num>​

Impede que o Jest execute mais que o número especificado de testes simultaneamente. Afeta apenas testes que usam test.concurrent.

--maxWorkers=<num>|<string>​

Alias: -w. Define o número máximo de workers que o pool criará para executar testes. No modo de execução única, padrão é núcleos disponíveis menos um. No modo watch, padrão é metade dos núcleos para evitar sobrecarga. Ajuste útil em ambientes limitados como CIs.

Para ambientes com CPUs variáveis, use configuração percentual: --maxWorkers=50%

--noStackTrace​

Desabilita stack traces na saída de resultados de testes.

--notify​

Ativa notificações nativas do SO para resultados de testes. Requer instalação separada do pacote node-notifier.

--onlyChanged​

Alias: -o. Tenta identificar quais testes executar com base em arquivos alterados no repositório atual. Funciona apenas em repositórios git/hg com grafos de dependência estáticos.

--onlyFailures​

Alias: -f. Executa testes que falharam na execução anterior.

--openHandlesTimeout=<milliseconds>​

Quando --detectOpenHandles e --forceExit estão desabilitadas, o Jest imprimirá um aviso se o processo não tiver sido encerrado corretamente após esse número de milissegundos. Um valor de 0 desabilita o aviso. O padrão é 1000.

--outputFile=<filename>​

Escreve os resultados dos testes em um arquivo quando a opção --json também for especificada. A estrutura JSON retornada está documentada em testResultsProcessor.

--passWithNoTests​

Permite que o conjunto de testes seja aprovado quando nenhum arquivo for encontrado.

--projects <path1> ... <pathN>​

Executa testes de um ou mais projetos, encontrados nos caminhos especificados; também aceita globs de caminho. Esta opção é equivalente à opção de configuração projects na CLI.

"message": "nota"

Se arquivos de configuração forem encontrados nos caminhos especificados, todos os projetos especificados nesses arquivos de configuração serão executados.

--randomize​

Embaralha a ordem dos testes em um arquivo. O embaralhamento é baseado na semente. Veja --seed=<num> para mais informações.

O valor da semente é exibido quando esta opção é definida. Equivalente a definir a opção da CLI --showSeed.

jest --randomize --seed 1234
"message": "nota"

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

--reporters​

Executa testes com os repórteres especificados. Opções de repórter não estão disponíveis via CLI. Exemplo com múltiplos repórteres:

jest --reporters="default" --reporters="jest-junit"

--resetMocks​

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.

--restoreMocks​

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.

--roots​

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

--runInBand​

Apelido: -i. Executa todos os testes em série no processo atual, em vez de criar um pool de workers de processos filhos que executam os testes. Isso pode ser útil para depuração.

--runTestsByPath​

Executa apenas os testes que foram especificados com seus caminhos exatos. Isso evita convertê-los em uma expressão regular e compará-la com cada arquivo.

Por exemplo, dada a seguinte estrutura de arquivos:

__tests__
└── t1.test.js # test
└── t2.test.js # test

Quando executado com um padrão, nenhum teste é encontrado:

jest --runTestsByPath __tests__/t

No entanto, passar um caminho exato executará apenas o teste fornecido:

No tests found

No entanto, passar um caminho exato executará apenas o teste fornecido:

jest --runTestsByPath __tests__/t1.test.js

No entanto, passar um caminho exato executará apenas o teste fornecido:

PASS __tests__/t1.test.js
"message": "dica"

A correspondência de regex padrão funciona bem em execuções pequenas, mas fica lenta se for fornecida com múltiplos padrões e/ou contra muitos testes. Esta opção substitui a lógica de correspondência de regex e, com isso, otimiza o tempo que o Jest leva para filtrar arquivos de teste específicos.

--seed=<num>​

Define um valor de semente que pode ser recuperado em um arquivo de teste via jest.getSeed(). O valor da semente deve estar entre -0x80000000 e 0x7fffffff inclusive (-2147483648 (-(2 ** 31)) e 2147483647 (2 ** 31 - 1) em decimal).

jest --seed=1324

Se esta opção não for especificada, o Jest gerará o valor aleatoriamente. Você pode usar a flag --showSeed para exibir a semente no resumo do relatório de testes.

O Jest usa internamente a semente para embaralhar a ordem de execução dos suites de teste. Se a opção --randomize for usada, a semente também será usada para embaralhar a ordem dos testes dentro de cada bloco describe. Ao lidar com testes instáveis, reexecutar com a mesma semente pode ajudar a reproduzir a falha.

--selectProjects <project1> ... <projectN>​

Executa os testes dos projetos especificados. O Jest usa o atributo displayName na configuração para identificar cada projeto. Se você usar esta opção, deve fornecer um displayName para todos os seus projetos.

--setupFilesAfterEnv <path1> ... <pathN>​

Uma lista de caminhos para módulos que executam algum código para configurar ou preparar o ambiente de teste antes de cada teste. Observe que arquivos importados pelos scripts de configuração não serão simulados durante os testes.

--shard​

O fragmento (shard) do suite de testes a ser executado, no formato (?<shardIndex>\d+)/(?<shardCount>\d+).

shardIndex indica qual fragmento selecionar, enquanto shardCount controla o número total de fragmentos em que o suite será dividido.

shardIndex e shardCount devem ser números positivos baseados em 1, e shardIndex deve ser menor ou igual a shardCount.

Quando shard é especificado, o testSequencer configurado deve implementar um método shard.

Por exemplo, para dividir o suite em três fragmentos, cada um executando um terço dos testes:

jest --shard=1/3
jest --shard=2/3
jest --shard=3/3

--showConfig​

Exibe sua configuração do Jest e encerra a execução.

--showSeed​

Exibe o valor da semente no resumo do relatório de testes. Consulte --seed=<num> para detalhes.

Também pode ser definido na configuração. Veja showSeed.

--silent​

Impede que os testes exibam mensagens no console.

--testEnvironmentOptions=<json string>​

Uma string JSON com opções que serão passadas ao testEnvironment. As opções relevantes dependem do ambiente.

--testLocationInResults​

Adiciona um campo location aos resultados dos testes. Útil se você deseja reportar a localização de um teste em um reporter.

"message": "nota"

No objeto resultante, column é indexado em 0 enquanto line não é:

{
  "column": 4,
  "line": 5
}

--testMatch glob1 ... globN​

Os padrões glob que o Jest usa para detectar arquivos de teste. Consulte a configuração testMatch para detalhes.

--testNamePattern=<regex>​

Alias: -t. Execute apenas testes cujo nome corresponda à expressão regular. Por exemplo, suponha que você queira executar apenas testes relacionados à autenticação, que terão nomes como 'GET /api/posts with auth'. Nesse caso, você pode usar jest -t=auth.

A expressão regular é comparada com o nome completo, que combina o nome do teste com todos os blocos describe que o envolvem.

--testPathIgnorePatterns=<regex>|[array]​

Um padrão regex único ou um array de padrões que são testados contra todos os caminhos de testes antes da execução. Ao contrário de --testPathPatterns, ele executará apenas os testes cujo caminho não corresponda às expressões regulares fornecidas.

Para passar como array, use parênteses escapados e padrões regex delimitados por espaços, como \(/node_modules/ /tests/e2e/\). Alternativamente, você pode omitir os parênteses combinando os padrões em uma única regex como /node_modules/|/tests/e2e/. Esses dois exemplos são equivalentes.

--testPathPatterns=<regex>​

Um padrão regex que é comparado com todos os caminhos de testes antes da execução. No Windows, você precisará usar / como separador de caminho ou escapar \ como \\.

--testRunner=<path>​

Permite especificar um executor de testes personalizado.

--testSequencer=<path>​

Permite especificar um sequenciador de testes personalizado. Consulte a configuração testSequencer para detalhes.

--testTimeout=<number>​

Tempo limite padrão para um teste em milissegundos. Valor padrão: 5000.

--updateSnapshot​

Alias: -u. Use esta flag para regravar todos os snapshots que falharem durante esta execução de testes. Pode ser usado com um padrão de suíte de testes ou com --testNamePattern para regravar snapshots.

--useStderr​

Redireciona toda a saída para stderr.

--verbose​

Exibe resultados individuais de testes com a hierarquia da suíte de testes.

--version​

Alias: -v. Exibe a versão e encerra.

--waitForUnhandledRejections​

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.

--watch​

Observa arquivos para alterações e reexecuta testes relacionados aos arquivos modificados. Se quiser reexecutar todos os testes quando um arquivo mudar, use --watchAll.

Use --no-watch (ou --watch=false) para desativar explicitamente o modo watch se ele foi habilitado via --watch. Na maioria dos ambientes de CI, isso é tratado automaticamente.

--watchAll​

Observa arquivos para alterações e reexecuta todos os testes quando algo muda. Se quiser reexecutar apenas os testes dependentes dos arquivos modificados, use --watch.

Use --no-watchAll (ou --watchAll=false) para desativar explicitamente o modo watch se ele foi habilitado via --watchAll. Na maioria dos ambientes de CI, isso é tratado automaticamente.

--watchman​

Define se o watchman deve ser usado para rastreamento de arquivos. O padrão é true. Desative usando --no-watchman.

--workerThreads​

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

cuidado

Este é um recurso experimental. Consulte a opção de configuração workerThreads para mais detalhes.