Saltar al contenido principal
Versión: Siguiente

De v29 a v30

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 →

¿Actualizando Jest de la versión 29 a la 30? Esta guía te ayudará a refactorizar tu configuración y pruebas.

información

Consulta el changelog para ver la lista completa de cambios.

nota

¿Actualizas desde una versión anterior? Puedes ver la guía de actualización de v28 a v29 aquí.

Compatibilidad​

  • Jest 30 elimina soporte para Node 14, 16, 19 y 21. Las versiones mínimas soportadas son ahora 18.x. Asegúrate de usar una versión compatible de Node antes de actualizar.

  • La versión mínima de TypeScript es ahora 5.4. Actualiza TypeScript si usas definiciones de tipos de Jest (o cualquier paquete relacionado).

  • El paquete jest-environment-jsdom ahora usa JSDOM v26. Esta actualización puede introducir cambios de comportamiento en el entorno DOM. Si encuentras diferencias en el comportamiento del DOM o nuevas advertencias, consulta las notas de lanzamiento de JSDOM para v21–26.

Jest Expect y Matchers​

Eliminación de funciones matcher alias​

Se han eliminado todos los nombres alias de matchers en favor de sus nombres principales. Si usabas nombres de matchers obsoletos, deberás actualizar tus pruebas:

  • Aliases eliminados y sus reemplazos:
    • 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)
información

Estos métodos alias fueron marcados como obsoletos desde Jest 26, y en Jest 30 se eliminan completamente. Realiza una búsqueda y reemplazo global en tu códigobase para actualizar a los nombres canónicos de los matchers. La funcionalidad es idéntica: solo cambiaron los nombres de los métodos. (Si usas ESLint con eslint-plugin-jest, la regla no-alias-methods puede automatizar este proceso.)

Propiedades no enumerables​

Las propiedades no enumerables de objetos ahora se excluyen por defecto en los matchers de objetos. Esto podría afectar expect.objectContaining o verificaciones de igualdad.

Mejoras en inferencia de tipos para CalledWith​

Usuarios de TypeScript: Los tipos para la familia de matchers CalledWith (ej. toHaveBeenCalledWith) se mejoraron para inferir tipos de parámetros de funciones. Esto detectará desajustes de tipos con mayor precisión. Es un cambio de ruptura en tiempo de compilación.

Si estabas realizando aserciones con argumentos que no coinciden con los tipos de parámetro de la función real, TypeScript ahora podría generar errores en esas pruebas. Por ejemplo, si una función está tipada para aceptar un número y escribiste expect(fn).toHaveBeenCalledWith("string"), los tipos de TypeScript 5 + Jest 30 marcarán este problema. El comportamiento en tiempo de ejecución del matcher no ha cambiado.

Para corregir nuevos errores de TypeScript, asegúrate de que los argumentos de tus pruebas coincidan con los tipos esperados por la función (o usa conversiones de tipos si llamas intencionalmente con tipos diferentes).

Este cambio no afecta el tiempo de ejecución, pero puede exponer nuevos errores de tipos en tus pruebas que antes pasaban desapercibidos, haciendo tus pruebas más seguras en cuanto a tipos.

Actualizaciones de configuración​

Soporte para extensiones de archivo .mts y .cts​

Jest 30 amplía el soporte para extensiones de archivo de módulos ESM y TypeScript:

  • La configuración predeterminada de moduleFileExtensions ahora incluye .mts y .cts (módulos TypeScript ESM y CommonJS) además de las extensiones habituales.

  • Los patrones predeterminados de testMatch y testRegex se han actualizado para reconocer archivos .mjs, .cjs, .mts y .cts como archivos de prueba.

información

Si tu proyecto contiene archivos con estas extensiones que no están destinados a ser tratados como módulos o pruebas, es posible que necesites ajustar tu configuración. Por el contrario, si tienes archivos de prueba con estas extensiones, Jest ahora los detectará por defecto (puedes eliminar configuraciones personalizadas que antes se requerían para incluirlos).

--testPathPattern fue renombrado a --testPathPatterns​

Si filtran pruebas por ruta, ten en cuenta que la bandera CLI ha cambiado: --testPathPattern ahora es --testPathPatterns. Puedes pasar múltiples patrones separándolos con espacios o repitiendo la bandera. Por ejemplo:

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

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

Internamente, Jest consolida estos patrones en un objeto TestPathPatterns. Si estabas llamando programáticamente al modo watch de Jest con un testPathPattern, ahora debes construir una instancia de TestPathPatterns en su lugar.

Eliminación del comando --init​

El comando interactivo de inicialización de configuración jest --init ha sido eliminado. Este comando obsoleto se usaba para generar un archivo de configuración de Jest. Si necesitas crear una configuración, puedes ejecutar:

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

Otros cambios en la CLI​

  • Jest ahora valida las banderas CLI que requieren argumentos para asegurarse de que se proporcione uno. Por ejemplo, si usas --maxWorkers o --selectProjects, debes incluir un valor (p.ej. --maxWorkers=50%). Anteriormente, Jest podía permitir ciertas banderas sin valor (usando valores predeterminados); ahora lanzará un error si falta el valor. Asegúrate de que cualquier script o comando npm que pase banderas de Jest incluya los argumentos necesarios.

  • Si usas la opción --filter para filtrar archivos de prueba (un caso avanzado donde proporcionas una ruta a una implementación de filtro), la interfaz esperada ha cambiado. La función de filtro ahora debe devolver un objeto con la forma {filtered: Array<string>}, coincidiendo con el formato documentado. En versiones anteriores, se podía aceptar un formato de retorno diferente (p.ej., devolver un array directamente). Actualiza cualquier función de filtro de prueba personalizada para que devuelva un objeto con una propiedad filtered como se documenta.

Cambios en el comportamiento del ejecutor de pruebas​

Rechazos de promesas no manejados en las pruebas​

Jest incluye una corrección para manejar adecuadamente las promesas que son rechazadas y luego capturadas, evitando fallos falsos en las pruebas. En Jest 29, un rechazo de promesa manejado de forma asíncrona (después del tick de la prueba) aún podía causar un fallo erróneo. Jest 30 ahora espera un ciclo de evento adicional para confirmar que un rechazo de promesa permanece sin manejar antes de fallar una prueba.

información

Deberías ver menos falsos positivos en rechazos de promesas no manejadas. Las pruebas que antes fallaban por rechazos asíncronos manejados ahora deberían pasar. Sin embargo, este cambio puede ralentizar ligeramente la finalización de pruebas, especialmente en tests que rechazan promesas intencionalmente. Para mitigar el impacto en rendimiento, se introdujo una nueva bandera de configuración waitForUnhandledRejections. Esta bandera, al desactivarse, puede restaurar el comportamiento anterior (sin esperar) si es estrictamente necesario. La mayoría de usuarios no necesitarán cambiarla: el valor predeterminado ahora prioriza la corrección evitando fallos falsos.

Secuenciadores de pruebas personalizados​

Si tienes un secuenciador de pruebas personalizado (clase que hereda del TestSequencer de Jest), necesitarás actualizarlo para Jest 30. Jest ahora pasa contexto adicional al secuenciador. Específicamente, la API de TestSequencer se extendió para exponer el globalConfig y contexts en tu secuenciador.

Se requiere globalConfig en tiempo de ejecución​

Para quienes usan las APIs programáticas de Jest: construir un Runtime ahora requiere un parámetro globalConfig. Si usas jest.runCLI o ayudantes similares, asegúrate de pasar todas las opciones requeridas según la API actualizada. (El uso típico mediante CLI jest o npm test no se ve afectado).

Cambios en instantáneas y salidas​

Actualizar enlace de documentación roto​

Se eliminó la URL obsoleta goo.gl de las pruebas de instantáneas. Este cambio actualiza las instantáneas existentes para reemplazar cualquier enlace goo.gl con URLs completas sin acortar.

Causas de error en instantáneas​

La serialización de errores en instantáneas cambió. El serializador de Jest 30 ahora incluirá la propiedad cause de un Error (si está presente) al imprimir errores.

Renderización de cadenas vacías en React​

El serializador específico de React ya no renderiza hijos de cadena vacía ("") en la salida. En Jest 29, un hijo de cadena vacía en un elemento React aparecía como ""; en Jest 30 se omitirá (tratado como sin contenido).

Mejora en impresión de objetos en pretty-format​

ArrayBuffer y DataView ahora se imprimen de forma legible en lugar de como objetos con campos internos.

Cambios en la API de simulación de Jest​

Eliminación de jest.genMockFromModule​

Se eliminó la función heredada jest.genMockFromModule(moduleName). Estaba obsoleta en favor de jest.createMockFromModule(moduleName). Si aún usas genMockFromModule, cámbialo por createMockFromModule: el comportamiento es idéntico. Ejemplo:

Código antiguo (Jest 29):

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

Código nuevo (Jest 30):

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

Eliminación de tipos de funciones simuladas​

información

Estos cambios de tipos solo aplican si importas explícitamente APIs de Jest:

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

Algunos tipos de TypeScript relacionados con funciones simuladas se eliminaron de la API pública.

  • MockFunctionMetadata

  • MockFunctionMetadataType

  • SpyInstance

Si usabas jest.SpyInstance (por ejemplo, para anotar el retorno de jest.spyOn), actualiza a jest.Spied.

jest.mock solo funciona con rutas de módulo sensibles a mayúsculas​

jest.mock() solo funcionará con rutas de módulo sensibles a mayúsculas a partir de ahora. En el mejor de los casos, esto representa un caso marginal ya que la mayoría de usuarios sigue los patrones de nombres de archivo del SO. Recomendamos usar rutas de módulo con nombres correctos para evitar rupturas similares en el futuro.

Código antiguo (Jest 29):

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

Código nuevo (Jest 30):

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

Cambios en módulos y tiempo de ejecución​

Soporte para módulos ESM y reestructuración interna​

Jest introdujo cambios significativos en cómo se empaquetan y exportan sus paquetes:

  • Todos los módulos internos de Jest ahora se empaquetan en archivos únicos para un inicio más rápido. Esto significa que al instalar Jest, la cantidad de archivos que carga se reduce considerablemente (mejorando el rendimiento). Sin embargo, un efecto secundario es que cualquier importación profunda no oficial en los paquetes de Jest probablemente fallará. Por ejemplo, si antes hacías algo como require('jest-runner/build/testWorker') (que no es una API pública), esta ruta ya no existirá. Solución: Utiliza únicamente las APIs públicas o interfaces documentadas de Jest. Si dependes de un módulo interno que crees debería ser parte de la API pública, por favor abre un Pull Request para exponerlo.

  • Los paquetes de Jest ahora incluyen wrappers para ESM. Esto forma parte del trabajo continuo para permitir ejecutar Jest en contexto ESM. Todos los paquetes oficiales de Jest se exportan correctamente mediante el campo "exports" en package.json. Para la mayoría de usuarios, esto no tiene impacto directo – continúas usando Jest de la misma manera. Pero si mantienes una herramienta o plugin que importa módulos de Jest, asegúrate de usar los nombres de paquete en las importaciones (que se resolverán mediante el sistema de módulos de Node).

Estos cambios se consideran rompedores para quienes acceden a los internals de Jest, pero no para el uso típico de la CLI y configuración de Jest. Tras actualizar, ejecuta tus pruebas normalmente – si aparecen errores de resolución de módulos relacionados con los propios módulos de Jest, es probable debido a una importación no soportada que debe eliminarse o actualizarse.

Cambios en Coincidencia de Patrones Glob​

La dependencia de Jest para coincidencia de patrones de archivos (glob) se ha actualizado a v10. Glob v10 puede tener ligeras diferencias en sintaxis y comportamiento de patrones.

Un cambio notable es que glob@10 trata las expansiones de llaves y extglobs de forma algo diferente y es más estricto con ciertos patrones. Si tienes patrones personalizados en testMatch, moduleNameMapper u otra configuración basada en glob, deberían seguir funcionando en la mayoría de casos. Solo ten presente que si un patrón ya no coincide con archivos como antes, podrías necesitar ajustarlo para el nuevo motor glob.

Conclusión​

Actualiza a Jest 30 asegurándote primero que tu entorno cumple con los nuevos requisitos de Node.js y TypeScript. Actualiza tu archivo de configuración de Jest y uso de CLI para las opciones renombradas y eliminadas (notablemente testPathPatterns y la eliminación de --init). Ejecuta tu suite de pruebas y aborda cualquier fallo:

  • Corrige pruebas que usen alias de matchers eliminados reemplazándolos por los nombres oficiales.

  • Actualiza cualquier snapshot que falle debido a cambios de formato (causas de error, cadenas vacías, etc.).

  • Presta atención a errores del compilador de TypeScript – te guiarán para actualizar usos de API obsoletas (como genMockFromModule o tipos eliminados) y ajustar pruebas donde los tipos ahora son más estrictos.

¡Felices pruebas!