Vai al contenuto principale
{ "message": "Versione: Prossima", "description": "" }

Configurazione di Jest

Traduzione Beta Non Ufficiale

Questa pagina è stata tradotta da PageTurner AI (beta). Non ufficialmente approvata dal progetto. Hai trovato un errore? Segnala problema →

La filosofia di Jest è funzionare perfettamente di default, ma a volte serve più controllo sulla configurazione.

Si consiglia di definire la configurazione in un file JavaScript, TypeScript o JSON dedicato. Il file viene rilevato automaticamente se denominato jest.config.js|ts|mjs|cjs|cts|json. Puoi utilizzare il flag --config per specificare un percorso esplicito al file.

nota

Ricorda che l'oggetto di configurazione risultante deve sempre essere serializzabile in JSON.

Open Config Examples
  • Using defineConfig from jest you should follow this:
jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  // ... Specify options here.
});
  • You can retrieve Jest's defaults from jest-config to extend them if needed:
jest.config.js
const {defineConfig} = require('jest');
const {defaults} = require('jest-config');

module.exports = defineConfig({
  moduleDirectories: [...defaults.moduleDirectories, 'bower_components'],
});
  • When using a separate Jest config, you can also extend Jest's options from another config file if needed using mergeConfig from jest:
jest.config.js
const {defineConfig, mergeConfig} = require('jest');
const jestConfig = require('./jest.config');

module.exports = mergeConfig(
  jestConfig,
  defineConfig({
    // ... Specify options here.
  }),
);
  • If your Jest config needs to be defined as a function, you can define the config like this:
jest.config.js
const {defineConfig, mergeConfig} = require('jest');
const jestConfig = require('./jest.config');

module.exports = defineConfig(() =>
  mergeConfig(
    jestConfig,
    defineConfig({
      // ... Specify options here.
    }),
  ),
);
  • The configuration also can be stored in a JSON file as a plain object:
jest.config.json
{
  "bail": 1,
  "verbose": true
}
  • Alternatively Jest's configuration can be defined through the "jest" key in the package.json of your project:
package.json
{
  "name": "my-project",
  "jest": {
    "verbose": true
  }
}
  • Also Jest's configuration json file can be referenced through the "jest" key in the package.json of your project:
package.json
{
  "name": "my-project",
  "jest": "./path/to/config.json"
}
suggerimento

Per leggere i file di configurazione TypeScript, Jest richiede per impostazione predefinita ts-node. Puoi sovrascrivere questo comportamento aggiungendo un docblock @jest-config-loader all'inizio del file. Attualmente sono supportati ts-node e esbuild-register. Assicurati che ts-node o il loader specificato siano installati.

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

import {defineConfig} from 'jest';

export default defineConfig({
  verbose: true,
});

Puoi anche passare opzioni al loader, ad esempio per abilitare transpileOnly.

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

import type {defineConfig} from 'jest';

export default defineConfig({
  verbose: true,
});

Opzioni​

Riferimento​

automock [boolean]​

Predefinito: false

Questa opzione indica a Jest che tutti i moduli importati nei test dovrebbero essere automaticamente simulati. Tutti i moduli utilizzati avranno un'implementazione sostitutiva, mantenendo la superficie delle API.

Esempio:

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

I moduli Node vengono automaticamente simulati quando esiste un mock manuale (es. __mocks__/lodash.js). Maggiori informazioni qui.

I moduli core di Node.js, come fs, non vengono simulati di default. Possono essere simulati esplicitamente con jest.mock('fs').

bail [number | boolean]​

Default: 0

Di default, Jest esegue tutti i test e mostra gli errori nella console al termine. L'opzione bail può essere usata per interrompere l'esecuzione dopo n fallimenti. Impostare bail a true equivale a impostarlo a 1.

cacheDirectory [string]​

Default: "/tmp/<path>"

La directory in cui Jest dovrebbe memorizzare le informazioni cache delle dipendenze.

Jest tenta di analizzare l'albero delle dipendenze una sola volta (in anticipo) e di memorizzarlo in cache per ridurre parte dell'overhead legato al filesystem durante l'esecuzione dei test. Questa opzione di configurazione consente di personalizzare la posizione su disco dove Jest memorizza tali dati della cache.

clearMocks [boolean]​

Predefinito: false

Cancella automaticamente chiamate, istanze, contesti e risultati dei mock prima di ogni test. Equivalente a chiamare jest.clearAllMocks() prima di ogni test. Questo non rimuove alcuna implementazione mock che potrebbe essere stata fornita.

collectCoverage [boolean]​

Predefinito: false

Indica se le informazioni sulla copertura del codice (coverage) debbano essere raccolte durante l'esecuzione dei test. Poiché questa operazione modifica retroattivamente tutti i file eseguiti con istruzioni di raccolta coverage, può rallentare significativamente i test.

Jest include due fornitori di coverage: babel (predefinito) e v8. Consulta l'opzione coverageProvider per maggiori dettagli.

info

I fornitori di coverage babel e v8 utilizzano rispettivamente i commenti /* istanbul ignore next */ e /* c8 ignore next */ per escludere righe dai report di coverage. Per maggiori informazioni, consulta la documentazione di istanbuljs e di c8.

collectCoverageFrom [array]​

Predefinito: undefined

Un array di pattern glob che indica un insieme di file per i quali raccogliere informazioni di coverage. Se un file corrisponde al pattern glob specificato, le informazioni di coverage verranno raccolte anche se non esistono test per questo file e non viene mai richiesto nella suite di test.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  collectCoverageFrom: [
    '**/*.{js,jsx}',
    '!**/node_modules/**',
    '!**/vendor/**',
  ],
});

Verranno raccolte informazioni di coverage per tutti i file all'interno della rootDir del progetto, eccetto quelli corrispondenti a **/node_modules/** o **/vendor/**.

suggerimento

Ogni pattern glob viene applicato nell'ordine in cui è specificato nella configurazione. Ad esempio ["!**/__tests__/**", "**/*.js"] non escluderà __tests__ perché la negazione viene sovrascritta dal secondo pattern. Per far funzionare il glob negato in questo esempio, deve essere posizionato dopo **/*.js.

nota

Questa opzione richiede che collectCoverage sia impostato su true o che Jest venga invocato 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]​

Predefinito: undefined

La directory dove Jest dovrebbe scrivere i file di copertura.

coveragePathIgnorePatterns [array<string>]​

Default: ["/node_modules/"]

Un array di stringhe con pattern regex confrontati con tutti i percorsi dei file prima dell'esecuzione del test. Se il percorso corrisponde a uno qualsiasi dei pattern, le informazioni di coverage verranno ignorate.

Questi pattern regex vengono confrontati con il percorso completo. Usa il token <rootDir> per includere il percorso della directory radice del tuo progetto ed evitare di ignorare accidentalmente file in ambienti diversi che potrebbero avere directory radice differenti. Esempio: ["<rootDir>/build/", "<rootDir>/node_modules/"].

coverageProvider [string]​

Indica quale provider dovrebbe essere utilizzato per strumentare il codice per la copertura. Valori consentiti: babel (predefinito) o v8.

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

Valore predefinito: ["clover", "json", "lcov", "text"]

Un elenco di nomi di reporter che Jest utilizza per generare i rapporti di copertura. Può essere usato qualsiasi reporter di istanbul.

suggerimento

Impostare questa opzione sovrascrive i valori predefiniti. Aggiungi "text" o "text-summary" per visualizzare un riepilogo della copertura nell'output della console.

Opzioni aggiuntive possono essere passate usando la forma a tupla. Ad esempio, puoi nascondere le righe del rapporto di copertura per tutti i file completamente coperti:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  coverageReporters: ['clover', 'json', 'lcov', ['text', {skipFull: true}]],
});

Per maggiori informazioni sulla struttura dell'oggetto opzioni, fare riferimento al tipo CoverageReporterWithOptions nelle definizioni dei tipi.

coverageThreshold [oggetto]​

Predefinito: undefined

Utilizzato per configurare l'applicazione di valori minimi soglia per i risultati della copertura. Le soglie possono essere specificate come global, come glob, o come percorso di directory/file. Se le soglie non vengono raggiunte, Jest fallirà. Soglie specificate come numero positivo rappresentano la percentuale minima richiesta. Soglie specificate come numero negativo rappresentano il numero massimo di entità non coperte consentite.

Ad esempio, con la seguente configurazione Jest fallirà se ci sarà meno dell'80% di copertura per branch, linee e funzioni, o più di 10 statement non coperti:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: -10,
    },
  },
});

Se vengono specificati glob o percorsi insieme a global, i dati di copertura per i percorsi corrispondenti verranno sottratti dalla copertura complessiva e le soglie verranno applicate indipendentemente. Le soglie per i glob si applicano a tutti i file corrispondenti al glob. Se il file specificato dal percorso non viene trovato, viene restituito un errore.

Ad esempio, con la seguente configurazione:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  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,
    },
  },
});

Jest fallirà se:

  • La directory ./src/components ha meno del 40% di copertura branch o statement.

  • Uno dei file corrispondenti al glob ./src/reducers/**/*.js ha meno del 90% di copertura statement.

  • Il file ./src/api/very-important-module.js ha meno del 100% di copertura.

  • Ogni file rimanente combinato ha meno del 50% di copertura (global).

dependencyExtractor [stringa]​

Predefinito: undefined

Questa opzione consente l'uso di un estrattore di dipendenze personalizzato. Deve essere un modulo node che esporta un oggetto con una funzione extract. Esempio:

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 funzione extract deve restituire un iterabile (Array, Set, ecc.) con le dipendenze trovate nel codice.

Il modulo può contenere anche una funzione getCacheKey per generare una chiave di cache che determini se la logica è cambiata e se eventuali artefatti memorizzati dovrebbero essere scartati.

displayName [stringa, oggetto]​

predefinito: undefined

Consente di stampare un'etichetta accanto a un test durante la sua esecuzione. Particolarmente utile in repository multi-progetto con molti file di configurazione Jest, poiché identifica visivamente a quale progetto appartiene un test.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  displayName: 'CLIENT',
});

In alternativa, può essere passato un oggetto con le proprietà name e color per configurare personalmente il colore di sfondo del displayName. Quando il valore è una stringa, displayName è bianco per impostazione predefinita. Jest utilizza chalk per i colori, quindi supporta tutte le opzioni di colore valide di chalk.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  displayName: {
    name: 'CLIENT',
    color: 'blue',
  },
});

errorOnDeprecated [booleano]​

Predefinito: false

Fa sì che le chiamate ad API deprecate generino messaggi di errore utili. Utile per semplificare il processo di aggiornamento.

extensionsToTreatAsEsm [array<stringa>]​

Predefinito: []

Jest eseguirà i file .mjs e .js che hanno il campo type impostato su module nel package.json più vicino come Moduli ECMAScript. Se possiedi altri file che dovrebbero essere eseguiti come ESM nativo, devi specificare la loro estensione qui.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  extensionsToTreatAsEsm: ['.ts'],
});
{ "message": "attenzione", "description": "The default label used for the Caution admonition (:::caution)" }

Il supporto ESM di Jest è ancora sperimentale, consulta la documentazione dedicata per maggiori dettagli.

fakeTimers [object]​

Predefinito: {}

I timer falsificati sono utili quando del codice imposta un timeout lungo che non vogliamo attendere durante un test. Per dettagli aggiuntivi consulta la guida Timer Falsificati e la documentazione API.

Questa opzione fornisce la configurazione predefinita dei timer falsificati per tutti i test. Chiamare jest.useFakeTimers() in un file di test utilizzerà queste opzioni o le sovrascriverà se viene passato un oggetto di configurazione. Ad esempio, puoi dire a Jest di mantenere l'implementazione originale di process.nextTick() e modificare il limite dei timer ricorsivi che verranno eseguiti:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    doNotFake: ['nextTick'],
    timerLimit: 1000,
  },
});
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});
  // ...
});
suggerimento

Invece di includere jest.useFakeTimers() in ogni file di test, puoi abilitare i timer fittizi globalmente per tutti i test nella configurazione di Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    enableGlobally: true,
  },
});

Opzioni di configurazione:

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;
};
Timer Fittizi Legacy

Per qualche motivo potresti dover usare l'implementazione legacy dei timer fittizi. Ecco come abilitarla globalmente (le opzioni aggiuntive non sono supportate):

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  fakeTimers: {
    enableGlobally: true,
    legacyFakeTimers: true,
  },
});

forceCoverageMatch [array<string>]​

Default: ['']

I file di test sono normalmente esclusi dalla raccolta della code coverage. Con questa opzione puoi sovrascrivere questo comportamento e includere file altrimenti ignorati nella code coverage.

Ad esempio, se hai test in file sorgente nominati con estensione .t.js come segue:

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);
  });
}

Puoi raccogliere la coverage da questi file impostando forceCoverageMatch.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  forceCoverageMatch: ['**/*.t.js'],
});

globals [object]​

Predefinito: {}

Un insieme di variabili globali che devono essere disponibili in tutti gli ambienti di test.

Ad esempio, quanto segue creerebbe una variabile globale __DEV__ impostata su true in tutti gli ambienti di test:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  globals: {
    __DEV__: true,
  },
});
nota

Se specifichi un valore di riferimento globale (come un oggetto o array) qui, e del codice modifica quel valore durante l'esecuzione di un test, quella modifica non sarà persistita tra le esecuzioni dei test per altri file. Inoltre, l'oggetto globals deve essere JSON-serializzabile, quindi non può essere usato per specificare funzioni globali. Per quello, dovresti usare setupFiles.

globalSetup [string]​

Predefinito: undefined

Questa opzione consente l'utilizzo di un modulo personalizzato per la configurazione globale, che deve esportare una funzione (sincrona o asincrona). La funzione verrà attivata una volta prima di tutte le suite di test e riceverà due argomenti: la globalConfig di Jest e la projectConfig.

info

Un modulo di setup globale configurato in un progetto (utilizzando il runner multi-progetto) verrà attivato solo quando esegui almeno un test da quel progetto.

Le variabili globali definite tramite globalSetup possono essere lette solo in globalTeardown. Non è possibile accedere alle variabili globali definite qui nelle suite di test.

Mentre la trasformazione del codice viene applicata al file di setup collegato, Jest non trasformerà alcun codice in node_modules. Ciò è dovuto alla necessità di caricare i trasformatori effettivi (es. babel o typescript) per eseguire la trasformazione.

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]​

Predefinito: undefined

Questa opzione consente l'utilizzo di un modulo personalizzato per la pulizia globale che deve esportare una funzione (sincrona o asincrona). La funzione verrà attivata una volta dopo tutte le suite di test e riceverà due argomenti: la globalConfig di Jest e la projectConfig.

info

Un modulo di teardown globale configurato in un progetto (utilizzando il runner multi-progetto) verrà attivato solo quando esegui almeno un test da quel progetto.

Vale la stessa avvertenza relativa alla trasformazione di node_modules come per globalSetup applicata a globalTeardown.

haste [object]​

Predefinito: undefined

Viene utilizzato per configurare il comportamento di jest-haste-map, il sistema interno di scansione file/cache di Jest. Sono supportate le seguenti opzioni:

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]​

Predefinito: true

Inserisce le variabili globali di Jest (expect, test, describe, beforeEach etc.) nell'ambiente globale. Se imposti questo valore su false, dovrai importarle da @jest/globals, ad esempio:

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

jest.useFakeTimers();

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

Questa opzione è supportata solo utilizzando il test runner predefinito jest-circus.

maxConcurrency [number]​

Predefinito: 5

Numero che limita la quantità di test consentiti di essere eseguiti contemporaneamente quando si utilizza test.concurrent. Qualsiasi test oltre questo limite verrà accodato e eseguito quando si libera uno slot.

maxWorkers [number | string]​

Specifica il numero massimo di worker che il pool genererà per eseguire i test. In modalità singola esecuzione, il valore predefinito è il numero di core disponibili sulla tua macchina meno uno per il thread principale. In modalità watch, il valore predefinito è la metà dei core disponibili per garantire che Jest sia poco invasivo e non rallenti la macchina. Può essere utile modificarlo in ambienti con risorse limitate come i CI, ma i valori predefiniti sono adeguati per la maggior parte dei casi d'uso.

Per ambienti con CPU disponibili variabili, puoi utilizzare una configurazione basata su percentuale:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  maxWorkers: '50%',
});

moduleDirectories [array<string>]​

Predefinito: ["node_modules"]

Un array di nomi di directory da ricercare ricorsivamente a partire dalla posizione del modulo richiedente. Impostare questa opzione sovrascriverà il valore predefinito. Se desideri comunque cercare i pacchetti in node_modules, includilo insieme alle altre opzioni:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  moduleDirectories: ['node_modules', 'bower_components'],
});
{ "message": "attenzione", "description": "The default label used for the Caution admonition (:::caution)" }

Si sconsiglia di utilizzare '.' come uno dei moduleDirectories, poiché ciò impedisce a pacchetti con ambito come @emotion/react di accedere a pacchetti con lo stesso nome di sottodirectory (react). Consulta questo issue per maggiori dettagli. Nella maggior parte dei casi, è preferibile utilizzare invece la configurazione moduleNameMapper.

moduleFileExtensions [array<string>]​

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

Un array di estensioni di file utilizzate dai tuoi moduli. Se richiedi moduli senza specificare un'estensione, queste sono le estensioni che Jest cercherà, in ordine da sinistra a destra.

Raccomandiamo di posizionare a sinistra le estensioni più comunemente utilizzate nel tuo progetto. Se stai utilizzando TypeScript, potresti considerare di spostare "ts" e/o "tsx" all'inizio dell'array.

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

Predefinito: null

Una mappa da espressioni regolari a nomi di moduli o array di nomi di moduli che permette di sostituire risorse come immagini o stili con un singolo modulo.

I moduli mappati a un alias non vengono mockati per impostazione predefinita, indipendentemente dallo stato dell'automocking.

Utilizza il token stringa <rootDir> per riferirti al valore di rootDir se vuoi utilizzare percorsi di file.

Inoltre, puoi sostituire i gruppi catturati nelle regex utilizzando backreference numerati.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  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',
    ],
  },
});

L'ordine in cui vengono definite le mappature è importante. I pattern vengono controllati uno per uno finché non ne viene trovato uno corrispondente. La regola più specifica dovrebbe essere elencata per prima. Questo vale anche per gli array di nomi di moduli.

info

Se fornisci nomi di moduli senza delimitatori ^$, potresti causare errori difficili da individuare. Ad esempio, relay sostituirà tutti i moduli che contengono relay come sottostringa nel nome: relay, react-relay e graphql-relay verranno tutti puntati al tuo stub.

modulePathIgnorePatterns [array<string>]​

Predefinito: []

Un array di stringhe di pattern regex che vengono confrontate con tutti i percorsi dei moduli prima che questi siano considerati "visibili" al caricatore di moduli. Se il percorso di un modulo corrisponde a uno qualsiasi dei pattern, non sarà richiamabile con require() nell'ambiente di test.

Queste stringhe di pattern corrispondono all'intero percorso. Utilizza il token <rootDir> per includere il percorso della directory root del tuo progetto ed evitare di ignorare accidentalmente tutti i file in ambienti con diverse directory root.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  modulePathIgnorePatterns: ['<rootDir>/build/'],
});

modulePaths [array<string>]​

Predefinito: []

Un'API alternativa all'impostazione della variabile d'ambiente NODE_PATH, modulePaths è un array di percorsi assoluti verso posizioni aggiuntive da cercare durante la risoluzione dei moduli. Utilizza il token stringa <rootDir> per includere il percorso della directory root del tuo progetto.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  modulePaths: ['<rootDir>/app/'],
});

notify [boolean]​

Predefinito: false

Attiva le notifiche native del sistema operativo per i risultati dei test. Per visualizzare le notifiche, Jest necessita del pacchetto node-notifier, che deve essere installato separatamente:

npm install --save-dev node-notifier
suggerimento

Su macOS, ricorda di consentire le notifiche da terminal-notifier in Preferenze di Sistema > Notifiche e Focus.

Su Windows, node-notifier crea una nuova voce nel menu Start al primo utilizzo e non visualizza la notifica. Le notifiche verranno visualizzate correttamente nelle esecuzioni successive.

notifyMode [string]​

Predefinito: failure-change

Specifica la modalità di notifica. Richiede notify: true.

Modalità​

  • always: invia sempre una notifica.

  • failure: invia una notifica quando i test falliscono.

  • success: invia una notifica quando i test hanno successo.

  • change: invia una notifica quando lo stato cambia.

  • success-change: invia una notifica quando i test hanno successo o una volta quando falliscono.

  • failure-change: invia una notifica quando i test falliscono o una volta quando hanno successo.

openHandlesTimeout [numero]​

Valore predefinito: 1000

Stampa un avviso indicando che probabilmente ci sono handle aperti se Jest non termina correttamente dopo questo numero di millisecondi dal completamento. Usa 0 per disabilitare l'avviso.

preset [stringa]​

Predefinito: undefined

Un preset utilizzato come base per la configurazione di Jest. Un preset deve puntare a un modulo npm che contiene un file jest-preset.json, jest-preset.js, jest-preset.cjs o jest-preset.mjs nella radice.

Ad esempio, questo preset foo-bar/jest-preset.js verrà utilizzato come segue:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  preset: 'foo-bar',
});

I preset possono anche essere relativi a percorsi del filesystem:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  preset: './node_modules/foo-bar/jest-preset.js',
});
info

Se hai specificato anche rootDir, la risoluzione di questo file sarà relativa a quella directory radice.

prettierPath [stringa]​

Valore predefinito: 'prettier'

Imposta il percorso al modulo node prettier utilizzato per aggiornare gli snapshot inline.

projects [array<stringa | ProjectConfig>]​

Predefinito: undefined

Quando la configurazione projects viene fornita con un array di percorsi o pattern glob, Jest eseguirà i test in tutti i progetti specificati contemporaneamente. Ideale per monorepo o quando si lavora su più progetti simultaneamente.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  projects: ['<rootDir>', '<rootDir>/examples/*'],
});

Questa configurazione d'esempio eseguirà Jest nella directory radice e in ogni cartella della directory degli esempi. Puoi avere un numero illimitato di progetti in esecuzione nella stessa istanza di Jest.

La funzionalità projects può essere utilizzata anche per eseguire più configurazioni o più runner. A questo scopo, puoi passare un array di oggetti di configurazione. Ad esempio, per eseguire sia test che ESLint (tramite jest-runner-eslint) nella stessa invocazione di Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  projects: [
    {
      displayName: 'test',
    },
    {
      displayName: 'lint',
      runner: 'jest-runner-eslint',
      testMatch: ['<rootDir>/**/*.js'],
    },
  ],
});
suggerimento

Quando si utilizza il multi-project runner, si consiglia di aggiungere un displayName per ogni progetto. Questo mostrerà il displayName del progetto accanto ai suoi test.

nota

Con l'opzione projects abilitata, Jest copierà le opzioni di configurazione di livello root in ogni configurazione figlia durante l'esecuzione dei test, risolvendone i valori nel contesto del figlio. Ciò significa che token come <rootDir> punteranno alla directory radice del figlio anche se definiti nella configurazione root.

randomize [booleano]​

Predefinito: false

Equivalente al flag --randomize per randomizzare l'ordine dei test in un file.

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

Predefinito: undefined

Utilizza questa opzione di configurazione per aggiungere reporter a Jest. Deve essere un elenco di nomi di reporter; opzioni aggiuntive possono essere passate a un reporter utilizzando la forma di tupla:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [
    'default',
    ['<rootDir>/custom-reporter.js', {banana: 'yes', pineapple: 'no'}],
  ],
});

Reporter Predefinito​

Se vengono specificati reporter personalizzati, il reporter predefinito di Jest verrà sovrascritto. Per mantenerlo, è necessario passare 'default' come nome del reporter:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [
    'default',
    ['jest-junit', {outputDirectory: 'reports', outputName: 'report.xml'}],
  ],
});

Reporter per GitHub Actions​

Se incluso nella lista, il reporter integrato per GitHub Actions annoterà i file modificati con i messaggi di errore dei test e (se usato con 'silent: false') stamperà log con le funzionalità di gruppo di GitHub per una facile navigazione. Nota che 'default' non dovrebbe essere usato in questo caso poiché 'github-actions' lo gestirà già, quindi ricorda di includere anche 'summary'. Se desideri usarlo solo per le annotazioni, lascia semplicemente il reporter senza opzioni poiché il valore predefinito di 'silent' è 'true':

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [['github-actions', {silent: false}], 'summary'],
});

Il reporter di riepilogo stampa un sommario di tutti i test. Fa parte del reporter predefinito, quindi verrà abilitato se 'default' è incluso nella lista. Ad esempio, potresti volerlo usare come reporter autonomo invece di quello predefinito, o insieme al Silent Reporter:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: ['jest-silent-reporter', 'summary'],
});

Il reporter summary accetta opzioni. Poiché è incluso nel reporter default, puoi anche passare le opzioni lì.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  reporters: [['default', {summaryThreshold: 10}]],
});

L'opzione summaryThreshold si comporta nel seguente modo: se il numero totale di suite di test supera questa soglia, verrà stampato un riepilogo dettagliato di tutti i test falliti dopo l'esecuzione di tutti i test. Il valore predefinito è 20.

Reporter Personalizzati​

suggerimento

Vuoi scoprire altri reporter? Dai un'occhiata alla lunga lista di reporter fantastici su Awesome Jest.

Un modulo reporter personalizzato deve esportare una classe che accetta come argomenti del costruttore globalConfig, reporterOptions e reporterContext:

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

Per l'elenco completo di hook e tipi di argomenti, consulta l'interfaccia Reporter in packages/jest-reporters/src/types.ts.

resetMocks [booleano]​

Predefinito: false

Reimposta automaticamente lo stato dei mock prima di ogni test. Equivale a chiamare jest.resetAllMocks() prima di ogni test. Rimuoverà le implementazioni finte da tutti i mock ma non ripristinerà la loro implementazione iniziale.

resetModules [booleano]​

Predefinito: false

Per impostazione predefinita, ogni file di test ha un proprio registro moduli indipendente. Abilitando resetModules si va oltre e si resetta il registro moduli prima di eseguire ogni singolo test. È utile per isolare i moduli per ogni test in modo che lo stato locale dei moduli non entri in conflitto tra i test. Questo può essere fatto programmaticamente con jest.resetModules().

resolver [stringa]​

Predefinito: undefined

Questa opzione consente l'uso di un resolver personalizzato. Questo resolver deve essere un modulo che esporta una delle seguenti:

  1. una funzione che si aspetta come primo argomento una stringa per il percorso da risolvere e come secondo argomento un oggetto opzioni. La funzione dovrebbe restituire un percorso al modulo da risolvere o generare un errore se il modulo non viene trovato. oppure

  2. un oggetto contenente proprietà async e/o sync. La proprietà sync dovrebbe essere una funzione con la forma descritta sopra, e la proprietà async dovrebbe essere anch'essa una funzione che accetta gli stessi argomenti, ma restituisce una promise che si risolve con il percorso del modulo o viene rifiutata con un errore.

L'oggetto opzioni fornito ai resolver ha 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;
  /** 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;
};
suggerimento

Il defaultResolver passato come opzione è il resolver predefinito di Jest, che può essere utile quando si scrive un resolver personalizzato. Accetta gli stessi argomenti del resolver sincrono personalizzato, ad esempio (path, options), e restituisce una stringa o genera un errore.

Ad esempio, se si desidera rispettare il campo "browser" di Browserify, si può utilizzare il seguente resolver:

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

module.exports = browserResolve.sync;

E aggiungerlo alla configurazione di Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  resolver: '<rootDir>/resolver.js',
});

Il modulo jest-resolve di Jest si basa su unrs-resolver. Possiamo passare opzioni aggiuntive, ad esempio modificando mainFields per la risoluzione. Ad esempio, per progetti React Native potrebbe essere utile questa configurazione:

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'],
  });
};

Si può anche utilizzare defaultResolver per implementare un "pre-processore" che modifichi il comportamento del resolver predefinito. Ad esempio, supponiamo un progetto TypeScript che necessita di referenziare file .js a runtime ma esegue Jest sui file .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 [boolean]​

Predefinito: false

Ripristina automaticamente lo stato e l'implementazione dei mock prima di ogni test. Equivale a chiamare jest.restoreAllMocks() prima di ogni test. Ciò rimuoverà le implementazioni finte dei mock e ripristinerà la loro implementazione iniziale.

rootDir [string]​

Valore predefinito: La root della directory contenente il tuo file di configurazione Jest oppure il package.json o il pwd se non viene trovato alcun package.json

La directory root che Jest dovrebbe analizzare per cercare test e moduli. Se inserisci la configurazione Jest nel tuo package.json e desideri che la root sia la directory principale del repository, il valore predefinito sarà la directory del package.json.

Spesso conviene impostarlo a 'src' o 'lib', corrispondenti a dove è memorizzato il codice nel repository.

suggerimento

Usando '<rootDir>' come token in altre impostazioni di percorso, si farà riferimento a questo valore. Ad esempio, per puntare un file some-setup.js nella root del progetto da setupFiles, imposta il valore a: '<rootDir>/some-setup.js'.

roots [array<string>]​

Valore predefinito: ["<rootDir>"]

Un elenco di percorsi alle directory che Jest dovrebbe utilizzare per cercare file.

Ci sono casi in cui si desidera che Jest cerchi solo in una sottodirectory specifica (ad esempio una cartella src/ nel repo), impedendogli di accedere al resto del repository.

info

Mentre rootDir è principalmente usato come token riutilizzabile in altre opzioni, roots è utilizzato internamente da Jest per individuare file di test e file sorgente. Ciò si applica anche quando si cercano mock manuali per moduli da node_modules (gli __mocks__ dovranno risiedere in uno dei roots).

Per impostazione predefinita, roots ha una singola voce <rootDir>, ma esistono casi in cui potresti volere più root nello stesso progetto, ad esempio roots: ["<rootDir>/src/", "<rootDir>/tests/"].

runtime [string]​

Predefinito: "jest-runtime"

Questa opzione consente l'uso di un runtime personalizzato per eseguire i file di test. Un runtime personalizzato può essere fornito specificando un percorso a un'implementazione runtime.

Il modulo runtime deve esportare una classe che estende la classe Runtime predefinita di Jest o che implementa un'interfaccia compatibile con la stessa firma del costruttore e gli stessi metodi.

attenzione

Creare un runtime personalizzato è un caso d'uso avanzato. La maggior parte degli utenti non dovrebbe aver bisogno di personalizzare il runtime. Valuta se il tuo caso d'uso possa essere gestito meglio con transformer personalizzati, ambienti di test o mock di moduli.

Esempio:

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
}

Aggiungi il runtime personalizzato alla tua configurazione Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  runtime: './custom-runtime.js',
});

runner [string]​

Valore predefinito: "jest-runner"

Questa opzione permette di utilizzare un runner personalizzato invece di quello predefinito di Jest. Esempi di runner includono:

info

Il valore della proprietà runner può omettere il prefisso jest-runner- dal nome del pacchetto.

Per creare un test-runner, esporta una classe che accetta globalConfig nel costruttore e ha un metodo runTests con la firma:

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

Se devi limitare il tuo test-runner a eseguire solo in serie anziché in parallelo, la tua classe deve avere la proprietà isSerial impostata su true.

sandboxInjectedGlobals [array<string>]​

suggerimento

Rinominato da extraGlobals in Jest 28.

Predefinito: undefined

I file di test vengono eseguiti all'interno di una vm, che rallenta le chiamate alle proprietà del contesto globale (es. Math). Con questa opzione puoi specificare proprietà aggiuntive da definire all'interno della vm per ricerche più veloci.

Ad esempio, se i tuoi test chiamano spesso Math, puoi passarlo impostando sandboxInjectedGlobals.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  sandboxInjectedGlobals: ['Math'],
});
nota

Questa opzione non ha effetto se usi ESM nativo.

setupFiles [array]​

Predefinito: []

Un elenco di percorsi a moduli che eseguono codice per configurare o preparare l'ambiente di testing. Ogni setupFile verrà eseguito una volta per file di test. Poiché ogni test viene eseguito nel proprio ambiente, questi script verranno eseguiti nell'ambiente di test prima di eseguire setupFilesAfterEnv e prima del codice del test stesso.

suggerimento

Se il tuo script di setup è un modulo CJS, può esportare una funzione asincrona. Jest chiamerà la funzione e ne attenderà il risultato. Ciò può essere utile per recuperare dati in modo asincrono. Se il file è un modulo ESM, utilizza semplicemente top-level await per ottenere lo stesso risultato.

setupFilesAfterEnv [array]​

Predefinito: []

Un elenco di percorsi a moduli che eseguono codice per configurare o preparare il framework di testing prima dell'esecuzione di ogni file di test nella suite. Poiché setupFiles viene eseguito prima dell'installazione del framework di test nell'ambiente, questo script ti offre l'opportunità di eseguire codice immediatamente dopo l'installazione del framework di test nell'ambiente ma prima del codice del test stesso.

In altre parole, i moduli setupFilesAfterEnv sono destinati al codice che si ripete in ogni file di test. Avere il framework di test installato rende accessibili nei moduli i globali di Jest, l'oggetto jest e expect. Ad esempio, puoi aggiungere matcher aggiuntivi dalla libreria jest-extended o chiamare hook di setup e teardown:

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

afterEach(() => {
  jest.useRealTimers();
});
jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  setupFilesAfterEnv: ['<rootDir>/setup-jest.js'],
});
suggerimento

Se il tuo script di setup è un modulo CJS, può esportare una funzione asincrona. Jest chiamerà la funzione e ne attenderà il risultato. Ciò può essere utile per recuperare dati in modo asincrono. Se il file è un modulo ESM, utilizza semplicemente top-level await per ottenere lo stesso risultato.

showSeed [boolean]​

Predefinito: false

Equivalente al flag --showSeed per stampare il seed nel riepilogo del report dei test.

slowTestThreshold [number]​

Predefinito: 5

Il numero di secondi dopo i quali un test viene considerato lento e segnalato come tale nei risultati.

snapshotFormat [object]​

Valore predefinito: {escapeString: false, printBasicPrototype: false}

Consente di sovrascrivere specifiche opzioni di formattazione degli snapshot documentate nel readme di pretty-format, con l'eccezione di compareKeys e plugins. Ad esempio, questa configurazione farebbe sì che il formattatore degli snapshot non stampi il prefisso per "Object" e "Array":

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  snapshotFormat: {
    printBasicPrototype: false,
  },
});
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 [string]​

Predefinito: undefined

Il percorso di un modulo in grado di risolvere il percorso test<->snapshot. Questa opzione permette di personalizzare dove Jest memorizza i file degli snapshot su 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>]​

Predefinito: []

Un elenco di percorsi verso moduli di serializzazione degli snapshot che Jest dovrebbe utilizzare per i test snapshot.

Jest include serializzatori predefiniti per i tipi JavaScript nativi, elementi HTML (dalla versione 20.0.0+), ImmutableJS (dalla versione 20.0.0+) e per elementi React. Consulta il tutorial sugli snapshot test per maggiori informazioni.

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 è una funzione che serializza un valore utilizzando i plugin esistenti.

Aggiungi custom-serializer alla tua configurazione Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  snapshotSerializers: ['path/to/custom-serializer.js'],
});

Infine, i test avrebbero il seguente aspetto:

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

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

Alla fine i test appariranno così:

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

Per rendere esplicita una dipendenza invece che implicita, puoi chiamare expect.addSnapshotSerializer per aggiungere un modulo a un singolo file di test invece di aggiungerlo al percorso snapshotSerializers nella configurazione Jest.

Maggiori informazioni sull'API dei serializzatori sono disponibili qui.

testEnvironment [string]​

Valore predefinito: "node"

L'ambiente di test che verrà utilizzato per i test. L'ambiente predefinito in Jest è un ambiente Node.js. Se stai costruendo un'applicazione web, puoi invece utilizzare un ambiente simile a un browser tramite jsdom.

Aggiungendo un docblock @jest-environment all'inizio del file, puoi specificare un ambiente diverso da utilizzare per tutti i test in quel file:

/**
 * @jest-environment jsdom
 */

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

Puoi creare il tuo modulo che verrà utilizzato per configurare l'ambiente di test. Il modulo deve esportare una classe con i metodi setup, teardown e getVmContext. Puoi anche passare variabili da questo modulo alle suite di test assegnandole all'oggetto this.global – questo le renderà disponibili nelle suite di test come variabili globali. Al costruttore vengono passati come primo argomento globalConfig e projectConfig, e come secondo argomento testEnvironmentContext.

La classe può opzionalmente esporre un metodo asincrono handleTestEvent per collegarsi agli eventi generati da jest-circus. Normalmente, il test runner jest-circus si interrompe fino a quando una promise restituita da handleTestEvent non viene risolta, tranne per i seguenti eventi: start_describe_definition, finish_describe_definition, add_hook, add_test o error (per l'elenco aggiornato consultare il tipo SyncEvent nelle definizioni). Questo comportamento è dovuto a ragioni di retrocompatibilità e alla firma process.on('unhandledRejection', callback), ma solitamente non rappresenta un problema per la maggior parte dei casi d'uso.

Eventuali pragmi docblock nei file di test verranno passati al costruttore dell'ambiente e possono essere utilizzati per configurazioni specifiche per test. Se il pragma non ha un valore, sarà presente nell'oggetto con valore impostato come stringa vuota. Se il pragma non è presente, non sarà incluso nell'oggetto.

Per utilizzare questa classe come ambiente personalizzato, fai riferimento al suo percorso completo all'interno del progetto. Ad esempio, se la tua classe è memorizzata in my-custom-environment.js in una sottocartella del progetto, l'annotazione potrebbe apparire così:

/**
 * @jest-environment ./src/test/my-custom-environment
 */
info

TestEnvironment è isolato. Ogni suite di test attiverà setup/teardown nel proprio TestEnvironment.

Esempio:

// 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 [Oggetto]​

Predefinito: {}

Opzioni dell'ambiente di test che verranno passate a testEnvironment. Le opzioni rilevanti dipendono dall'ambiente specifico.

Ad esempio, puoi sovrascrivere le opzioni passate a jsdom:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    html: '<html lang="zh-cmn-Hant"></html>',
    url: 'https://jestjs.io/',
    userAgent: 'Agent/007',
  },
});

Sia jest-environment-jsdom che jest-environment-node consentono di specificare customExportConditions, che ti permettono di controllare quali versioni di una libreria vengono caricate dagli exports in package.json. jest-environment-jsdom usa predefinitamente ['browser']. jest-environment-node usa predefinitamente ['node', 'node-addons'].

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  testEnvironment: 'jsdom',
  testEnvironmentOptions: {
    customExportConditions: ['react-native'],
  },
});

Queste opzioni possono anche essere passate tramite docblock, in modo simile a testEnvironment. La stringa con le opzioni deve essere analizzabile da 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 [numero]​

Predefinito: 1

Il codice di uscita che Jest restituisce in caso di fallimento dei test.

info

Questo non modifica il codice di uscita in caso di errori di Jest (ad es. configurazione non valida).

testMatch [array<stringa>]​

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

I pattern glob che Jest utilizza per rilevare i file di test. Per impostazione predefinita cerca file .js, .jsx, .ts e .tsx all'interno di cartelle __tests__, oltre a qualsiasi file con suffisso .test o .spec (es. Component.test.js o Component.spec.js). Troverà anche file chiamati test.js o spec.js.

Consulta il pacchetto micromatch per dettagli sui pattern che puoi specificare.

Vedi anche testRegex [stringa | array<stringa>], ma nota che non puoi specificare entrambe le opzioni.

suggerimento

Ogni pattern glob viene applicato nell'ordine in cui sono specificati nella configurazione. Ad esempio ["!**/__fixtures__/**", "**/__tests__/**/*.js"] non escluderà __fixtures__ perché la negazione viene sovrascritta dal secondo pattern. Per far funzionare la negazione in questo esempio deve essere posizionata dopo **/__tests__/**/*.js.

testPathIgnorePatterns [array<string>]​

Default: ["/node_modules/"]

Un array di stringhe con pattern regex che vengono confrontati con tutti i percorsi dei test prima della loro esecuzione. Se il percorso corrisponde a uno qualsiasi dei pattern, il test verrà saltato.

Questi pattern regex vengono confrontati con il percorso completo. Usa il token <rootDir> per includere il percorso della directory radice del tuo progetto ed evitare di ignorare accidentalmente file in ambienti diversi che potrebbero avere directory radice differenti. Esempio: ["<rootDir>/build/", "<rootDir>/node_modules/"].

testRegex [string | array<string>]​

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

Il pattern o i pattern che Jest utilizza per rilevare i file di test. Per impostazione predefinita cerca file .js, .jsx, .ts e .tsx all'interno di cartelle __tests__, oltre a file con suffisso .test o .spec (es. Component.test.js o Component.spec.js). Rileva anche file chiamati test.js o spec.js. Vedi anche testMatch [array<string>], ma nota che non puoi specificare entrambe le opzioni.

Ecco una visualizzazione della regex predefinita:

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

testRegex tenta di rilevare i file di test utilizzando il percorso assoluto del file. Pertanto, avere una cartella con nome corrispondente farà eseguire tutti i file come test.

testResultsProcessor [string]​

Predefinito: undefined

Questa opzione consente l'uso di un processore personalizzato per i risultati. Il processore deve essere un modulo Node che esporta una funzione che riceve come primo argomento un oggetto con la seguente struttura e lo restituisce:

{
  "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 e reporters sono molto simili tra loro. Una differenza è che un processore dei risultati viene chiamato solo dopo il completamento di tutti i test, mentre un reporter può ricevere i risultati dopo il completamento di singoli test e/o suite di test.

testRunner [string]​

Default: jest-circus/runner

Questa opzione consente l'uso di un test runner personalizzato. Quello predefinito è jest-circus. Puoi specificare un test runner personalizzato indicando il percorso a un'implementazione di test runner.

Il modulo del test runner deve esportare una funzione con la seguente firma:

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

Un esempio di tale funzione è disponibile nel nostro pacchetto predefinito per il test runner jasmine2.

testSequencer [string]​

Default: @jest/test-sequencer

Questa opzione consente di utilizzare un sequenziatore personalizzato invece di quello predefinito di Jest.

suggerimento

Sia sort che shard possono opzionalmente restituire una Promise.

Ad esempio, puoi ordinare i percorsi dei test alfabeticamente:

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;

Aggiungi custom-sequencer alla tua configurazione Jest:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  testSequencer: 'path/to/custom-sequencer.js',
});

testTimeout [number]​

Default: 5000

Timeout predefinito di un test in millisecondi.

transform [object<string, pathToTransformer | [pathToTransformer, object]>]​

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

Una mappa da espressioni regolari a percorsi di trasformatori. Opzionalmente, è possibile passare una tupla con opzioni di configurazione come secondo argomento: {filePattern: ['path-to-transformer', {options}]}. Ad esempio, ecco come configurare babel-jest per un comportamento non predefinito: {'\\.js$': ['babel-jest', {rootMode: 'upward'}]}.

Jest esegue il codice del tuo progetto come JavaScript, quindi è necessario un trasformatore se utilizzi sintassi non supportate nativamente da Node (come JSX, TypeScript o template Vue). Di default, Jest utilizza il trasformatore babel-jest, che caricherà la configurazione Babel del tuo progetto e trasformerà qualsiasi file corrispondente all'espressione regolare /\.[jt]sx?$/ (ovvero qualsiasi file .js, .jsx, .ts o .tsx). Inoltre, babel-jest inietterà il plugin Babel necessario per l'hoisting dei mock descritto in Mocking dei moduli ES.

Consulta la sezione Trasformazione del codice per maggiori dettagli e istruzioni su come costruire il tuo trasformatore personalizzato.

suggerimento

Ricorda che un transformer viene eseguito solo una volta per file, a meno che il file non sia cambiato.

Se desideri utilizzare il transformer predefinito babel-jest insieme ad altri preprocessori di codice, ricordati di includerlo esplicitamente:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transform: {
    '\\.[jt]sx?$': 'babel-jest',
    '\\.css$': 'some-css-transformer',
  },
});

transformIgnorePatterns [array<string>]​

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

Un array di stringhe con pattern regex che vengono confrontati con tutti i percorsi dei file sorgente prima della trasformazione. Se il percorso del file corrisponde a qualsiasi pattern, non verrà trasformato.

Fornire pattern regex che si sovrappongono può causare il mancato trasforming di file che ti aspettavi venissero trasformati. Ad esempio:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: ['/node_modules/(?!(foo|bar)/)', '/bar/'],
});

Il primo pattern corrisponderà (e quindi non trasformerà) i file dentro /node_modules tranne quelli in /node_modules/foo/ e /node_modules/bar/. Il secondo pattern corrisponderà (e quindi non trasformerà) i file in qualsiasi percorso contenente /bar/. Con entrambi attivi, i file in /node_modules/bar/ non verranno trasformati perché corrispondono al secondo pattern, anche se erano esclusi dal primo.

Talvolta (soprattutto in progetti React Native o TypeScript) i moduli di terze parti vengono pubblicati come codice non trascompilato. Poiché tutti i file dentro node_modules non vengono trasformati per impostazione predefinita, Jest non capirà il codice in questi moduli, generando errori di sintassi. Per risolvere, puoi usare transformIgnorePatterns per consentire la trascompilazione di tali moduli. Troverai un buon esempio in questa Guida React Native.

Queste stringhe di pattern corrispondono all'intero percorso. Utilizza il token <rootDir> per includere il percorso della directory root del tuo progetto ed evitare di ignorare accidentalmente tutti i file in ambienti con diverse directory root.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  transformIgnorePatterns: [
    '<rootDir>/bower_components/',
    '<rootDir>/node_modules/',
  ],
});
suggerimento

Se utilizzi pnpm e devi trasformare alcuni pacchetti in node_modules, nota che questi pacchetti (ad es. node_modules/package-a/) sono collegati tramite symlink al percorso sotto .pnpm (ad es. node_modules/.pnpm/package-a@x.x.x/node_modules/package-a/). Quindi usare direttamente <rootDir>/node_modules/(?!(package-a|@scope/pkg-b)/) non funzionerà, mentre dovresti usare:

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  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)',
  ],
});

Nota che i nomi delle cartelle pnpm sotto .pnpm sono il nome del pacchetto più @ e il numero di versione, quindi inserire / non verrà riconosciuto, mentre usare @ può funzionare correttamente.

unmockedModulePathPatterns [array<string>]​

Predefinito: []

Un array di pattern regex confrontati con tutti i moduli prima che il caricatore restituisca automaticamente un mock. Se il percorso di un modulo corrisponde a uno di questi pattern, non verrà convertito automaticamente in mock dal caricatore.

Utile per moduli "utility" comunemente usati come dettagli implementativi (es. underscore, lodash). È buona pratica mantenere questa lista piccola e usare chiamate esplicite jest.mock()/jest.unmock() nei singoli test. La configurazione esplicita per test rende più semplice capire l'ambiente di esecuzione.

È possibile sovrascrivere questa impostazione nei singoli test chiamando esplicitamente jest.mock() all'inizio del file di test.

verbose [boolean]​

Valore predefinito: false o true se c'è un solo file di test da eseguire

Indica se ogni singolo test dovrebbe essere riportato durante l'esecuzione. Tutti gli errori verranno comunque mostrati in fondo dopo il completamento.

waitForUnhandledRejections [boolean]​

Concede un ciclo dell'event loop per gestire rejectionHandled, uncaughtException o unhandledRejection.

Senza questo flag Jest potrebbe segnalare falsi positivi (es. rejection gestita segnalata come errore) o non segnalare rejection non gestite (o attribuirle al caso di test sbagliato).

Questa opzione può aggiungere un sovraccarico significativo per suite di test veloci.

watchPathIgnorePatterns [array<string>]​

Predefinito: []

Un array di pattern RegExp confrontati con tutti i percorsi dei file sorgente prima di rieseguire i test in modalità watch. Se il percorso del file corrisponde a uno dei pattern, quando viene aggiornato non attiverà una riesecuzione dei test.

Questi pattern corrispondono al percorso completo. Usa il token stringa <rootDir> per includere il percorso della directory radice del tuo progetto ed evitare di ignorare accidentalmente tutti i file in ambienti diversi con directory radice differenti. Esempio: ["<rootDir>/node_modules/"].

Anche se non viene specificato nulla qui, il watcher ignorerà le modifiche alle cartelle di controllo versione (.git, .hg, .sl). Altri file e directory nascosti (quelli che iniziano con un punto .) sono monitorati per impostazione predefinita. Ricorda di eseguire l'escape del punto quando li aggiungi a watchPathIgnorePatterns poiché è un carattere speciale RegExp.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  watchPathIgnorePatterns: ['<rootDir>/\\.tmp/', '<rootDir>/bar/'],
});

watchPlugins [array<string | [string, Object]>]​

Predefinito: []

Questa opzione permette di utilizzare plugin watch personalizzati. Maggiori informazioni sui watch plugin qui.

Esempi di watch plugin includono:

info

I valori nella proprietà watchPlugins possono omettere il prefisso jest-watch- del nome del pacchetto.

watchman [boolean]​

Predefinito: true

Indica se utilizzare watchman per il crawling dei file.

workerIdleMemoryLimit [number|string]​

Predefinito: undefined

Specifica il limite di memoria per i worker prima che vengano riciclati, principalmente come soluzione alternativa per questo problema.

Dopo l'esecuzione di un test, viene controllato l'utilizzo della memoria del worker. Se supera il valore specificato, il worker viene terminato e riavviato. Il limite può essere specificato in diversi modi e il risultato viene convertito in valore intero con Math.floor:

  • <= 1 - Il valore è considerato una percentuale della memoria di sistema (es. 0.5 = metà della memoria totale)

  • \> 1 - Considerato un valore fisso in byte (per specificare 1 byte, usare 1.1)

  • Con unità:

    • 50% - Percentuale della memoria di sistema totale
    • 100KB, 65MB, etc. - Limite di memoria fisso con unità:
      • K / KB - Kilobyte (x1000)
      • KiB - Kibibyte (x1024)
      • M / MB - Megabyte
      • MiB - Mebibyte
      • G / GB - Gigabyte
      • GiB - Gibibyte
{ "message": "attenzione", "description": "The default label used for the Caution admonition (:::caution)" }

Il limite di memoria basato su percentuali non funziona su worker Linux CircleCI a causa di un reporting errato della memoria di sistema.

jest.config.js
const {defineConfig} = require('jest');

module.exports = defineConfig({
  workerIdleMemoryLimit: 0.2,
});

// [string]​

Questa opzione consente commenti in package.json. Includi il testo del commento come valore di questa chiave:

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

workerThreads​

Predefinito: false

Indica se utilizzare i worker thread per la parallelizzazione. Per impostazione predefinita vengono utilizzati i processi figlio.

L'utilizzo dei worker thread può aiutare a migliorare le prestazioni.

{ "message": "attenzione", "description": "The default label used for the Caution admonition (:::caution)" }

Questa è una funzionalità sperimentale. Tieni presente che i worker thread utilizzano lo structured clone invece di JSON.stringify() per serializzare i messaggi. Ciò significa che oggetti JavaScript built-in come BigInt, Map o Set verranno serializzati correttamente. Tuttavia, le proprietà aggiuntive impostate su Error, Map o Set non verranno propagate durante la serializzazione. Per maggiori dettagli consulta l'articolo sullo structured clone.