Módulos ECMAScript

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 →

cuidado

O Jest inclui suporte experimental para Módulos ECMAScript (ESM).

A implementação pode conter bugs e faltar recursos. Para o status mais recente, consulte a issue e o label no rastreador de problemas.

Além disso, observe que as APIs que o Jest usa para implementar o suporte a ESM ainda são consideradas experimentais pelo Node (na versão 18.8.0).

Com os avisos feitos, veja como ativar o suporte a ESM em seus testes.

1. Certifique-se de desabilitar as transformações de código passando transform: {} ou configure seu transformador para emitir ESM em vez do CommonJS (CJS) padrão.

2. Execute o node com --experimental-vm-modules, por exemplo: node --experimental-vm-modules node_modules/jest/bin/jest.js ou NODE_OPTIONS="$NODE_OPTIONS --experimental-vm-modules" npx jest etc.

   No Windows, você pode usar cross-env para definir variáveis de ambiente.

   Se você usa Yarn, pode utilizar yarn node --experimental-vm-modules $(yarn bin jest). Este comando também funciona se você usa Yarn Plug'n'Play.

   Se sua base de código inclui imports ESM de arquivos *.wasm, você não precisa passar --experimental-wasm-modules para o node. A implementação atual de imports WebAssembly no Jest depende de módulos VM experimentais, mas isso pode mudar no futuro.

3. Além disso, tentamos seguir a lógica do node para ativar o "modo ESM" (como verificar type no package.json ou arquivos .mjs), consulte a documentação deles para detalhes.

4. Se desejar tratar outras extensões de arquivo (como .jsx ou .ts) como ESM, use a opção extensionsToTreatAsEsm.

Diferenças entre ESM e CommonJS

A maioria das diferenças é explicada na documentação do Node, mas além disso, o Jest injeta uma variável especial em todos os arquivos executados - o objeto jest. Para acessar este objeto em ESM, você precisa importá-lo do módulo @jest/globals ou usar import.meta.

import {jest} from '@jest/globals';

jest.useFakeTimers();

// etc.

// alternatively
import.meta.jest.useFakeTimers();

// jest === import.meta.jest => true

Mock de módulos em ESM

Como o ESM avalia instruções import estáticas antes de analisar o código, o hoisting de chamadas jest.mock que ocorre no CJS não funciona para ESM. Para mockar módulos em ESM, você precisa usar require ou import() dinâmico após as chamadas jest.mock para carregar os módulos mockados - o mesmo se aplica a módulos que carregam os módulos mockados.

O mock de ESM é suportado via jest.unstable_mockModule. Como o nome sugere, esta API ainda está em desenvolvimento, acompanhe esta issue para atualizações.

O uso de jest.unstable_mockModule é essencialmente o mesmo que jest.mock, com duas diferenças: a função factory é obrigatória e pode ser síncrona ou assíncrona:

import {jest} from '@jest/globals';

jest.unstable_mockModule('node:child_process', () => ({
  execSync: jest.fn(),
  // etc.
}));

const {execSync} = await import('node:child_process');

// etc.

Para mockar módulos CJS, você deve continuar usando jest.mock. Veja o exemplo abaixo:

main.cjs

const {BrowserWindow, app} = require('electron');

// etc.

module.exports = {example};

main.test.cjs

import {createRequire} from 'node:module';
import {jest} from '@jest/globals';

const require = createRequire(import.meta.url);

jest.mock('electron', () => ({
  app: {
    on: jest.fn(),
    whenReady: jest.fn(() => Promise.resolve()),
  },
  BrowserWindow: jest.fn().mockImplementation(() => ({
    // partial mocks.
  })),
}));

const {BrowserWindow} = require('electron');
const exported = require('./main.cjs');

// alternatively
const {BrowserWindow} = (await import('electron')).default;
const exported = await import('./main.cjs');

// etc.