Módulos ECMAScript

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

precaución

Jest incluye soporte experimental para Módulos ECMAScript (ESM).

La implementación puede contener errores y carecer de funciones. Para conocer el estado más reciente, consulta el issue y la etiqueta en el rastreador de problemas.

Ten en cuenta que las APIs que Jest utiliza para implementar soporte ESM aún son consideradas experimentales por Node (a partir de la versión 18.8.0).

Hechas las advertencias, así es como activas el soporte ESM en tus pruebas.

1. Asegúrate de deshabilitar las transformaciones de código pasando transform: {} o configurando tu transformador para emitir ESM en lugar del CommonJS (CJS) predeterminado.

2. Ejecuta node con --experimental-vm-modules, por ejemplo: node --experimental-vm-modules node_modules/jest/bin/jest.js o NODE_OPTIONS="$NODE_OPTIONS --experimental-vm-modules" npx jest, etc.

   En Windows, puedes usar cross-env para establecer variables de entorno.

   Si usas Yarn, puedes emplear yarn node --experimental-vm-modules $(yarn bin jest). Este comando también funciona si usas Yarn Plug'n'Play.

   Si tu código incluye importaciones ESM de archivos *.wasm, no necesitas pasar --experimental-wasm-modules a node. La implementación actual de importaciones WebAssembly en Jest depende de módulos VM experimentales, aunque esto podría cambiar en el futuro.

3. Además de esto, intentamos seguir la lógica de node para activar el "modo ESM" (como revisar type en package.json o archivos .mjs), consulta su documentación para más detalles.

4. Si deseas tratar otras extensiones de archivo (como .jsx o .ts) como ESM, utiliza la opción extensionsToTreatAsEsm.

Diferencias entre ESM y CommonJS

La mayoría de las diferencias se explican en la documentación de Node, pero además de lo mencionado allí, Jest inyecta una variable especial en todos los archivos ejecutados: el objeto jest. Para acceder a este objeto en ESM, debes importarlo desde el módulo @jest/globals o usar import.meta.

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

jest.useFakeTimers();

// etc.

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

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

Simulación de módulos en ESM

Dado que ESM evalúa las declaraciones estáticas import antes de revisar el código, el hoisting de llamadas jest.mock que ocurre en CJS no funcionará para ESM. Para simular módulos en ESM, necesitas usar require o import() dinámico después de las llamadas jest.mock para cargar los módulos simulados. Esto mismo aplica para módulos que cargan los módulos simulados.

La simulación ESM se realiza mediante jest.unstable_mockModule. Como su nombre indica, esta API aún está en desarrollo. Sigue este issue para actualizaciones.

El uso de jest.unstable_mockModule es esencialmente igual a jest.mock con dos diferencias: la función factory es obligatoria y puede ser síncrona o así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 simular módulos CJS, debes seguir usando jest.mock. Consulta el ejemplo a continuación:

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.