Como configurar o Jest para usar TypeScript com ESModules

Passo a passo para rodar testes com Jest em projetos TypeScript usando ESModules

Publicado em 31 mai. de 2025 · Escrito por Fernando

Se você já tentou usar o Jest em um projeto TypeScript moderno com suporte a ESModules, provavelmente percebeu que as coisas não funcionam “de primeira”. Neste post, vou mostrar como configurar o Jest corretamente nesse cenário, considerando algumas exigências específicas do TypeScript quando usamos os modos module: "NodeNext" e moduleResolution: "NodeNext".

Instalando o ts-jest

O primeiro passo é instalar o ts-jest, que é um pré-processador do Jest para projetos TypeScript:

npm install --save-dev jest ts-jest typescript

Configurando o ts-jest

Vamos usar o preset createDefaultEsmPreset fornecido pelo ts-jest para suportar ESModules. Abaixo está um exemplo do arquivo jest.config.js:

// jest.config.js

import { createDefaultEsmPreset } from "ts-jest";

const presetConfig = createDefaultEsmPreset({
  // Você pode passar opções adicionais aqui, se necessário
});

const jestConfig = {
  ...presetConfig,
  moduleNameMapper: {
    "(.+)\\.js": "$1",
  },
  testPathIgnorePatterns: ["dist/", "node_modules/"],
};

export default jestConfig;

Por que usar moduleNameMapper?

Quando usamos o TypeScript com moduleResolution: "NodeNext", somos obrigados a usar extensões nos imports — por exemplo, import { algo } from './util.js'. Isso pode causar problemas para o ts-jest, que não consegue reconhecer os imports com .js automaticamente. A configuração abaixo resolve isso:

moduleNameMapper: {
  "(.+)\\.js": "$1",
}

Ela faz com que o Jest trate os imports terminados em .js como se não tivessem extensão.

Ignorando diretórios desnecessários

Também adicionamos a configuração:

testPathIgnorePatterns: ["dist/", "node_modules/"]

Assim, o Jest não tenta rodar testes em arquivos da pasta dist/ (build) nem em node_modules.

Ajustes no tsconfig.json

Para que tudo funcione corretamente com NodeNext, é necessário ativar o modo de módulos isolados:

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "isolatedModules": true
  }
}

A opção isolatedModules é obrigatória nesse modo e ajuda o TypeScript a compilar corretamente arquivos de forma independente.

Rodando os testes com suporte a ESModules

Por fim, para que o Jest funcione com ESModules, precisamos ativar uma flag experimental no Node.js ao rodar os testes:

node --experimental-vm-modules node_modules/jest/bin/jest.js

Você pode adicionar esse comando no seu package.json, em um script como este: