Saltar al contenido principal
Versión: 30.0

Opciones de CLI de Jest

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 →

El ejecutor de línea de comandos jest tiene varias opciones útiles. Puedes ejecutar jest --help para ver todas las opciones disponibles. Muchas de las opciones mostradas a continuación también pueden combinarse para ejecutar pruebas exactamente como deseas. Cualquier opción de Configuración de Jest también puede especificarse mediante la CLI.

Aquí tienes un resumen breve:

Ejecución desde la línea de comandos​

Ejecutar todas las pruebas (predeterminado):

jest

Ejecutar solo las pruebas especificadas con un patrón o nombre de archivo:

jest my-test #or
jest path/to/my-test.js

Ejecutar pruebas relacionadas con archivos modificados según hg/git (archivos no confirmados):

jest -o

Ejecutar pruebas relacionadas con path/to/fileA.js y path/to/fileB.js:

jest --findRelatedTests path/to/fileA.js path/to/fileB.js

Ejecutar pruebas que coincidan con este nombre de spec (básicamente, coincide con el nombre en describe o test).

jest -t name-of-spec

Ejecutar en modo watch:

jest --watch #runs jest -o by default
jest --watchAll #runs all tests

El modo watch también permite especificar el nombre o ruta de un archivo para enfocarse en un conjunto específico de pruebas.

Uso con gestores de paquetes​

Si ejecutas Jest mediante tu gestor de paquetes, aún puedes pasar los argumentos de línea de comandos directamente como argumentos de Jest.

En lugar de:

jest -u -t="ColorPicker"

puedes usar:

npm test -- -u -t="ColorPicker"

Soporte para args en camelCase y guiones​

Jest admite formatos de argumentos tanto en camelCase como con guiones. Los siguientes ejemplos tendrán resultados equivalentes:

jest --collect-coverage
jest --collectCoverage

Los argumentos también pueden mezclarse:

jest --update-snapshot --detectOpenHandles

Opciones​

nota

Las opciones de CLI tienen prioridad sobre los valores de la Configuración.

Referencia​

jest <regexForTestFiles>​

Cuando ejecutas jest con un argumento, ese argumento se trata como una expresión regular para coincidir con archivos en tu proyecto. Es posible ejecutar conjuntos de pruebas proporcionando un patrón. Solo se seleccionarán y ejecutarán los archivos que coincidan con el patrón. Según tu terminal, es posible que necesites entrecomillar este argumento: jest "my.*(complex)?pattern". En Windows, deberás usar / como separador de rutas o escapar \ como \\.

--bail[=<n>]​

Alias: -b. Sale inmediatamente del conjunto de pruebas tras n número de conjuntos de pruebas fallidos. Por defecto es 1.

--cache​

Determina si se usa la caché. Por defecto es true. Desactiva la caché usando --no-cache.

precaución

La caché solo debe desactivarse si experimentas problemas relacionados con el almacenamiento en caché. En promedio, desactivar la caché hace que Jest sea al menos dos veces más lento.

Si deseas inspeccionar la caché, usa --showConfig y busca el valor de cacheDirectory. Si necesitas borrar la caché, usa --clearCache.

--changedFilesWithAncestor​

Ejecuta pruebas relacionadas con los cambios actuales y los cambios del último commit. Se comporta de manera similar a --onlyChanged.

--changedSince​

Ejecuta pruebas relacionadas con los cambios desde la rama o hash de commit proporcionado. Si la rama actual ha divergido de la rama dada, solo se probarán los cambios locales. Se comporta de manera similar a --onlyChanged.

--ci​

Cuando se proporciona esta opción, Jest asumirá que se ejecuta en un entorno de CI. Esto cambia el comportamiento cuando se encuentra un nuevo snapshot. En lugar del comportamiento habitual de almacenar automáticamente un nuevo snapshot, fallará la prueba y requerirá ejecutar Jest con --updateSnapshot.

--clearCache​

Elimina el directorio de caché de Jest y luego sale sin ejecutar pruebas. Eliminará cacheDirectory si se pasa esta opción, o el directorio de caché predeterminado de Jest. El directorio de caché predeterminado se puede encontrar ejecutando jest --showConfig.

precaución

Limpiar la caché reducirá el rendimiento.

--clearMocks​

Borra automáticamente las llamadas, instancias, contextos y resultados de los mocks antes de cada prueba. Equivale a llamar a jest.clearAllMocks() antes de cada prueba. Esto no elimina ninguna implementación de mock que se haya proporcionado.

--collectCoverageFrom=<glob>​

Patrón glob relativo a rootDir que coincide con los archivos de los que se debe recopilar información de cobertura.

--colors​

Fuerza el resaltado de los resultados de las pruebas incluso si stdout no es una terminal TTY.

nota

Alternativamente, puedes establecer la variable de entorno FORCE_COLOR=true para habilitar forzadamente o FORCE_COLOR=false para deshabilitar la salida con colores. El uso de FORCE_COLOR anula todas las demás comprobaciones de soporte de color.

--config=<path>​

Alias: -c. La ruta al archivo de configuración de Jest que especifica cómo encontrar y ejecutar pruebas. Si no se establece rootDir en la configuración, se asume que el directorio que contiene el archivo de configuración es el rootDir del proyecto. También puede ser un valor codificado en JSON que Jest usará como configuración.

--coverage[=<boolean>]​

Alias: --collectCoverage. Indica que se debe recopilar y reportar información de cobertura de pruebas en la salida. Opcionalmente pasa <boolean> para anular la opción establecida en la configuración.

--coverageDirectory=<path>​

El directorio donde Jest debe guardar sus archivos de cobertura.

--coverageProvider=<provider>​

Indica qué proveedor usar para instrumentar el código para cobertura. Valores permitidos: babel (predeterminado) o v8.

--debug​

Imprime información de depuración sobre tu configuración de Jest.

--detectOpenHandles​

Intenta recopilar e imprimir manejadores abiertos que impiden que Jest salga limpiamente. Usa esto en casos donde necesitas usar --forceExit para que Jest salga y así poder rastrear la razón. Esto implica --runInBand, haciendo que las pruebas se ejecuten en serie. Implementado usando async_hooks. Esta opción tiene una penalización significativa de rendimiento y solo debe usarse para depuración.

--env=<environment>​

El entorno de prueba usado para todas las pruebas. Puede apuntar a cualquier archivo o módulo de node. Ejemplos: jsdom, node o path/to/my-environment.js.

--errorOnDeprecated​

Hace que llamar a APIs obsoletas genere mensajes de error útiles. Facilita el proceso de actualización.

--expand​

Alias: -e. Usa esta bandera para mostrar diferencias completas y errores en lugar de un parche.

--filter=<file>​

Ruta a un módulo que exporte una función de filtrado. Esta función asíncrona recibe una lista de rutas de pruebas que pueden manipularse para excluir pruebas de la ejecución y debe devolver un objeto con la forma { filtered: Array<string> } que contenga las pruebas que Jest debe ejecutar. Especialmente útil cuando se usa junto con una infraestructura de pruebas para filtrar pruebas defectuosas conocidas.

my-filter.js
// This filter when applied will only run tests ending in .spec.js (not the best way to do it, but it's just an example):
const filteringFunction = testPath => testPath.endsWith('.spec.js');

module.exports = testPaths => {
  const allowedPaths = testPaths.filter(filteringFunction); // ["path1.spec.js", "path2.spec.js", etc]

  return {
    filtered: allowedPaths,
  };
};

--findRelatedTests <spaceSeparatedListOfSourceFiles>​

Encuentra y ejecuta las pruebas que cubren una lista separada por espacios de archivos fuente pasados como argumentos. Útil para integración con hooks de pre-commit para ejecutar la cantidad mínima de pruebas necesarias. Puede usarse junto con --coverage para incluir una cobertura de pruebas para los archivos fuente, sin necesidad de argumentos duplicados --collectCoverageFrom.

--forceExit​

Fuerza a Jest a salir después de completar todos los tests. Es útil cuando recursos configurados por el código de pruebas no pueden limpiarse adecuadamente.

precaución

Esta característica es un último recurso. Si Jest no sale al final de una ejecución, significa que aún hay recursos externos retenidos o temporizadores pendientes en tu código. Se recomienda liberar recursos externos después de cada prueba para asegurar un cierre limpio. Puedes usar --detectOpenHandles para ayudar a diagnosticarlo.

--help​

Muestra información de ayuda, similar a esta página.

--ignoreProjects <project1> ... <projectN>​

Ignora los tests de los proyectos especificados. Jest usa el atributo displayName en la configuración para identificar proyectos. Si usas esta opción, debes definir displayName en todos tus proyectos.

--injectGlobals​

Inserta las variables globales de Jest (expect, test, describe, beforeEach, etc.) en el entorno global. Si estableces esto en false, deberás importarlas desde @jest/globals, ej:

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

jest.useFakeTimers();

test('some test', () => {
  expect(Date.now()).toBe(0);
});
nota

Esta opción solo es compatible con el corredor de pruebas predeterminado jest-circus.

--json​

Imprime los resultados de pruebas en formato JSON. Este modo envía demás salidas y mensajes de usuario a stderr.

--lastCommit​

Ejecuta todos los tests afectados por cambios en el último commit. Comportamiento similar a --onlyChanged.

--listTests​

Lista todos los archivos de prueba que Jest ejecutará con los argumentos dados, y finaliza.

--logHeapUsage​

Registra el uso de memoria heap después de cada prueba. Útil para depurar fugas de memoria. Usar junto con --runInBand y --expose-gc en Node.

--maxConcurrency=<num>​

Evita que Jest ejecute más pruebas simultáneas que la cantidad especificada. Solo afecta pruebas que usan test.concurrent.

--maxWorkers=<num>|<string>​

Alias: -w. Define el número máximo de workers que se crearán para ejecutar pruebas. En modo ejecución única, el valor predeterminado es el número de núcleos disponibles menos uno para el hilo principal. En modo watch, usa la mitad de los núcleos disponibles para no sobrecargar tu máquina. Puede ajustarse en entornos limitados como CI, pero los valores predeterminados son adecuados para la mayoría de casos.

Para entornos con CPUs variables, usa configuración porcentual: --maxWorkers=50%

--noStackTrace​

Desactiva los stack traces en los resultados de las pruebas.

--notify​

Activa notificaciones nativas del SO para resultados de pruebas. Ideal cuando quieres concentrarte exclusivamente en testing JavaScript. Requiere instalar node-notifier por separado.

--onlyChanged​

Alias: -o. Intenta identificar qué pruebas ejecutar basándose en archivos modificados en el repositorio actual. Solo funciona en repositorios git/hg y requiere gráficos de dependencia estáticos (sin requires dinámicos).

--onlyFailures​

Alias: -f. Ejecuta pruebas que fallaron en la ejecución anterior.

--openHandlesTimeout=<milliseconds>​

Cuando --detectOpenHandles y --forceExit están desactivados, Jest mostrará una advertencia si el proceso no se cierra correctamente después de este número de milisegundos. Un valor de 0 desactiva la advertencia. Por defecto es 1000.

--outputFile=<filename>​

Escribe los resultados de las pruebas en un archivo cuando también se especifica la opción --json. La estructura JSON devuelta está documentada en testResultsProcessor.

--passWithNoTests​

Permite que la suite de pruebas pase cuando no se encuentran archivos.

--projects <path1> ... <pathN>​

Ejecuta pruebas desde uno o más proyectos, ubicados en las rutas especificadas; también acepta globs de rutas. Esta opción es el equivalente en CLI de la opción de configuración projects.

nota

Si se encuentran archivos de configuración en las rutas especificadas, se ejecutarán todos los proyectos definidos en esos archivos de configuración.

--randomize​

Mezcla aleatoriamente el orden de las pruebas dentro de un archivo. La mezcla se basa en una semilla. Consulta --seed=<num> para más información.

El valor de la semilla se muestra cuando esta opción está activada. Equivale a establecer la opción CLI --showSeed.

jest --randomize --seed 1234
nota

Esta opción solo es compatible con el corredor de pruebas predeterminado jest-circus.

--reporters​

Ejecuta pruebas con los reporters especificados. Las opciones de reporter no están disponibles mediante CLI. Ejemplo con múltiples reporters:

jest --reporters="default" --reporters="jest-junit"

--resetMocks​

Restablece automáticamente el estado de los mocks antes de cada prueba. Equivalente a llamar jest.resetAllMocks() antes de cada test. Esto eliminará las implementaciones falsas de los mocks pero no restaurará su implementación original.

--restoreMocks​

Restaura automáticamente el estado y la implementación de los mocks antes de cada prueba. Equivalente a llamar a jest.restoreAllMocks() antes de cada test. Esto hará que cualquier mock elimine sus implementaciones falsas y restaure su implementación inicial.

--roots​

Una lista de rutas a directorios que Jest debe usar para buscar archivos.

--runInBand​

Alias: -i. Ejecuta todas las pruebas en serie dentro del proceso actual, en lugar de crear un grupo de procesos secundarios. Útil para depuración.

--runTestsByPath​

Ejecuta solo las pruebas especificadas con sus rutas exactas. Evita convertirlas en expresiones regulares y compararlas con cada archivo.

Por ejemplo, dada la siguiente estructura de archivos:

__tests__
└── t1.test.js # test
└── t2.test.js # test

Al ejecutar con un patrón, no se encuentra ninguna prueba:

jest --runTestsByPath __tests__/t

Salida:

No tests found

Sin embargo, al pasar una ruta exacta solo se ejecutará esa prueba:

jest --runTestsByPath __tests__/t1.test.js

Salida:

PASS __tests__/t1.test.js
consejo

La coincidencia con expresiones regulares funciona bien en ejecuciones pequeñas, pero se vuelve lenta con múltiples patrones o muchas pruebas. Esta opción optimiza el tiempo que tarda Jest en filtrar archivos de prueba específicos.

--seed=<num>​

Establece un valor de semilla que puede recuperarse en un archivo de prueba mediante jest.getSeed(). El valor de la semilla debe estar entre -0x80000000 y 0x7fffffff inclusive (-2147483648 (-(2 ** 31)) y 2147483647 (2 ** 31 - 1) en decimal).

jest --seed=1324
consejo

Si no se especifica esta opción, Jest generará el valor aleatoriamente. Puedes usar el flag --showSeed para imprimir la semilla en el resumen del informe de pruebas.

Jest usa la semilla internamente para barajar el orden en que se ejecutan los conjuntos de pruebas. Si se usa la opción --randomize, la semilla también se utiliza para barajar el orden de las pruebas dentro de cada bloque describe. Al tratar con pruebas inestables (flaky), volver a ejecutar con la misma semilla puede ayudar a reproducir el fallo.

--selectProjects <project1> ... <projectN>​

Ejecuta las pruebas de los proyectos especificados. Jest utiliza el atributo displayName en la configuración para identificar cada proyecto. Si usas esta opción, debes proporcionar un displayName a todos tus proyectos.

--setupFilesAfterEnv <path1> ... <pathN>​

Lista de rutas a módulos que ejecutan código para configurar o preparar el entorno de pruebas antes de cada prueba. Ten en cuenta que los archivos importados por los scripts de configuración no serán simulados durante las pruebas.

--shard​

El shard del conjunto de pruebas a ejecutar en formato (?<shardIndex>\d+)/(?<shardCount>\d+).

shardIndex indica qué shard seleccionar, mientras que shardCount controla la cantidad de shards en los que se debe dividir el conjunto.

shardIndex y shardCount deben ser números positivos basados en 1, y shardIndex debe ser menor o igual que shardCount.

Cuando se especifica shard, el testSequencer configurado debe implementar un método shard.

Por ejemplo, para dividir el conjunto en tres shards, cada uno ejecutando un tercio de las pruebas:

jest --shard=1/3
jest --shard=2/3
jest --shard=3/3

--showConfig​

Imprime tu configuración de Jest y luego sale.

--showSeed​

Imprime el valor de la semilla en el resumen del informe de pruebas. Consulta --seed=<num> para más detalles.

También puede configurarse en la configuración. Consulta showSeed.

--silent​

Evita que las pruebas impriman mensajes a través de la consola.

--testEnvironmentOptions=<json string>​

Cadena JSON con opciones que se pasarán al testEnvironment. Las opciones relevantes dependen del entorno.

--testLocationInResults​

Agrega un campo location a los resultados de las pruebas. Útil si deseas reportar la ubicación de una prueba en un reporter.

nota

En el objeto resultante, column se cuenta desde 0 mientras que line se cuenta desde 1.

{
  "column": 4,
  "line": 5
}

--testMatch glob1 ... globN​

Los patrones glob que Jest utiliza para detectar archivos de prueba. Consulta la configuración de testMatch para más detalles.

--testNamePattern=<regex>​

Alias: -t. Ejecuta solo las pruebas cuyo nombre coincida con la expresión regular. Por ejemplo, supongamos que quieres ejecutar solo pruebas relacionadas con autorización que tengan nombres como 'GET /api/posts with auth', entonces puedes usar jest -t=auth.

consejo

La expresión regular se compara contra el nombre completo, que es una combinación del nombre de la prueba y todos sus bloques describe circundantes.

--testPathIgnorePatterns=<regex>|[array]​

Una o varias expresiones regulares que se evalúan contra todas las rutas de pruebas antes de ejecutarlas. A diferencia de --testPathPatterns, solo ejecutará aquellas pruebas cuya ruta NO coincida con las expresiones proporcionadas.

Para pasar como array, usa expresiones regulares delimitadas por espacios y entre paréntesis escapados: \(/node_modules/ /tests/e2e/\). Alternativamente, puedes omitir paréntesis combinando regex en una sola expresión como /node_modules/|/tests/e2e/. Ambos ejemplos son equivalentes.

--testPathPatterns=<regex>​

Expresión regular que se evalúa contra todas las rutas de pruebas antes de ejecutarlas. En Windows, usa / como separador de rutas o escapa \ como \\.

--testRunner=<path>​

Permite especificar un ejecutor de pruebas personalizado.

--testSequencer=<path>​

Permite especificar un secuenciador de pruebas personalizado. Consulta la configuración testSequencer para más detalles.

--testTimeout=<number>​

Tiempo límite predeterminado para pruebas en milisegundos. Valor por defecto: 5000.

--updateSnapshot​

Alias: -u. Regenera todos los snapshots que fallen durante esta ejecución. Puede usarse con un patrón de suite o con --testNamePattern.

--useStderr​

Redirige toda la salida a stderr.

--verbose​

Muestra resultados individuales de pruebas con la jerarquía del conjunto de pruebas.

--version​

Alias: -v. Muestra la versión y finaliza.

--waitForUnhandledRejections​

Da un ciclo de evento adicional para manejar rejectionHandled, uncaughtException o unhandledRejection.

Sin esta opción, Jest podría reportar falsos positivos (ej. rechazos manejados reportados como errores) o no detectar rechazos no manejados.

Esta opción puede añadir sobrecarga perceptible en suites de pruebas rápidas.

--watch​

Observa cambios en archivos y vuelve a ejecutar pruebas relacionadas. Para reejecutar TODAS las pruebas al cambiar un archivo, usa --watchAll.

consejo

Usa --no-watch (o --watch=false) para desactivar explícitamente el modo observación si fue habilitado usando --watch. En entornos CI, esto suele manejarse automáticamente.

--watchAll​

Observa cambios y reejecuta TODAS las pruebas cuando algo cambia. Para reejecutar solo pruebas dependientes de archivos modificados, usa --watch.

consejo

Usa --no-watchAll (o --watchAll=false) para desactivar explícitamente el modo watch si fue habilitado usando --watchAll. En entornos CI, esto suele manejarse automáticamente.

--watchman​

Si se debe usar watchman para el rastreo de archivos. Por defecto es true. Deshabilitar con --no-watchman.

--workerThreads​

Indica si usar worker threads para paralelización. Por defecto se usan procesos secundarios.

precaución

Esta es una característica experimental. Consulta la opción de configuración workerThreads para más detalles.