Ir para o conteúdo principal
Versão: 30.0

Da v29 para a v30

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 →

Atualizando do Jest v29 para o v30? Este guia ajudará na refatoração da sua configuração e testes.

"message": "informação"

Veja o changelog para a lista completa de mudanças.

"message": "nota"

Atualizando de uma versão anterior? Veja o guia de atualização da v28 para v29 aqui.

Compatibilidade​

  • O Jest 30 remove suporte para Node 14, 16, 19 e 21. As versões mínimas suportadas agora são Node 18.x. Certifique-se de usar uma versão compatível do Node antes de atualizar.

  • A versão mínima do TypeScript agora é 5.4. Atualize o TypeScript se estiver usando definições de tipos do Jest (ou de quaisquer de seus pacotes).

  • O pacote jest-environment-jsdom agora usa JSDOM v26. Esta atualização pode causar mudanças de comportamento no ambiente DOM. Se encontrar diferenças no comportamento do DOM ou novos avisos, consulte as notas de versão do JSDOM para v21–26.

Jest Expect e Matchers​

Remoção de Funções Matchers Alternativas​

Todos os nomes de matchers alternativos (aliases) foram removidos em favor dos nomes principais. Se você usava os nomes antigos e descontinuados, precisará atualizar seus testes:

  • Aliases removidos e suas substituições:
    • expect(fn).toBeCalled() → expect(fn).toHaveBeenCalled()
    • expect(fn).toBeCalledTimes(n) → expect(fn).toHaveBeenCalledTimes(n)
    • expect(fn).toBeCalledWith(arg) → expect(fn).toHaveBeenCalledWith(arg)
    • expect(fn).lastCalledWith(arg) → expect(fn).toHaveBeenLastCalledWith(arg)
    • expect(fn).nthCalledWith(n, arg) → expect(fn).toHaveBeenNthCalledWith(n, arg)
    • expect(fn).toReturn() → expect(fn).toHaveReturned()
    • expect(fn).toReturnTimes(n) → expect(fn).toHaveReturnedTimes(n)
    • expect(fn).toReturnWith(val) → expect(fn).toHaveReturnedWith(val)
    • expect(fn).lastReturnedWith(val) → expect(fn).toHaveLastReturnedWith(val)
    • expect(fn).nthReturnedWith(n, val) → expect(fn).toHaveNthReturnedWith(n, val)
    • expect(func).toThrowError(message) → expect(func).toThrow(message)
"message": "informação"

Esses métodos alternativos estavam descontinuados desde o Jest 26 e foram completamente removidos no Jest 30. Faça uma busca-e-substituição global na sua base de código para atualizar para os nomes canônicos dos matchers. A funcionalidade é idêntica — apenas os nomes dos métodos mudaram. (Se usar ESLint com eslint-plugin-jest, a regra no-alias-methods pode automatizar essa substituição.)

Propriedades não enumeráveis​

Propriedades não enumeráveis de objetos agora são excluídas dos matchers de objeto por padrão. Isso pode afetar expect.objectContaining ou verificações de igualdade.

Inferência de Tipo Aprimorada para CalledWith​

Usuários de TypeScript: Os tipos para a família de matchers CalledWith (ex: toHaveBeenCalledWith) foram aprimorados para inferir tipos de parâmetros de funções. Na maioria dos casos, isso detectará incompatibilidades de tipos com mais precisão. Esta é uma mudança de quebra de compatibilidade em tempo de compilação.

Se você estava fazendo asserções de chamadas com argumentos que não correspondem aos tipos de parâmetro reais da função, o TypeScript pode agora gerar erros nesses testes. Por exemplo, se uma função é tipada para aceitar um número e você escreveu expect(fn).toHaveBeenCalledWith("string"), os tipos do Jest 30 + TypeScript 5 vão sinalizar isso. O comportamento em tempo de execução do matcher permanece inalterado.

Para corrigir novos erros do TypeScript, garanta que os argumentos dos seus testes estejam alinhados com os tipos esperados pela função (ou use type casts se você intencionalmente chamar com tipos diferentes).

Essa alteração não impacta o tempo de execução, mas pode expor novos erros de tipo nos seus testes que passavam despercebidos anteriormente, tornando seus testes mais seguros em termos de tipo.

Atualizações de Configuração​

Suporte para extensões de arquivo .mts e .cts​

O Jest 30 expande o suporte para extensões de módulos ESM e TypeScript:

  • A configuração padrão de moduleFileExtensions agora inclui .mts e .cts (módulos TypeScript ESM e CommonJS) além das extensões usuais.

  • Os padrões testMatch e testRegex padrão foram atualizados para reconhecer arquivos .mjs, .cjs, .mts e .cts como arquivos de teste.

"message": "informação"

Se o seu projeto contiver arquivos com essas extensões que não devem ser tratados como módulos ou testes, você pode precisar ajustar sua configuração. Por outro lado, se você tiver arquivos de teste com essas extensões, o Jest agora os detectará por padrão (você pode remover configurações personalizadas que eram necessárias anteriormente para incluí-los).

--testPathPattern foi renomeado para --testPathPatterns​

Se você filtra testes por caminho, observe que a flag da CLI mudou: a flag --testPathPattern agora é --testPathPatterns. Você pode passar múltiplos padrões separando-os com espaços ou repetindo a flag. Por exemplo:

# Old (Jest 29)
jest --testPathPattern="unit/.*"

# New (Jest 30)
jest --testPathPatterns "unit/.*" "integration/.*"

Internamente, o Jest consolida esses padrões em um objeto TestPathPatterns. Se você estava chamando programaticamente o modo watch do Jest com um testPathPattern, você agora deve construir uma instância de TestPathPatterns em vez disso.

Remoção do comando --init​

O comando interativo de inicialização de configuração jest --init foi removido. Esse comando, depreciado, era usado para criar um scaffold de arquivo de configuração do Jest. Se você precisa criar uma configuração, você pode executar:

npm init jest@latest
# Or for Yarn
yarn create jest
# Or for pnpm
pnpm create jest

Outras Mudanças na CLI​

  • O Jest agora valida flags da CLI que exigem argumentos para garantir que um argumento seja fornecido. Por exemplo, se você usar --maxWorkers ou --selectProjects, você deve incluir um valor (ex.: --maxWorkers=50%). Anteriormente, o Jest podia permitir certas flags sem um valor (recorrendo a padrões); agora ele lançará um erro se o valor estiver ausente. Garanta que quaisquer scripts ou comandos npm que passam flags para o Jest incluam os argumentos necessários.

  • Se você usar a opção --filter para filtrar arquivos de teste (um caso de uso avançado em que você fornece um caminho para uma implementação de filtro), a interface esperada mudou. A função de filtro agora deve retornar um objeto no formato {filtered: Array<string>}, correspondendo ao formato documentado. Em versões anteriores, um formato de retorno diferente podia ser aceito (ex.: retornar um array diretamente). Atualize quaisquer funções de filtro de teste personalizadas para retornar um objeto com uma propriedade filtered como documentado.

Mudanças de Comportamento no Test Runner​

Rejeições de Promessas Não Tratadas em Testes​

O Jest inclui uma correção para lidar adequadamente com promessas que são rejeitadas e depois capturadas, evitando falhas falsas nos testes. No Jest 29, uma rejeição de promessa que era tratada de forma assíncrona (após o tick do teste) ainda podia fazer o teste falhar erroneamente. O Jest 30 agora espera um turno extra de event loop para confirmar que uma rejeição de promessa permanece não tratada antes de falhar um teste.

"message": "informação"

Você deve observar menos falsos positivos para rejeições de promessas não tratadas. Testes que antes falhavam devido a rejeições assíncronas tratadas agora devem passar. Entretanto, essa mudança pode desacelerar levemente a conclusão dos testes, especialmente em testes que rejeitam promessas intencionalmente. Para mitigar o impacto no desempenho, foi introduzida uma nova flag de configuração waitForUnhandledRejections. Essa flag, quando desabilitada, pode restaurar o comportamento anterior (sem esperar) se absolutamente necessário. A maioria dos usuários não precisará alterar isso – o padrão agora favorece a correção ao evitar falhas falsas.

Sequenciadores de Teste Personalizados​

Se você possui um sequenciador de teste personalizado (uma classe que herda do TestSequencer do Jest), será necessário atualizá-lo para o Jest 30. O Jest agora passa contexto adicional ao sequenciador de testes. Especificamente, a API do TestSequencer foi estendida para expor o globalConfig e contexts ao seu sequenciador.

globalConfig Obrigatório no Runtime​

Para quem usa as APIs programáticas do Jest: construir um Runtime agora requer um parâmetro globalConfig. Se você usa jest.runCLI ou helpers similares, garanta que passa todas as opções necessárias conforme a API atualizada. (O uso típico do CLI jest ou npm test não é afetado por essa mudança.)

Alterações em Snapshots e Saída​

URLs goo.gl obsoletas foram removidas dos testes de snapshot. Essa mudança atualiza snapshots existentes para substituir quaisquer links goo.gl por URLs completas, não encurtadas.

Causas de Erro em Snapshots​

A serialização de erros em snapshots mudou. O serializer de snapshot do Jest 30 agora incluirá a propriedade cause de um Error (se presente) ao imprimir erros.

Renderização de String Vazia no React​

O serializer de snapshot específico para React não renderiza mais filhos de string vazia ("") na saída. No Jest 29, um filho de string vazia em um elemento React podia aparecer como "" na saída do snapshot; no Jest 30 ele será omitido (tratado como sem conteúdo).

Melhoria na Impressão de Objetos em pretty-format​

ArrayBuffer e DataView agora são impressos de forma legível por humanos em vez de como objetos com campos internos.

Mudanças na API de Mock do Jest​

jest.genMockFromModule Removido​

A função legada jest.genMockFromModule(moduleName) foi removida. Ela foi previamente descontinuada em favor de jest.createMockFromModule(moduleName). Se você ainda usa genMockFromModule, migre para createMockFromModule – o comportamento é o mesmo. Por exemplo:

Código antigo (Jest 29):

const mockFs = jest.genMockFromModule('fs');

Código novo (Jest 30):

const mockFs = jest.createMockFromModule('fs');

Remoção de Tipos de Função Mock​

"message": "informação"

As mudanças de tipo só se aplicam se você importar explicitamente as APIs do Jest:

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

Alguns tipos TypeScript relacionados a funções mock foram removidos da API pública.

  • MockFunctionMetadata

  • MockFunctionMetadataType

  • SpyInstance

Se você usava jest.SpyInstance (por exemplo, para anotar o retorno de jest.spyOn), atualize para usar jest.Spied.

jest.mock funciona apenas com caminho de módulo que respeita maiúsculas/minúsculas​

A partir de agora, o jest.mock() só funcionará com caminhos de módulo que respeitem maiúsculas e minúsculas. Embora seja um caso raro (já que a maioria dos usuários segue o comportamento do sistema de arquivos do SO), recomendamos usar caminhos de módulo com nomeação correta para evitar problemas semelhantes no futuro.

Código antigo (Jest 29):

jest.mock('./path/to/FILENAME.js'); // This works EVEN when you only have `filename.js`

Código novo (Jest 30):

jest.mock('./path/to/filename.js'); // This strictly works when you ONLY have `filename.js`

Mudanças em Módulos e Runtime​

Suporte a Módulos ESM e Reestruturação Interna​

O Jest introduziu mudanças significativas na forma como seus pacotes são empacotados e exportados:

  • Todos os módulos internos do Jest agora são empacotados em arquivos únicos para inicialização mais rápida. Isso significa que ao instalar o Jest, o número de arquivos carregados é drasticamente reduzido (melhorando o desempenho). Porém, um efeito colateral é que qualquer importação não oficial em profundidade nos pacotes do Jest provavelmente será quebrada. Por exemplo, se você fazia algo como require('jest-runner/build/testWorker') (que não é uma API pública), esse caminho não existirá mais. Solução: Use apenas as APIs públicas ou interfaces documentadas do Jest. Se você depende de um módulo interno que acredita dever fazer parte da API pública, abra um Pull Request para expô-lo.

  • Os pacotes do Jest agora fornecem wrappers ESM. Isso faz parte do trabalho contínuo para permitir a execução do Jest em contexto ESM. Todos os pacotes oficiais do Jest agora exportam corretamente através do campo "exports" no package.json. Para a maioria dos usuários, não há impacto direto – você continua usando o Jest da mesma forma. Mas se você mantém uma ferramenta ou plugin que importa módulos do Jest, garanta que usa os nomes dos pacotes nas importações (que serão resolvidos via sistema de módulos do Node).

Essas mudanças são consideradas quebra para quem acessa os internals do Jest, mas não para o uso típico da CLI e configuração do Jest. Após a atualização, execute seus testes normalmente – se ocorrerem erros de resolução de módulos relacionados aos próprios módulos do Jest, provavelmente é devido a uma importação não suportada que precisa ser removida ou atualizada.

Mudanças na Correspondência de Padrões Glob​

A dependência do Jest para correspondência de padrões de arquivos (glob) foi atualizada para v10. O Glob v10 pode ter diferenças sutis na sintaxe e comportamento de padrões.

Uma mudança notável é que o glob@10 trata expansões de chaves e extglobs de forma um pouco diferente e é mais rigoroso com alguns padrões. Se você tem padrões personalizados em testMatch, moduleNameMapper ou outras configurações baseadas em glob, eles devem continuar funcionando na maioria dos casos. Apenas esteja ciente que se algum padrão não corresponder aos arquivos como antes, talvez seja necessário ajustá-lo para o novo motor glob.

Conclusão​

Atualize para o Jest 30 primeiro garantindo que seu ambiente atende aos novos requisitos de Node.js e TypeScript. Atualize seu arquivo de configuração do Jest e uso da CLI para as opções renomeadas e removidas (notavelmente testPathPatterns e a remoção de --init). Execute sua suíte de testes e corrija eventuais falhas:

  • Corrija testes que usam aliases de matchers removidos substituindo-os pelos nomes oficiais.

  • Atualize snapshots que falharem devido a mudanças de formatação (causas de erro, strings vazias, etc.).

  • Atenção a erros do compilador TypeScript – eles guiarão você para atualizar usos de APIs depreciadas (como genMockFromModule ou tipos removidos) e ajustar testes onde os tipos estão mais rigorosos.

Bons testes!