Saltar al contenido principal
Versión: 30.0

Configuración 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 →

La filosofía de Jest es funcionar perfectamente por defecto, pero a veces necesitas más poder de configuración.

Se recomienda definir la configuración en un archivo dedicado de JavaScript, TypeScript o JSON. El archivo se detectará automáticamente si se llama jest.config.js|ts|mjs|cjs|cts|json. Puedes usar la bandera --config para pasar una ruta explícita al archivo.

nota

Recuerda que el objeto de configuración resultante siempre debe ser serializable en JSON.

El archivo de configuración simplemente debe exportar un objeto:

/** @type {import('jest').Config} */
const config = {
  verbose: true,
};

module.exports = config;

O una función que devuelva un objeto:

/** @returns {Promise<import('jest').Config>} */
module.exports = async () => {
  return {
    verbose: true,
  };
};
consejo

Para leer archivos de configuración TypeScript, Jest requiere por defecto ts-node. Puedes anular este comportamiento agregando un docblock @jest-config-loader al inicio del archivo. Actualmente se admiten ts-node y esbuild-register. Asegúrate de instalar ts-node o el loader que especifiques.

jest.config.ts
/** @jest-config-loader ts-node */
// or
/** @jest-config-loader esbuild-register */

import type {Config} from 'jest';

const config: Config = {
  verbose: true,
};

export default config;

También puedes pasar opciones al loader, por ejemplo para habilitar transpileOnly.

jest.config.ts
/** @jest-config-loader ts-node */
/** @jest-config-loader-options {"transpileOnly": true} */

import type {Config} from 'jest';

const config: Config = {
  verbose: true,
};

export default config;

La configuración también puede almacenarse en un archivo JSON como objeto simple:

jest.config.json
{
  "bail": 1,
  "verbose": true
}

Alternativamente, la configuración de Jest puede definirse mediante la clave "jest" en el package.json de tu proyecto:

package.json
{
  "name": "my-project",
  "jest": {
    "verbose": true
  }
}

También se puede referenciar el archivo JSON de configuración de Jest mediante la clave "jest" en el package.json de tu proyecto:

package.json
{
  "name": "my-project",
  "jest": "./path/to/config.json"
}

Opciones​

información

Puedes obtener los valores predeterminados de Jest desde jest-config para extenderlos si es necesario:

const {defaults} = require('jest-config');

/** @type {import('jest').Config} */
const config = {
  moduleDirectories: [...defaults.moduleDirectories, 'bower_components'],
};

module.exports = config;

Referencia​

automock [booleano]​

Valor predeterminado: false

Esta opción indica a Jest que todos los módulos importados en tus pruebas deben ser simulados automáticamente. Todos los módulos usados tendrán una implementación de reemplazo, manteniendo la superficie de la API.

Ejemplo:

utils.js
export default {
  authorize: () => 'token',
  isAuthorized: secret => secret === 'wizard',
};
__tests__/automock.test.js
import utils from '../utils';

test('if utils mocked automatically', () => {
  // Public methods of `utils` are now mock functions
  expect(utils.authorize.mock).toBeTruthy();
  expect(utils.isAuthorized.mock).toBeTruthy();

  // You can provide them with your own implementation
  // or pass the expected return value
  utils.authorize.mockReturnValue('mocked_token');
  utils.isAuthorized.mockReturnValue(true);

  expect(utils.authorize()).toBe('mocked_token');
  expect(utils.isAuthorized('not_wizard')).toBeTruthy();
});
nota

Los módulos de Node se simulan automáticamente cuando tienes un mock manual (ej: __mocks__/lodash.js). Más información aquí.

Los módulos core de Node.js, como fs, no se simulan por defecto. Pueden simularse explícitamente con jest.mock('fs').

bail [número | booleano]​

Por defecto: 0

Por defecto, Jest ejecuta todas las pruebas y muestra todos los errores en la consola al finalizar. La opción bail permite detener la ejecución después de n fallos. Establecer bail como true equivale a establecerlo en 1.

cacheDirectory [cadena]​

Por defecto: "/tmp/<path>"

El directorio donde Jest debe almacenar su información de dependencias en caché.

Jest intenta escanear tu árbol de dependencias una vez (de antemano) y almacenarlo en caché para aliviar parte de la carga en el sistema de archivos que ocurre durante la ejecución de pruebas. Esta opción te permite personalizar dónde Jest guarda esos datos de caché en el disco.

clearMocks [booleano]​

Valor predeterminado: false

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.

collectCoverage [booleano]​

Valor predeterminado: false

Indica si se debe recopilar información de cobertura durante la ejecución de las pruebas. Como esto adapta todos los archivos ejecutados con declaraciones de recolección de cobertura, puede ralentizar significativamente tus pruebas.

Jest incluye dos proveedores de cobertura: babel (predeterminado) y v8. Consulta la opción coverageProvider para más detalles.

información

Los proveedores de cobertura babel y v8 usan los comentarios /* istanbul ignore next */ y /* c8 ignore next */ respectivamente para excluir líneas de los informes de cobertura. Para más información, consulta la documentación de istanbuljs y la documentación de c8.

collectCoverageFrom [array]​

Por defecto: undefined

Un array de patrones glob que indica qué archivos deben recopilar información de cobertura. Si un archivo coincide con el patrón, se recopilará su cobertura incluso si no tiene pruebas ni se usa en el conjunto de pruebas.

/** @type {import('jest').Config} */
const config = {
  collectCoverageFrom: [
    '**/*.{js,jsx}',
    '!**/node_modules/**',
    '!**/vendor/**',
  ],
};

module.exports = config;

Esto recopilará cobertura para todos los archivos dentro del rootDir del proyecto, excepto los que coincidan con **/node_modules/** o **/vendor/**.

consejo

Cada patrón glob se aplica en el orden especificado en la configuración. Por ejemplo, ["!**/__tests__/**", "**/*.js"] no excluirá __tests__ porque la negación se sobrescribe con el segundo patrón. Para que funcione, el glob negado debe ir después de **/*.js.

nota

Esta opción requiere que collectCoverage esté en true o que Jest se ejecute con --coverage.

Help:

If you are seeing coverage output such as...

=============================== Coverage summary ===============================
Statements   : Unknown% ( 0/0 )
Branches     : Unknown% ( 0/0 )
Functions    : Unknown% ( 0/0 )
Lines        : Unknown% ( 0/0 )
================================================================================
Jest: Coverage data for global was not found.

Most likely your glob patterns are not matching any files. Refer to the micromatch documentation to ensure your globs are compatible.

coverageDirectory [string]​

Por defecto: undefined

El directorio donde Jest debe guardar sus archivos de cobertura.

coveragePathIgnorePatterns [array<string>]​

Predeterminado: ["/node_modules/"]

Un array de patrones regex que se comparan con todas las rutas de archivo antes de ejecutar pruebas. Si la ruta coincide con algún patrón, se omitirá su cobertura.

Estos patrones coinciden con la ruta completa. Usa el token <rootDir> para incluir la ruta del directorio raíz de tu proyecto y evitar que se ignoren accidentalmente archivos en entornos con diferentes directorios raíz. Ejemplo: ["<rootDir>/build/", "<rootDir>/node_modules/"].

coverageProvider [string]​

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

coverageReporters [array<string | [string, options]>]​

Por defecto: ["clover", "json", "lcov", "text"]

Una lista de nombres de reportadores que Jest utiliza al generar reportes de cobertura. Se puede usar cualquier reportador de istanbul.

consejo

Configurar esta opción sobrescribe los valores predeterminados. Agrega "text" o "text-summary" para ver un resumen de cobertura en la salida de la consola.

Se pueden pasar opciones adicionales usando la forma de tupla. Por ejemplo, puedes ocultar las líneas del reporte de cobertura para todos los archivos completamente cubiertos:

/** @type {import('jest').Config} */
const config = {
  coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
};

module.exports = config;

Para más información sobre la estructura del objeto de opciones, consulta el tipo CoverageReporterWithOptions en las definiciones de tipo.

coverageThreshold [object]​

Por defecto: undefined

Se utiliza para configurar el cumplimiento de umbrales mínimos para los resultados de cobertura. Los umbrales pueden especificarse como global, como un glob, o como ruta de directorio/archivo. Si no se cumplen los umbrales, Jest fallará. Los umbrales especificados como número positivo representan el porcentaje mínimo requerido. Los especificados como número negativo representan la cantidad máxima permitida de entidades no cubiertas.

Por ejemplo, con la siguiente configuración Jest fallará si hay menos del 80% de cobertura en ramas, líneas y funciones, o si hay más de 10 sentencias no cubiertas:

/** @type {import('jest').Config} */
const config = {
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: -10,
    },
  },
};

module.exports = config;

Si se especifican globs o rutas junto con global, los datos de cobertura para las rutas coincidentes se restarán de la cobertura general y los umbrales se aplicarán independientemente. Los umbrales para globs se aplican a todos los archivos que coincidan. Si no se encuentra el archivo especificado por la ruta, se devuelve un error.

Por ejemplo, con esta configuración:

/** @type {import('jest').Config} */
const config = {
  coverageThreshold: {
    global: {
      branches: 50,
      functions: 50,
      lines: 50,
      statements: 50,
    },
    './src/components/': {
      branches: 40,
      statements: 40,
    },
    './src/reducers/**/*.js': {
      statements: 90,
    },
    './src/api/very-important-module.js': {
      branches: 100,
      functions: 100,
      lines: 100,
      statements: 100,
    },
  },
};

module.exports = config;

Jest fallará si:

  • El directorio ./src/components tiene menos del 40% de cobertura en ramas o sentencias.

  • Algún archivo que coincida con el glob ./src/reducers/**/*.js tiene menos del 90% de cobertura de sentencias.

  • El archivo ./src/api/very-important-module.js tiene menos del 100% de cobertura.

  • El resto de archivos combinados tienen menos del 50% de cobertura (global).

dependencyExtractor [string]​

Por defecto: undefined

Esta opción permite usar un extractor de dependencias personalizado. Debe ser un módulo de node que exporte un objeto con una función extract. Ejemplo:

const crypto = require('crypto');
const fs = require('fs');

module.exports = {
  extract(code, filePath, defaultExtract) {
    const deps = defaultExtract(code, filePath);
    // Scan the file and add dependencies in `deps` (which is a `Set`)
    return deps;
  },
  getCacheKey() {
    return crypto
      .createHash('md5')
      .update(fs.readFileSync(__filename))
      .digest('hex');
  },
};

La función extract debe devolver un iterable (Array, Set, etc.) con las dependencias encontradas en el código.

Ese módulo también puede contener una función getCacheKey para generar una clave de caché que determine si la lógica ha cambiado y si se deben descartar artefactos en caché que dependan de ella.

displayName [string, object]​

predeterminado: undefined

Permite mostrar una etiqueta junto a una prueba mientras se ejecuta. Esto es especialmente útil en repositorios multi-proyecto con múltiples archivos de configuración de Jest, ya que indica visualmente a qué proyecto pertenece cada prueba.

/** @type {import('jest').Config} */
const config = {
  displayName: 'CLIENT',
};

module.exports = config;

Alternativamente, se puede pasar un objeto con las propiedades name y color. Esto permite configurar personalizadamente el color de fondo del displayName. Cuando es string, displayName usa blanco por defecto. Jest usa chalk para los colores, por lo que todas las opciones válidas de colores en chalk son compatibles.

/** @type {import('jest').Config} */
const config = {
  displayName: {
    name: 'CLIENT',
    color: 'blue',
  },
};

module.exports = config;

errorOnDeprecated [boolean]​

Valor predeterminado: false

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

extensionsToTreatAsEsm [array<string>]​

Por defecto: []

Jest ejecutará archivos .mjs y .js cuyo package.json más cercano tenga el campo type configurado como module como Módulos ECMAScript. Si tienes otros archivos que deben ejecutarse con ESM nativo, debes especificar su extensión aquí.

/** @type {import('jest').Config} */
const config = {
  extensionsToTreatAsEsm: ['.ts'],
};

module.exports = config;
precaución

El soporte de ESM en Jest aún es experimental; consulta su documentación para más detalles.

fakeTimers [objeto]​

Valor predeterminado: {}

Los temporizadores simulados pueden ser útiles cuando un fragmento de código establece un tiempo de espera largo que no queremos esperar en una prueba. Para detalles adicionales, consulta la guía de temporizadores simulados y la documentación de la API.

Esta opción proporciona la configuración predeterminada de temporizadores simulados para todas las pruebas. Llamar a jest.useFakeTimers() en un archivo de prueba usará estas opciones o las sobrescribirá si se pasa un objeto de configuración. Por ejemplo, puedes indicar a Jest que mantenga la implementación original de process.nextTick() y ajustar el límite de temporizadores recursivos que se ejecutarán:

/** @type {import('jest').Config} */
const config = {
  fakeTimers: {
    doNotFake: ['nextTick'],
    timerLimit: 1000,
  },
};

module.exports = config;
fakeTime.test.js
// install fake timers for this file using the options from Jest configuration
jest.useFakeTimers();

test('increase the limit of recursive timers for this and following tests', () => {
  jest.useFakeTimers({timerLimit: 5000});
  // ...
});
consejo

En lugar de incluir jest.useFakeTimers() en cada archivo de prueba, puedes habilitar temporizadores simulados globalmente en tu configuración de Jest:

/** @type {import('jest').Config} */
const config = {
  fakeTimers: {
    enableGlobally: true,
  },
};

module.exports = config;

Opciones de configuración:

type FakeableAPI =
  | 'Date'
  | 'hrtime'
  | 'nextTick'
  | 'performance'
  | 'queueMicrotask'
  | 'requestAnimationFrame'
  | 'cancelAnimationFrame'
  | 'requestIdleCallback'
  | 'cancelIdleCallback'
  | 'setImmediate'
  | 'clearImmediate'
  | 'setInterval'
  | 'clearInterval'
  | 'setTimeout'
  | 'clearTimeout';

type ModernFakeTimersConfig = {
  /**
   * If set to `true` all timers will be advanced automatically by 20 milliseconds
   * every 20 milliseconds. A custom time delta may be provided by passing a number.
   * The default is `false`.
   */
  advanceTimers?: boolean | number;
  /**
   * List of names of APIs that should not be faked. The default is `[]`, meaning
   * all APIs are faked.
   */
  doNotFake?: Array<FakeableAPI>;
  /** Whether fake timers should be enabled for all test files. The default is `false`. */
  enableGlobally?: boolean;
  /**
   * Use the old fake timers implementation instead of one backed by `@sinonjs/fake-timers`.
   * The default is `false`.
   */
  legacyFakeTimers?: boolean;
  /** Sets current system time to be used by fake timers, in milliseconds. The default is `Date.now()`. */
  now?: number;
  /** Maximum number of recursive timers that will be run. The default is `100_000` timers. */
  timerLimit?: number;
};
Temporizadores simulados heredados

Si por algún motivo necesitas usar la implementación heredada de temporizadores simulados, así se habilita globalmente (no se admiten opciones adicionales):

/** @type {import('jest').Config} */
const config = {
  fakeTimers: {
    enableGlobally: true,
    legacyFakeTimers: true,
  },
};

module.exports = config;

forceCoverageMatch [array<string>]​

Valor predeterminado: ['']

Normalmente, los archivos de prueba se ignoran al recopilar la cobertura de código. Con esta opción, puedes sobrescribir este comportamiento e incluir archivos que normalmente se ignorarían.

Por ejemplo, si tienes pruebas en archivos fuente con extensión .t.js como:

sum.t.js
export function sum(a, b) {
  return a + b;
}

if (process.env.NODE_ENV === 'test') {
  test('sum', () => {
    expect(sum(1, 2)).toBe(3);
  });
}

Puedes recopilar cobertura de esos archivos configurando forceCoverageMatch.

/** @type {import('jest').Config} */
const config = {
  forceCoverageMatch: ['**/*.t.js'],
};

module.exports = config;

globals [objeto]​

Valor predeterminado: {}

Conjunto de variables globales que deben estar disponibles en todos los entornos de prueba.

Por ejemplo, lo siguiente crearía una variable global __DEV__ establecida como true en todos los entornos:

/** @type {import('jest').Config} */
const config = {
  globals: {
    __DEV__: true,
  },
};

module.exports = config;
nota

Si especificas aquí un valor de referencia global (como un objeto o array) y algún código modifica ese valor durante una prueba, esa modificación no persistirá entre ejecuciones para otros archivos de prueba. Además, el objeto globals debe ser serializable en JSON, por lo que no puede usarse para especificar funciones globales. Para eso, usa setupFiles.

globalSetup [string]​

Por defecto: undefined

Esta opción permite utilizar un módulo personalizado de configuración global, que debe exportar una función (puede ser síncrona o asíncrona). La función se ejecutará una vez antes de todos los conjuntos de pruebas y recibirá dos argumentos: la globalConfig de Jest y la projectConfig.

información

Un módulo de configuración global configurado en un proyecto (usando el ejecutor multiproyecto) se activará solo cuando ejecutes al menos una prueba de ese proyecto.

Las variables globales definidas mediante globalSetup solo pueden leerse en globalTeardown. No puedes acceder a las variables globales definidas aquí en tus conjuntos de pruebas.

Aunque se aplica transformación de código al archivo de configuración vinculado, Jest no transformará ningún código en node_modules. Esto se debe a la necesidad de cargar los transformadores reales (ej. babel o typescript) para realizar la transformación.

setup.js
module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPatterns);
  console.log(projectConfig.cache);

  // Set reference to mongod in order to close the server during teardown.
  globalThis.__MONGOD__ = mongod;
};
teardown.js
module.exports = async function (globalConfig, projectConfig) {
  console.log(globalConfig.testPathPatterns);
  console.log(projectConfig.cache);

  await globalThis.__MONGOD__.stop();
};

globalTeardown [string]​

Por defecto: undefined

Esta opción permite utilizar un módulo personalizado de desmontaje global que debe exportar una función (puede ser síncrona o asíncrona). La función se ejecutará una vez después de todos los conjuntos de pruebas y recibirá dos argumentos: la globalConfig de Jest y la projectConfig.

información

Un módulo de desmontaje global configurado en un proyecto (usando el ejecutor multiproyecto) se activará solo cuando ejecutes al menos una prueba de ese proyecto.

La misma advertencia sobre la transformación de node_modules que aplica a globalSetup también se aplica a globalTeardown.

haste [object]​

Por defecto: undefined

Esto se utilizará para configurar el comportamiento de jest-haste-map, el sistema interno de rastreo/caché de archivos de Jest. Se admiten las siguientes opciones:

type HasteConfig = {
  /** Whether to hash files using SHA-1. */
  computeSha1?: boolean;
  /** The platform to use as the default, e.g. 'ios'. */
  defaultPlatform?: string | null;
  /** Force use of Node's `fs` APIs rather than shelling out to `find` */
  forceNodeFilesystemAPI?: boolean;
  /**
   * Whether to follow symlinks when crawling for files.
   *   This options cannot be used in projects which use watchman.
   *   Projects with `watchman` set to true will error if this option is set to true.
   */
  enableSymlinks?: boolean;
  /** Path to a custom implementation of Haste. */
  hasteImplModulePath?: string;
  /** All platforms to target, e.g ['ios', 'android']. */
  platforms?: Array<string>;
  /** Whether to throw an error on module collision. */
  throwOnModuleCollision?: boolean;
  /** Custom HasteMap module */
  hasteMapModulePath?: string;
  /** Whether to retain all files, allowing e.g. search for tests in `node_modules`. */
  retainAllFiles?: boolean;
};

injectGlobals [boolean]​

Por defecto: true

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.

maxConcurrency [number]​

Valor predeterminado: 5

Número que limita la cantidad de pruebas que pueden ejecutarse simultáneamente al usar test.concurrent. Cualquier prueba por encima de este límite se pondrá en cola y se ejecutará cuando haya disponibilidad.

maxWorkers [number | string]​

Especifica el número máximo de trabajadores que el grupo de trabajadores generará para ejecutar pruebas. En modo de ejecución única, el valor predeterminado es la cantidad de núcleos disponibles en tu máquina menos uno para el hilo principal. En modo de observación, el valor predeterminado es la mitad de los núcleos disponibles para garantizar que Jest sea discreto y no sature tu máquina. Puede ser útil ajustar esto en entornos con recursos limitados como CI, pero los valores predeterminados son adecuados para la mayoría de los casos.

Para entornos con CPUs disponibles variables, puedes usar una configuración basada en porcentajes:

/** @type {import('jest').Config} */
const config = {
  maxWorkers: '50%',
};

module.exports = config;

moduleDirectories [array<string>]​

Valor predeterminado: ["node_modules"]

Un array de nombres de directorios que se buscarán recursivamente desde la ubicación del módulo requirente. Establecer esta opción anulará el valor predeterminado. Si deseas seguir buscando paquetes en node_modules, inclúyelo junto con cualquier otra opción:

/** @type {import('jest').Config} */
const config = {
  moduleDirectories: ['node_modules', 'bower_components'],
};

module.exports = config;
precaución

Se desaconseja usar '.' como uno de los moduleDirectories, ya que esto impide que paquetes con ámbito como @emotion/react accedan a paquetes con el mismo nombre de subdirectorio (react). Consulta este issue para más detalles. En la mayoría de casos, es preferible usar la configuración moduleNameMapper en su lugar.

moduleFileExtensions [array<string>]​

Valor predeterminado: ["js", "mjs", "cjs", "jsx", "ts", "mts", "cts", "tsx", "json", "node"]

Un array de extensiones de archivo que utilizan tus módulos. Si importas módulos sin especificar la extensión, Jest buscará estas extensiones en orden de izquierda a derecha.

Recomendamos colocar las extensiones más usadas en tu proyecto a la izquierda. Por ejemplo, si usas TypeScript, considera mover "ts" y/o "tsx" al principio del array.

moduleNameMapper [object<string, string | array<string>>]​

Valor predeterminado: null

Un mapeo de expresiones regulares a nombres de módulo o arrays de nombres, que permite sustituir recursos como imágenes o estilos con un único módulo.

Los módulos mapeados a un alias no se simulan por defecto, independientemente de si automocking está activado o no.

Usa el token <rootDir> para referirte al valor de rootDir si necesitas utilizar rutas de archivo.

Adicionalmente, puedes sustituir grupos capturados en regex usando referencias inversas numeradas.

/** @type {import('jest').Config} */
const config = {
  moduleNameMapper: {
    '^image![a-zA-Z0-9$_-]+$': 'GlobalImageStub',
    '^[./a-zA-Z0-9$_-]+\\.png$': '<rootDir>/RelativeImageStub.js',
    'module_name_(.*)': '<rootDir>/substituted_module_$1.js',
    'assets/(.*)': [
      '<rootDir>/images/$1',
      '<rootDir>/photos/$1',
      '<rootDir>/recipes/$1',
    ],
  },
};

module.exports = config;

El orden de los mapeos es importante. Los patrones se verifican uno por uno hasta que coincida uno. La regla más específica debe listarse primero. Esto también aplica para arrays de nombres de módulo.

información

Si proporcionas nombres de módulo sin límites ^$, puede causar errores difíciles de detectar. Ej: relay reemplazará todos los módulos que contengan relay como subcadena: relay, react-relay y graphql-relay apuntarán a tu stub.

modulePathIgnorePatterns [array<string>]​

Por defecto: []

Un array de patrones regex que se comparan con todas las rutas de módulo antes de considerarlas "visibles" para el cargador de módulos. Si la ruta de un módulo coincide con algún patrón, no será accesible via require() en el entorno de pruebas.

Estos patrones coinciden con la ruta completa. Usa el token <rootDir> para incluir la ruta al directorio raíz de tu proyecto y evitar ignorar accidentalmente archivos en entornos con diferentes rutas raíz.

/** @type {import('jest').Config} */
const config = {
  modulePathIgnorePatterns: ['<rootDir>/build/'],
};

module.exports = config;

modulePaths [array<string>]​

Por defecto: []

Alternativa a configurar la variable de entorno NODE_PATH. modulePaths es un array de rutas absolutas a ubicaciones adicionales donde buscar módulos. Usa el token <rootDir> para incluir la ruta raíz de tu proyecto.

/** @type {import('jest').Config} */
const config = {
  modulePaths: ['<rootDir>/app/'],
};

module.exports = config;

notify [boolean]​

Valor predeterminado: false

Activa notificaciones nativas del sistema operativo para resultados de pruebas. Para mostrarlas, Jest requiere el paquete node-notifier, que debe instalarse adicionalmente:

npm install --save-dev node-notifier
consejo

En macOS, permite notificaciones de terminal-notifier en Preferencias del Sistema > Notificaciones.

En Windows, node-notifier crea una nueva entrada en el menú de inicio en el primer uso y no muestra la notificación. Las notificaciones se mostrarán correctamente en ejecuciones posteriores.

notifyMode [string]​

Valor predeterminado: failure-change

Especifica el modo de notificación. Requiere notify: true.

Modos​

  • always: enviar siempre una notificación.

  • failure: enviar notificación cuando fallen las pruebas.

  • success: enviar notificación cuando las pruebas pasen.

  • change: enviar notificación cuando cambie el estado.

  • success-change: enviar notificación cuando las pruebas pasen o una vez cuando fallen.

  • failure-change: enviar notificación cuando las pruebas fallen o una vez cuando pasen.

openHandlesTimeout [number]​

Valor predeterminado: 1000

Imprime una advertencia indicando posibles manejadores abiertos si Jest no se cierra correctamente después de este número de milisegundos tras completarse. Usa 0 para desactivar la advertencia.

preset [string]​

Por defecto: undefined

Preconfiguración que sirve como base para la configuración de Jest. Debe apuntar a un módulo npm que contenga un archivo jest-preset.json, jest-preset.js, jest-preset.cjs o jest-preset.mjs en su raíz.

Por ejemplo, este preset foo-bar/jest-preset.js se configurará de la siguiente manera:

/** @type {import('jest').Config} */
const config = {
  preset: 'foo-bar',
};

module.exports = config;

Las preconfiguraciones también pueden ser rutas relativas del sistema de archivos:

/** @type {import('jest').Config} */
const config = {
  preset: './node_modules/foo-bar/jest-preset.js',
};

module.exports = config;
información

Si también has especificado rootDir, la resolución de este archivo será relativa a ese directorio raíz.

prettierPath [string]​

Valor predeterminado: 'prettier'

Define la ruta al módulo prettier usado para actualizar instantáneas en línea.

projects [array<string | ProjectConfig>]​

Por defecto: undefined

Cuando se proporciona la configuración projects con un array de rutas o patrones glob, Jest ejecutará pruebas en todos los proyectos especificados simultáneamente. Ideal para monorepos o cuando se trabaja en múltiples proyectos.

/** @type {import('jest').Config} */
const config = {
  projects: ['<rootDir>', '<rootDir>/examples/*'],
};

module.exports = config;

Esta configuración de ejemplo ejecutará Jest en el directorio raíz y en cada carpeta dentro de /examples. Puedes tener proyectos ilimitados ejecutándose en la misma instancia de Jest.

La función de proyectos también puede ejecutar múltiples configuraciones o varios runners. Para esto, pasa un array de objetos de configuración. Por ejemplo, para ejecutar pruebas y ESLint (via jest-runner-eslint) en la misma invocación de Jest:

/** @type {import('jest').Config} */
const config = {
  projects: [
    {
      displayName: 'test',
    },
    {
      displayName: 'lint',
      runner: 'jest-runner-eslint',
      testMatch: ['<rootDir>/**/*.js'],
    },
  ],
};

module.exports = config;
consejo

Al usar multi-project runner, se recomienda agregar un displayName para cada proyecto. Esto mostrará el displayName de un proyecto junto a sus pruebas.

nota

Con la opción projects activada, Jest copiará las opciones de configuración del nivel raíz a cada configuración hija durante la ejecución, resolviendo sus valores en el contexto del hijo. Esto significa que tokens como <rootDir> apuntarán al directorio raíz del hijo aunque estén definidos en la configuración raíz.

randomize [boolean]​

Valor predeterminado: false

Equivalente al flag --randomize para aleatorizar el orden de las pruebas en un archivo.

reporters [array<moduleName | [moduleName, options]>]​

Por defecto: undefined

Usa esta opción para agregar reporters a Jest. Debe ser una lista de nombres de reporters. Puedes pasar opciones adicionales usando la forma de tupla:

/** @type {import('jest').Config} */
const config = {
  reporters: [
    'default',
    ['<rootDir>/custom-reporter.js', {banana: 'yes', pineapple: 'no'}],
  ],
};

module.exports = config;

Reportero predeterminado​

Si se especifican reporteros personalizados, se anulará el reportero predeterminado de Jest. Si deseas mantenerlo, debes incluir 'default' como nombre del reportero:

/** @type {import('jest').Config} */
const config = {
  reporters: [
    'default',
    ['jest-junit', {outputDirectory: 'reports', outputName: 'report.xml'}],
  ],
};

module.exports = config;

Reportero de GitHub Actions​

Si se incluye en la lista, el reportero integrado de GitHub Actions anotará los archivos modificados con mensajes de fallos en las pruebas y (si se usa con 'silent: false') imprimirá logs con funciones de grupo de GitHub para facilitar la navegación. Ten en cuenta que 'default' no debería usarse en este caso porque 'github-actions' ya lo manejará, así que recuerda incluir también 'summary'. Si solo deseas usarlo para anotaciones, simplemente incluye el reportero sin opciones ya que el valor predeterminado de 'silent' es 'true':

/** @type {import('jest').Config} */
const config = {
  reporters: [['github-actions', {silent: false}], 'summary'],
};

module.exports = config;

Reportero de resumen​

El reportero de resumen imprime un resumen de todas las pruebas. Es parte del reportero predeterminado, por lo que se habilitará si 'default' está incluido en la lista. Por ejemplo, podrías usarlo como reportero independiente en lugar del predeterminado, o junto con el Reportero silencioso:

/** @type {import('jest').Config} */
const config = {
  reporters: ['jest-silent-reporter', 'summary'],
};

module.exports = config;

El reportero summary acepta opciones. Como está incluido en el reportero default, también puedes pasarle las opciones allí.

/** @type {import('jest').Config} */
const config = {
  reporters: [['default', {summaryThreshold: 10}]],
};

module.exports = config;

La opción summaryThreshold se comporta de la siguiente manera: si el número total de suites de pruebas supera este umbral, se imprimirá un resumen detallado de todas las pruebas fallidas después de ejecutar todas las pruebas. Por defecto es 20.

Reporteros personalizados​

consejo

¿Hambriento de reporteros? Echa un vistazo a la larga lista de reporteros increíbles de Awesome Jest.

Un módulo de reportero personalizado debe exportar una clase que tome globalConfig, reporterOptions y reporterContext como argumentos del constructor:

custom-reporter.js
class CustomReporter {
  constructor(globalConfig, reporterOptions, reporterContext) {
    this._globalConfig = globalConfig;
    this._options = reporterOptions;
    this._context = reporterContext;
  }

  onRunComplete(testContexts, results) {
    console.log('Custom reporter output:');
    console.log('global config:', this._globalConfig);
    console.log('options for this reporter from Jest config:', this._options);
    console.log('reporter context passed from test scheduler:', this._context);
  }

  // Optionally, reporters can force Jest to exit with non zero code by returning
  // an `Error` from `getLastError()` method.
  getLastError() {
    if (this._shouldFail) {
      return new Error('Custom error reported!');
    }
  }
}

module.exports = CustomReporter;
nota

Para la lista completa de hooks y tipos de argumentos, consulta la interfaz Reporter en packages/jest-reporters/src/types.ts.

resetMocks [booleano]​

Valor predeterminado: false

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.

resetModules [booleano]​

Valor predeterminado: false

Por defecto, cada archivo de prueba tiene su propio registro de módulos independiente. Habilitar resetModules va un paso más allá y restablece el registro de módulos antes de ejecutar cada prueba individual. Esto es útil para aislar módulos en cada prueba y evitar conflictos entre estados de módulos locales. Esto puede hacerse programáticamente usando jest.resetModules().

resolver [cadena]​

Por defecto: undefined

Esta opción permite usar un resolvedor personalizado. Este resolvedor debe ser un módulo que exporte ya sea:

  1. Una función que espere una cadena como primer argumento para la ruta a resolver y un objeto de opciones como segundo argumento. La función debe devolver una ruta al módulo que debe resolverse o lanzar un error si no se encuentra el módulo. o

  2. Un objeto que contenga propiedades async y/o sync. La propiedad sync debe ser una función con la forma descrita anteriormente, y la propiedad async también debe ser una función que acepte los mismos argumentos, pero devuelva una promesa que se resuelva con la ruta al módulo o se rechace con un error.

El objeto de opciones proporcionado a los resolvedores tiene la forma:

type ResolverOptions = {
  /** Directory to begin resolving from. */
  basedir: string;
  /** List of export conditions. */
  conditions?: Array<string>;
  /** Instance of default resolver. */
  defaultResolver: (path: string, options: ResolverOptions) => string;
  /** Instance of default async resolver. */
  defaultAsyncResolver: (
    path: string,
    options: ResolverOptions,
  ) => Promise<string>;
  /** List of file extensions to search in order. */
  extensions?: Array<string>;
  /** List of directory names to be looked up for modules recursively. */
  moduleDirectory?: Array<string>;
  /** List of `require.paths` to use if nothing is found in `node_modules`. */
  paths?: Array<string>;
  /** Current root directory. */
  rootDir?: string;
};
consejo

El defaultResolver pasado como opción es el resolvedor predeterminado de Jest que puede ser útil cuando escribes uno personalizado. Toma los mismos argumentos que tu resolvedor síncrono personalizado, por ejemplo (path, options), y devuelve una cadena o lanza un error.

De manera similar, el defaultAsyncResolver es el resolvedor asíncrono predeterminado que toma los mismos argumentos y devuelve una promesa que se resuelve con una cadena o se rechaza con un error.

Por ejemplo, si deseas respetar el campo "browser" de Browserify, puedes usar el siguiente resolvedor:

resolver.js
const browserResolve = require('browser-resolve');

module.exports = browserResolve.sync;

Y agregarlo a la configuración de Jest:

/** @type {import('jest').Config} */
const config = {
  resolver: '<rootDir>/resolver.js',
};

module.exports = config;

El jest-resolve de Jest depende de unrs-resolver. Podemos pasar opciones adicionales, por ejemplo modificar mainFields para la resolución. Por ejemplo, para proyectos de React Native, podrías usar esta configuración:

module.exports = (path, options) => {
  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(path, {
    ...options,
    // `unrs-resolver` option: https://github.com/unrs/unrs-resolver#main-field
    mainFields: ['react-native', 'main'],
  });
};

También puedes usar defaultResolver para implementar un "preprocesador" que nos permita cambiar cómo el resolvedor predeterminado resolverá los módulos. Por ejemplo, supongamos que un proyecto TypeScript necesita referenciar archivos .js en tiempo de ejecución pero ejecuta Jest en archivos .ts.

module.exports = (path, options) => {
  // Dynamic imports within our codebase that reference .js need to reference
  // .ts during tests.
  if (
    !options.basedir.includes('node_modules') &&
    path.endsWith('.js') &&
    (path.startsWith('../') || path.startsWith('./'))
  ) {
    path = path.replace(/\.js$/, '.ts');
  }

  // Call the defaultResolver, so we leverage its cache, error handling, etc.
  return options.defaultResolver(path, options);
};

restoreMocks [booleano]​

Valor predeterminado: false

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.

rootDir [cadena]​

Valor predeterminado: La raíz del directorio que contiene tu archivo de configuración de Jest o el package.json o el pwd si no se encuentra package.json

El directorio raíz que Jest debe escanear para buscar tests y módulos. Si colocas tu configuración de Jest dentro de tu package.json y quieres que el directorio raíz sea la raíz de tu repositorio, el valor de este parámetro de configuración será por defecto el directorio del package.json.

A menudo querrás establecer esto como 'src' o 'lib', correspondiente a dónde se almacena el código en tu repositorio.

Usar '<rootDir>' como token de cadena en cualquier otra configuración basada en rutas hará referencia a este valor. Por ejemplo, si quieres que una entrada setupFiles apunte al archivo some-setup.js en la raíz del proyecto, establece su valor como: '<rootDir>/some-setup.js'.

roots [arreglo<cadena>]​

Valor predeterminado: ["<rootDir>"]

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

Hay ocasiones en las que solo quieres que Jest busque en un único subdirectorio (como casos donde tienes un directorio src/ en tu repositorio), pero evitando que acceda al resto del repositorio.

información

Mientras que rootDir se usa principalmente como token para reutilizar en otras opciones de configuración, roots lo usa internamente Jest para localizar archivos de prueba y archivos fuente. Esto también se aplica al buscar mocks manuales para módulos de node_modules (__mocks__ deberá estar en uno de los roots).

Por defecto, roots tiene una única entrada <rootDir>, pero hay casos donde puedes querer tener múltiples raíces dentro de un proyecto, por ejemplo roots: ["<rootDir>/src/", "<rootDir>/tests/"].

runtime [cadena]​

Valor predeterminado: "jest-runtime"

Esta opción permite utilizar un runtime personalizado para ejecutar archivos de prueba. Puedes proporcionar un runtime personalizado especificando la ruta a su implementación.

El módulo runtime debe exportar una clase que extienda la clase Runtime predeterminada de Jest o implemente una interfaz compatible con la misma firma de constructor y métodos.

advertencia

Crear un runtime personalizado es un caso de uso avanzado. La mayoría de usuarios no necesitará personalizar el runtime. Considera si tu caso podría resolverse mejor con transformers, entornos de prueba o mocks de módulos personalizados.

Ejemplo:

custom-runtime.js
const {default: Runtime} = require('jest-runtime');

class CustomRuntime extends Runtime {
  //...custom logic
}

module.exports = CustomRuntime;
custom-runtime.ts
import Runtime from 'jest-runtime';

export default class CustomRuntime extends Runtime {
  //...custom logic
}

Agrega el runtime personalizado a tu configuración de Jest:

jest.config.js
module.exports = {
  runtime: './custom-runtime.js',
};

runner [cadena]​

Valor predeterminado: "jest-runner"

Esta opción te permite usar un runner personalizado en lugar del runner de pruebas predeterminado de Jest. Ejemplos de runners incluyen:

información

El valor de la propiedad runner puede omitir el prefijo jest-runner- del nombre del paquete.

Para crear un test-runner, exporta una clase que acepte globalConfig en su constructor y tenga un método runTests con la firma:

async function runTests(
  tests: Array<Test>,
  watcher: TestWatcher,
  onStart: OnTestStart,
  onResult: OnTestSuccess,
  onFailure: OnTestFailure,
  options: TestRunnerOptions,
): Promise<void>;

Si necesitas que tu test-runner se ejecute solo en serie en lugar de en paralelo, tu clase debe tener la propiedad isSerial establecida como true.

sandboxInjectedGlobals [array<string>]​

consejo

Renombrado desde extraGlobals en Jest 28.

Por defecto: undefined

Los archivos de prueba se ejecutan dentro de un vm, lo que ralentiza las llamadas a propiedades del contexto global (ej. Math). Esta opción permite especificar propiedades adicionales para definir dentro del vm y acelerar las búsquedas.

Por ejemplo, si tus pruebas llaman frecuentemente a Math, puedes incluirlo configurando sandboxInjectedGlobals.

/** @type {import('jest').Config} */
const config = {
  sandboxInjectedGlobals: ['Math'],
};

module.exports = config;
nota

Esta opción no tiene efecto si usas ESM nativo.

setupFiles [array]​

Por defecto: []

Lista de rutas a módulos que ejecutan código para configurar el entorno de pruebas. Cada archivo setup se ejecuta una vez por archivo de prueba. Como cada prueba tiene su propio entorno, estos scripts se ejecutan antes de setupFilesAfterEnv y antes del código de prueba.

consejo

Si tu script es un módulo CJS, puede exportar una función asíncrona. Jest la llamará y esperará su resultado. Si es ESM, usa top-level await para lograr lo mismo.

setupFilesAfterEnv [array]​

Por defecto: []

Lista de rutas a módulos que ejecutan código para configurar el framework de pruebas antes de cada archivo de prueba. Como setupFiles se ejecuta antes de instalar el framework, estos scripts permiten ejecutar código justo después de dicha instalación pero antes del código de prueba.

Es decir, los módulos setupFilesAfterEnv contienen código repetitivo entre archivos de prueba. Con el framework instalado, los globales de Jest, objeto jest y expect son accesibles. Por ejemplo, puedes añadir matchers de jest-extended o llamar hooks de configuración y desmontaje:

setup-jest.js
const matchers = require('jest-extended');
expect.extend(matchers);

afterEach(() => {
  jest.useRealTimers();
});
/** @type {import('jest').Config} */
const config = {
  setupFilesAfterEnv: ['<rootDir>/setup-jest.js'],
};

module.exports = config;
consejo

Si tu script es un módulo CJS, puede exportar una función asíncrona. Jest la llamará y esperará su resultado. Si es ESM, usa top-level await para lograr lo mismo.

showSeed [boolean]​

Valor predeterminado: false

Equivalente al flag --showSeed para imprimir la semilla en el resumen del reporte de pruebas.

slowTestThreshold [number]​

Valor predeterminado: 5

El número de segundos después del cual una prueba se considera lenta y se reporta como tal en los resultados.

snapshotFormat [objeto]​

Por defecto: {escapeString: false, printBasicPrototype: false}

Permite sobrescribir opciones específicas de formato de instantáneas documentadas en el readme de pretty-format, con las excepciones de compareKeys y plugins. Por ejemplo, esta configuración haría que el formateador de instantáneas no imprima un prefijo para "Object" y "Array":

/** @type {import('jest').Config} */
const config = {
  snapshotFormat: {
    printBasicPrototype: false,
  },
};

module.exports = config;
some.test.js
test('does not show prototypes for object and array inline', () => {
  const object = {
    array: [{hello: 'Danger'}],
  };
  expect(object).toMatchInlineSnapshot(`
    {
      "array": [
        {
          "hello": "Danger",
        },
      ],
    }
  `);
});

snapshotResolver [cadena]​

Por defecto: undefined

La ruta a un módulo que puede resolver la ruta prueba↔instantánea. Esta opción te permite personalizar dónde Jest almacena los archivos de instantáneas en el disco.

custom-resolver.js
module.exports = {
  // resolves from test to snapshot path
  resolveSnapshotPath: (testPath, snapshotExtension) =>
    testPath.replace('__tests__', '__snapshots__') + snapshotExtension,

  // resolves from snapshot to test path
  resolveTestPath: (snapshotFilePath, snapshotExtension) =>
    snapshotFilePath
      .replace('__snapshots__', '__tests__')
      .slice(0, -snapshotExtension.length),

  // Example test path, used for preflight consistency check of the implementation above
  testPathForConsistencyCheck: 'some/__tests__/example.test.js',
};

snapshotSerializers [array<string>]​

Por defecto: []

Una lista de rutas a módulos serializadores de instantáneas que Jest debe usar para pruebas de instantáneas.

Jest tiene serializadores predeterminados para tipos de JavaScript incorporados, elementos HTML (Jest 20.0.0+), ImmutableJS (Jest 20.0.0+) y elementos React. Consulta el tutorial de pruebas de instantáneas para más información.

custom-serializer.js
module.exports = {
  serialize(val, config, indentation, depth, refs, printer) {
    return `Pretty foo: ${printer(val.foo, config, indentation, depth, refs)}`;
  },

  test(val) {
    return val && Object.prototype.hasOwnProperty.call(val, 'foo');
  },
};

printer es una función que serializa un valor usando plugins existentes.

Añade custom-serializer a tu configuración de Jest:

/** @type {import('jest').Config} */
const config = {
  snapshotSerializers: ['path/to/custom-serializer.js'],
};

module.exports = config;

Finalmente las pruebas se verían así:

test(() => {
  const bar = {
    foo: {
      x: 1,
      y: 2,
    },
  };

  expect(bar).toMatchSnapshot();
});

Instantánea renderizada:

Pretty foo: Object {
  "x": 1,
  "y": 2,
}
consejo

Para hacer una dependencia explícita en lugar de implícita, puedes usar expect.addSnapshotSerializer para añadir un módulo en un archivo de prueba individual, en lugar de agregar su ruta a snapshotSerializers en la configuración de Jest.

Más información sobre la API de serializadores puede encontrarse aquí.

testEnvironment [cadena]​

Por defecto: "node"

El entorno de pruebas que se usará. El entorno predeterminado en Jest es Node.js. Si estás desarrollando una aplicación web, puedes usar un entorno similar a navegador mediante jsdom.

Al agregar un docblock @jest-environment al inicio del archivo, puedes especificar otro entorno para todas las pruebas en ese archivo:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Puedes crear tu propio módulo para configurar el entorno de pruebas. El módulo debe exportar una clase con métodos setup, teardown y getVmContext. También puedes pasar variables a tus conjuntos de pruebas asignándolas al objeto this.global – esto las hará disponibles como variables globales. El constructor recibe globalConfig y projectConfig como primer argumento, y testEnvironmentContext como segundo.

La clase puede exponer opcionalmente un método asíncrono handleTestEvent para vincularse a eventos emitidos por jest-circus. Normalmente, el runner de pruebas jest-circus se pausaría hasta que se cumpla una promesa devuelta por handleTestEvent, excepto para los siguientes eventos: start_describe_definition, finish_describe_definition, add_hook, add_test o error (para la lista actualizada puedes consultar el tipo SyncEvent en las definiciones de tipos). Esto se debe a razones de compatibilidad con versiones anteriores y la firma process.on('unhandledRejection', callback), aunque normalmente no debería ser un problema para la mayoría de los casos de uso.

Cualquier pragma de docblock en archivos de prueba se pasará al constructor del entorno y puede usarse para configuración por prueba. Si el pragma no tiene valor, estará presente en el objeto con su valor establecido como cadena vacía. Si el pragma no está presente, no aparecerá en el objeto.

Para usar esta clase como entorno personalizado, refiérala por su ruta completa dentro del proyecto. Por ejemplo, si su clase está almacenada en my-custom-environment.js dentro de alguna subcarpeta de su proyecto, la anotación podría verse así:

/**
 * @jest-environment ./src/test/my-custom-environment
 */
información

El TestEnvironment tiene un entorno aislado (sandbox). Cada suite de pruebas activará su propia configuración/limpieza en su propio TestEnvironment.

Ejemplo:

// my-custom-environment
const NodeEnvironment = require('jest-environment-node').TestEnvironment;

class CustomEnvironment extends NodeEnvironment {
  constructor(config, context) {
    super(config, context);
    console.log(config.globalConfig);
    console.log(config.projectConfig);
    this.testPath = context.testPath;
    this.docblockPragmas = context.docblockPragmas;
  }

  async setup() {
    await super.setup();
    await someSetupTasks(this.testPath);
    this.global.someGlobalObject = createGlobalObject();

    // Will trigger if docblock contains @my-custom-pragma my-pragma-value
    if (this.docblockPragmas['my-custom-pragma'] === 'my-pragma-value') {
      // ...
    }
  }

  async teardown() {
    this.global.someGlobalObject = destroyGlobalObject();
    await someTeardownTasks();
    await super.teardown();
  }

  getVmContext() {
    return super.getVmContext();
  }

  async handleTestEvent(event, state) {
    if (event.name === 'test_start') {
      // ...
    }
  }
}

module.exports = CustomEnvironment;
// my-test-suite
/**
 * @jest-environment ./my-custom-environment
 */
let someGlobalObject;

beforeAll(() => {
  someGlobalObject = globalThis.someGlobalObject;
});

testEnvironmentOptions [Object]​

Valor predeterminado: {}

Opciones del entorno de prueba que se pasarán al testEnvironment. Las opciones relevantes dependen del entorno.

Por ejemplo, puedes sobrescribir opciones pasadas a jsdom:

/** @type {import('jest').Config} */
const config = {
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    html: '<html lang="zh-cmn-Hant"></html>',
    url: 'https://jestjs.io/',
    userAgent: 'Agent/007',
  },
};

module.exports = config;

Tanto jest-environment-jsdom como jest-environment-node permiten especificar customExportConditions, que te permiten controlar qué versiones de una biblioteca se cargan desde exports en package.json. jest-environment-jsdom usa ['browser'] por defecto. jest-environment-node usa ['node', 'node-addons'] por defecto.

/** @type {import('jest').Config} */
const config = {
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    customExportConditions: ['react-native'],
  },
};

module.exports = config;

Estas opciones también pueden pasarse mediante un docblock, similar a testEnvironment. La cadena con opciones debe ser parseable por JSON.parse:

/**
 * @jest-environment jsdom
 * @jest-environment-options {"url": "https://jestjs.io/"}
 */

test('use jsdom and set the URL in this test file', () => {
  expect(window.location.href).toBe('https://jestjs.io/');
});

testFailureExitCode [number]​

Valor predeterminado: 1

El código de salida que Jest devuelve al fallar una prueba.

información

Esto no cambia el código de salida en caso de errores de Jest (ej. configuración inválida).

testMatch [cadena | array<cadena>]​

(predeterminado: [ "**/__tests__/**/*.?([mc])[jt]s?(x)", "**/?(*.)+(spec|test).?([mc])[jt]s?(x)" ])

Los patrones glob que Jest usa para detectar archivos de prueba. Por defecto busca archivos .js, .jsx, .ts y .tsx dentro de carpetas __tests__, así como cualquier archivo con sufijo .test o .spec (ej. Component.test.js o Component.spec.js). También encontrará archivos llamados test.js o spec.js.

Consulta el paquete micromatch para detalles sobre los patrones que puedes especificar.

Ver también testRegex [string | array<string>], pero ten en cuenta que no puedes especificar ambas opciones.

consejo

Cada patrón glob se aplica en el orden especificado en la configuración. Por ejemplo ["!**/__fixtures__/**", "**/__tests__/**/*.js"] no excluirá __fixtures__ porque la negación se sobrescribe con el segundo patrón. Para que el glob negado funcione en este caso debe ir después de **/__tests__/**/*.js.

testPathIgnorePatterns [array<string>]​

Predeterminado: ["/node_modules/"]

Un array de cadenas con patrones de expresiones regulares que se comparan con todas las rutas de prueba antes de ejecutar el test. Si la ruta coincide con algún patrón, se omitirá.

Estos patrones coinciden con la ruta completa. Usa el token <rootDir> para incluir la ruta del directorio raíz de tu proyecto y evitar que se ignoren accidentalmente archivos en entornos con diferentes directorios raíz. Ejemplo: ["<rootDir>/build/", "<rootDir>/node_modules/"].

testRegex [string | array<string>]​

Predeterminado: (/__tests__/.*|(\\.|/)(test|spec))\\.[mc]?[jt]sx?$

El patrón o patrones que Jest usa para detectar archivos de prueba. Por defecto busca archivos .js, .jsx, .ts y .tsx dentro de carpetas __tests__, así como cualquier archivo con el sufijo .test o .spec (por ejemplo Component.test.js o Component.spec.js). También encontrará archivos llamados test.js o spec.js. Consulta también testMatch [cadena | array<cadena>], pero ten en cuenta que no puedes especificar ambas opciones.

Esta es una visualización de la expresión regular predeterminada:

├── __tests__
│   └── component.spec.js # test
│   └── anything # test
├── package.json # not test
├── foo.test.js # test
├── bar.spec.jsx # test
└── component.js # not test
información

testRegex intenta detectar archivos de prueba usando la ruta absoluta del archivo, por lo que si tienes una carpeta cuyo nombre coincida con el patrón, todos sus archivos se ejecutarán como pruebas.

testResultsProcessor [string]​

Por defecto: undefined

Esta opción permite usar un procesador personalizado de resultados. Debe ser un módulo de Node que exporte una función que reciba como primer argumento un objeto con la siguiente estructura y lo retorne:

{
  "success": boolean,
  "startTime": epoch,
  "numTotalTestSuites": number,
  "numPassedTestSuites": number,
  "numFailedTestSuites": number,
  "numRuntimeErrorTestSuites": number,
  "numTotalTests": number,
  "numPassedTests": number,
  "numFailedTests": number,
  "numPendingTests": number,
  "numTodoTests": number,
  "openHandles": Array<Error>,
  "testResults": [{
    "numFailingTests": number,
    "numPassingTests": number,
    "numPendingTests": number,
    "testResults": [{
      "title": string (message in it block),
      "status": "failed" | "pending" | "passed",
      "ancestorTitles": [string (message in describe blocks)],
      "failureMessages": [string],
      "numPassingAsserts": number,
      "location": {
        "column": number,
        "line": number
      },
      "duration": number | null,
      "startAt": epoch | null
    },
    ...
    ],
    "perfStats": {
      "end": epoch,
      "loadTestEnvironmentEnd": epoch,
      "loadTestEnvironmentStart": epoch,
      "runtime": number,
      "setupAfterEnvEnd": epoch,
      "setupAfterEnvStart": epoch,
      "setupFilesEnd": epoch,
      "setupFilesStart": epoch,
      "slow": boolean,
      "start": epoch
    },
    "testFilePath": absolute path to test file,
    "coverage": {}
  },
  "testExecError:" (exists if there was a top-level failure) {
    "message": string
    "stack": string
  }
  ...
  ]
}

testResultsProcessor y reporters son funcionalmente similares. Una diferencia clave es que el procesador de resultados solo se ejecuta después de finalizar todas las pruebas, mientras que un reporter puede recibir resultados tras completarse pruebas individuales o grupos de pruebas.

testRunner [cadena]​

Predeterminado: jest-circus/runner

Permite usar un runner de pruebas personalizado. El valor predeterminado es jest-circus. Puedes especificar la ruta a una implementación personalizada.

El módulo del runner debe exportar una función con la siguiente firma:

function testRunner(
  globalConfig: GlobalConfig,
  config: ProjectConfig,
  environment: Environment,
  runtime: Runtime,
  testPath: string,
): Promise<TestResult>;

Puedes encontrar un ejemplo de esta función en nuestro paquete predeterminado jasmine2 test runner.

testSequencer [cadena]​

Predeterminado: @jest/test-sequencer

Permite usar un secuenciador personalizado en lugar del predeterminado de Jest.

consejo

Tanto sort como shard pueden opcionalmente devolver una Promise.

Por ejemplo, para ordenar rutas alfabéticamente:

custom-sequencer.js
const Sequencer = require('@jest/test-sequencer').default;

class CustomSequencer extends Sequencer {
  /**
   * Select tests for shard requested via --shard=shardIndex/shardCount
   * Sharding is applied before sorting
   */
  shard(tests, {shardIndex, shardCount}) {
    const shardSize = Math.ceil(tests.length / shardCount);
    const shardStart = shardSize * (shardIndex - 1);
    const shardEnd = shardSize * shardIndex;

    return [...tests]
      .sort((a, b) => (a.path > b.path ? 1 : -1))
      .slice(shardStart, shardEnd);
  }

  /**
   * Sort test to determine order of execution
   * Sorting is applied after sharding
   */
  sort(tests) {
    // Test structure information
    // https://github.com/jestjs/jest/blob/6b8b1404a1d9254e7d5d90a8934087a9c9899dab/packages/jest-runner/src/types.ts#L17-L21
    const copyTests = [...tests];
    return copyTests.sort((testA, testB) => (testA.path > testB.path ? 1 : -1));
  }
}

module.exports = CustomSequencer;

Agrega custom-sequencer a tu configuración de Jest:

/** @type {import('jest').Config} */
const config = {
  testSequencer: 'path/to/custom-sequencer.js',
};

module.exports = config;

testTimeout [número]​

Predeterminado: 5000

Tiempo máximo de espera predeterminado para una prueba en milisegundos.

transform [objeto<string, rutaAlTransformer | [rutaAlTransformer, objeto]>]​

Predeterminado: {"\\.[jt]sx?$": "babel-jest"}

Un mapa de expresiones regulares a rutas de transformadores. Opcionalmente, se puede pasar una tupla con opciones de configuración como segundo argumento: {filePattern: ['path-to-transformer', {options}]}. Por ejemplo, así puedes configurar babel-jest para comportamiento no predeterminado: {'\\.js$': ['babel-jest', {rootMode: 'upward'}]}.

Jest ejecuta el código de tu proyecto como JavaScript, por lo que se necesita un transformador si usas alguna sintaxis no soportada nativamente por Node (como JSX, TypeScript o plantillas Vue). Por defecto, Jest utilizará el transformador babel-jest, que cargará la configuración de Babel de tu proyecto y transformará cualquier archivo que coincida con la expresión regular /\.[jt]sx?$/ (es decir, archivos .js, .jsx, .ts o .tsx). Además, babel-jest inyectará el plugin de Babel necesario para el hoisting de mocks mencionado en Mocking de módulos ES.

Consulta la sección Transformación de código para más detalles e instrucciones sobre cómo construir tu propio transformador.

consejo

Ten en cuenta que un transformador solo se ejecuta una vez por archivo a menos que este haya cambiado.

Recuerda incluir explícitamente el transformador predeterminado babel-jest si deseas usarlo junto con otros preprocesadores de código:

/** @type {import('jest').Config} */
const config = {
  transform: {
    '\\.[jt]sx?$': 'babel-jest',
    '\\.css$': 'some-css-transformer',
  },
};

module.exports = config;

transformIgnorePatterns [arreglo<string>]​

Predeterminado: ["/node_modules/", "\\.pnp\\.[^\\\/]+$"]

Un array de patrones regex que se comparan con todas las rutas de archivos fuente antes de la transformación. Si la ruta del archivo coincide con cualquier patrón, no será transformado.

Proporcionar patrones regex que se superpongan puede resultar en que archivos que esperabas transformar no se transformen. Por ejemplo:

/** @type {import('jest').Config} */
const config = {
  transformIgnorePatterns: ['/node_modules/(?!(foo|bar)/)', '/bar/'],
};

module.exports = config;

El primer patrón excluirá archivos dentro de /node_modules excepto aquellos en /node_modules/foo/ y /node_modules/bar/. El segundo patrón excluirá archivos en cualquier ruta que contenga /bar/. Combinados, los archivos en /node_modules/bar/ no se transformarán porque coinciden con el segundo patrón, aunque fueron excluidos por el primero.

A veces ocurre (especialmente en proyectos React Native o TypeScript) que módulos de terceros se publican sin transpilar. Como los archivos dentro de node_modules no se transforman por defecto, Jest no entenderá su código, causando errores de sintaxis. Para solucionarlo, puedes usar transformIgnorePatterns para permitir la transpilación de estos módulos. Encontrarás un buen ejemplo en la Guía de React Native.

Estos patrones coinciden con la ruta completa. Usa el token <rootDir> para incluir la ruta al directorio raíz de tu proyecto y evitar ignorar accidentalmente archivos en entornos con diferentes rutas raíz.

/** @type {import('jest').Config} */
const config = {
  transformIgnorePatterns: [
    '<rootDir>/bower_components/',
    '<rootDir>/node_modules/',
  ],
};

module.exports = config;
consejo

Si usas pnpm y necesitas transformar algunos paquetes dentro de node_modules, ten en cuenta que estos paquetes (ej. node_modules/package-a/) están enlazados simbólicamente a rutas bajo .pnpm (ej. node_modules/.pnpm/package-a@x.x.x/node_modules/package-a/). Por lo tanto, usar <rootDir>/node_modules/(?!(package-a|@scope/pkg-b)/) directamente no funcionará. En su lugar, puedes utilizar:

/** @type {import('jest').Config} */
const config = {
  transformIgnorePatterns: [
    '<rootDir>/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)',
    /* if config file is under '~/packages/lib-a/' */
    `${path.join(
      __dirname,
      '../..',
    )}/node_modules/.pnpm/(?!(package-a|@scope\\+pkg-b)@)`,
    /* or using relative pattern to match the second 'node_modules/' in 'node_modules/.pnpm/@scope+pkg-b@x.x.x/node_modules/@scope/pkg-b/' */
    'node_modules/(?!.pnpm|package-a|@scope/pkg-b)',
  ],
};

module.exports = config;

Es importante destacar que los nombres de carpeta de pnpm bajo .pnpm usan el formato nombre-de-paquete@versión. Por lo tanto, usar / no será reconocido, pero emplear @ sí funciona.

unmockedModulePathPatterns [arreglo<string>]​

Por defecto: []

Un array de patrones regex que coinciden con módulos que no deben ser simulados automáticamente. Si la ruta de un módulo coincide con alguno de estos patrones, el cargador de módulos no generará un mock automático.

Esto es útil para módulos "utilidad" comúnmente usados como detalles de implementación (como underscore, lodash, etc.). Es buena práctica mantener esta lista pequeña y usar jest.mock()/jest.unmock() explícitamente en pruebas individuales. La configuración explícita por prueba facilita entender el entorno de ejecución.

Puedes sobrescribir esta configuración en pruebas específicas llamando jest.mock() al inicio del archivo de prueba.

verbose [booleano]​

Valor predeterminado: false o true si solo hay un archivo de prueba

Indica si cada prueba individual debe reportarse durante la ejecución. Todos los errores seguirán mostrándose al final.

waitForUnhandledRejections [booleano]​

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.

watchPathIgnorePatterns [arreglo<string>]​

Por defecto: []

Un arreglo de patrones RegExp que se comparan con todas las rutas de archivos fuente antes de volver a ejecutar pruebas en modo watch. Si la ruta del archivo coincide con alguno de los patrones, cuando se actualice, no desencadenará una re-ejecución de pruebas.

Estos patrones coinciden con la ruta completa. Usa el token <rootDir> para incluir la ruta al directorio raíz de tu proyecto y evitar que accidentalmente ignore todos tus archivos en diferentes entornos que puedan tener directorios raíz distintos. Ejemplo: ["<rootDir>/node_modules/"].

Incluso si no se especifica nada aquí, el watcher ignorará cambios en carpetas de control de versiones (.git, .hg, .sl). Otros archivos y directorios ocultos, es decir, aquellos que comienzan con un punto (.), son monitoreados por defecto. Recuerda escapar el punto cuando los agregues a watchPathIgnorePatterns ya que es un carácter especial de RegExp.

/** @type {import('jest').Config} */
const config = {
  watchPathIgnorePatterns: ['<rootDir>/\\.tmp/', '<rootDir>/bar/'],
};

module.exports = config;

watchPlugins [arreglo<string | [string, Objeto]>]​

Por defecto: []

Esta opción te permite usar plugins personalizados para el modo watch. Lee más sobre watch plugins aquí.

Ejemplos de watch plugins incluyen:

información

Los valores en la propiedad watchPlugins pueden omitir el prefijo jest-watch- del nombre del paquete.

watchman [booleano]​

Por defecto: true

Indica si se debe usar watchman para el rastreo de archivos.

workerIdleMemoryLimit [número|string]​

Por defecto: undefined

Especifica el límite de memoria para workers antes de que sean reciclados y es principalmente una solución para este problema;

Después de que un worker ejecuta una prueba, se verifica su uso de memoria. Si excede el valor especificado, el worker se termina y reinicia. El límite puede especificarse de varias formas y cualquiera que sea el resultado, se usa Math.floor para convertirlo en un valor entero:

  • <= 1 - Se asume que el valor es un porcentaje de la memoria del sistema. Así 0.5 establece el límite de memoria del worker a la mitad de la memoria total del sistema

  • \> 1 - Se asume que es un valor fijo en bytes. Debido a la regla anterior, si quisieras un valor de 1 byte (no sé por qué) podrías usar 1.1.

  • Con unidades

    • 50% - Como arriba, un porcentaje de la memoria total del sistema
    • 100KB, 65MB, etc - Con unidades para denotar un límite de memoria fijo.
      • K / KB - Kilobytes (x1000)
      • KiB - Kibibytes (x1024)
      • M / MB - Megabytes
      • MiB - Mebibytes
      • G / GB - Gigabytes
      • GiB - Gibibytes
precaución

El límite de memoria basado en porcentaje no funciona en workers Linux de CircleCI debido a que se reporta incorrectamente la memoria del sistema.

/** @type {import('jest').Config} */
const config = {
  workerIdleMemoryLimit: 0.2,
};

module.exports = config;

// [cadena]​

Esta opción permite comentarios en package.json. Incluye el texto del comentario como valor de esta clave:

package.json
{
  "name": "my-project",
  "jest": {
    "//": "Comment goes here",
    "verbose": true
  }
}

workerThreads​

Valor predeterminado: false

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

Usar worker threads puede ayudar a mejorar el rendimiento.

precaución

Esta es una función experimental. Ten en cuenta que los worker threads usan structured clone en lugar de JSON.stringify() para serializar mensajes. Esto significa que objetos JavaScript incorporados como BigInt, Map o Set se serializarán correctamente. Sin embargo, las propiedades adicionales configuradas en Error, Map o Set no se pasarán durante la serialización. Para más detalles consulta el artículo sobre structured clone.