{ "message": "Versione: Prossima", "description": "" }

L'oggetto Jest

Traduzione Beta Non Ufficiale

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

L'oggetto jest è automaticamente nello scope in ogni file di test. I metodi dell'oggetto jest aiutano a creare mock e ti permettono di controllare il comportamento complessivo di Jest. Può anche essere importato esplicitamente tramite import {jest} from '@jest/globals'.

Traduzione Beta Non Ufficiale

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

info

Gli esempi TypeScript in questa pagina funzioneranno come documentato solo se importi esplicitamente le API di Jest:

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

Consulta la guida Per iniziare per i dettagli su come configurare Jest con TypeScript.

Moduli Mock

`jest.disableAutomock()`

Disabilita il mocking automatico nel caricatore dei moduli.

info

Il mocking automatico deve essere abilitato tramite l'opzione di configurazione automock affinché questo metodo abbia effetto. Consulta anche la documentazione dell'opzione di configurazione per maggiori dettagli.

JavaScript
TypeScript

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

module.exports = config;

import type {Config} from 'jest';

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

export default config;

Dopo la chiamata a disableAutomock(), tutti i require() restituiranno le versioni reali di ogni modulo (anziché una versione mock).

utils.js
export default {
  authorize: () => {
    return 'token';
  },
};

__tests__/disableAutomocking.js
import utils from '../utils';

jest.disableAutomock();

test('original implementation', () => {
  // now we have the original implementation,
  // even if we set the automocking in a jest configuration
  expect(utils.authorize()).toBe('token');
});

Questo è solitamente utile quando hai uno scenario in cui il numero di dipendenze che vuoi mockare è molto inferiore a quelle che non vuoi mockare. Ad esempio, se stai scrivendo un test per un modulo che utilizza molte dipendenze classificabili come "dettagli implementativi", probabilmente non vorrai mockarle.

Esempi di dipendenze considerabili "dettagli implementativi" includono elementi built-in del linguaggio (es. metodi Array.prototype), utility comuni (es. underscore, lodash, funzioni per array) e intere librerie come React.js.

Restituisce l'oggetto jest per il chaining.

suggerimento

Con babel-jest, le chiamate a disableAutomock() vengono automaticamente sollevate in cima al blocco di codice. Usa autoMockOff() per evitare esplicitamente questo comportamento.

`jest.enableAutomock()`

Abilita il mocking automatico nel caricatore dei moduli.

info

Per dettagli sul mocking automatico, consulta la documentazione dell'opzione automock.

Esempio:

utils.js
export default {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};

__tests__/enableAutomocking.js
jest.enableAutomock();

import utils from '../utils';

test('original implementation', () => {
  // now we have the mocked implementation,
  expect(utils.authorize._isMockFunction).toBeTruthy();
  expect(utils.isAuthorized._isMockFunction).toBeTruthy();
});

Restituisce l'oggetto jest per il chaining.

suggerimento

Con babel-jest, le chiamate a enableAutomock vengono automaticamente sollevate in cima al blocco di codice. Usa autoMockOn per evitare esplicitamente questo comportamento.

`jest.createMockFromModule(moduleName)`

Dato il nome di un modulo, utilizza il sistema di mocking automatico per generarne una versione mock.

Utile quando vuoi creare un mock manuale che estende il comportamento del mock automatico:

JavaScript
TypeScript

utils.js
module.exports = {
  authorize: () => {
    return 'token';
  },
  isAuthorized: secret => secret === 'wizard',
};

__tests__/createMockFromModule.test.js
const utils = jest.createMockFromModule('../utils');

utils.isAuthorized = jest.fn(secret => secret === 'not wizard');

test('implementation created by jest.createMockFromModule', () => {
  expect(jest.isMockFunction(utils.authorize)).toBe(true);
  expect(utils.isAuthorized('not wizard')).toBe(true);
});

utils.ts
export const utils = {
  authorize: () => {
    return 'token';
  },
  isAuthorized: (secret: string) => secret === 'wizard',
};

__tests__/createMockFromModule.test.ts
const {utils} =
  jest.createMockFromModule<typeof import('../utils')>('../utils');

utils.isAuthorized = jest.fn((secret: string) => secret === 'not wizard');

test('implementation created by jest.createMockFromModule', () => {
  expect(jest.isMockFunction(utils.authorize)).toBe(true);
  expect(utils.isAuthorized('not wizard')).toBe(true);
});

Ecco come createMockFromModule gestisce diversi tipi di dati:

`Function`

Crea una nuova funzione mock senza parametri che restituisce undefined. Funziona anche per funzioni async.

`Class`

Crea una nuova classe mantenendo l'interfaccia originale, con tutte le funzioni e proprietà membro mockate.

`Object`

Crea un nuovo oggetto clonato in profondità: le chiavi vengono mantenute mentre i valori sono mockati.

`Array`

Crea un nuovo array vuoto, ignorando l'originale.

`Primitives`

Crea una nuova proprietà con lo stesso valore primitivo della proprietà originale.

Esempio:

example.js
module.exports = {
  function: function square(a, b) {
    return a * b;
  },
  asyncFunction: async function asyncSquare(a, b) {
    const result = (await a) * b;
    return result;
  },
  class: new (class Bar {
    constructor() {
      this.array = [1, 2, 3];
    }
    foo() {}
  })(),
  object: {
    baz: 'foo',
    bar: {
      fiz: 1,
      buzz: [1, 2, 3],
    },
  },
  array: [1, 2, 3],
  number: 123,
  string: 'baz',
  boolean: true,
  symbol: Symbol.for('a.b.c'),
};

__tests__/example.test.js
const example = jest.createMockFromModule('../example');

test('should run example code', () => {
  // creates a new mocked function with no formal arguments.
  expect(example.function.name).toBe('square');
  expect(example.function).toHaveLength(0);

  // async functions get the same treatment as standard synchronous functions.
  expect(example.asyncFunction.name).toBe('asyncSquare');
  expect(example.asyncFunction).toHaveLength(0);

  // creates a new class with the same interface, member functions and properties are mocked.
  expect(example.class.constructor.name).toBe('Bar');
  expect(example.class.foo.name).toBe('foo');
  expect(example.class.array).toHaveLength(0);

  // creates a deeply cloned version of the original object.
  expect(example.object).toEqual({
    baz: 'foo',
    bar: {
      fiz: 1,
      buzz: [],
    },
  });

  // creates a new empty array, ignoring the original array.
  expect(example.array).toHaveLength(0);

  // creates a new property with the same primitive value as the original property.
  expect(example.number).toBe(123);
  expect(example.string).toBe('baz');
  expect(example.boolean).toBe(true);
  expect(example.symbol).toEqual(Symbol.for('a.b.c'));
});

`jest.mock(moduleName, factory, options)`

Simula un modulo con una versione automaticamente mockata quando viene richiesto. factory e options sono opzionali. Per esempio:

banana.js
module.exports = () => 'banana';

__tests__/test.js
jest.mock('../banana');

const banana = require('../banana'); // banana will be explicitly mocked.

banana(); // will return 'undefined' because the function is auto-mocked.

Il secondo argomento può essere usato per specificare una factory esplicita del modulo che viene eseguita al posto della funzionalità di automocking di Jest:

JavaScript
TypeScript

jest.mock('../moduleName', () => {
  return jest.fn(() => 42);
});

// This runs the function specified as second argument to `jest.mock`.
const moduleName = require('../moduleName');
moduleName(); // Will return '42';

// The optional type argument provides typings for the module factory
jest.mock<typeof import('../moduleName')>('../moduleName', () => {
  return jest.fn(() => 42);
});

// This runs the function specified as second argument to `jest.mock`.
const moduleName = require('../moduleName');
moduleName(); // Will return '42';

Quando si utilizza il parametro factory per un modulo ES6 con un default export, è necessario specificare la proprietà __esModule: true. Questa proprietà è normalmente generata da Babel/TypeScript, ma qui deve essere impostata manualmente. Quando si importa un default export, è un'istruzione per importare la proprietà chiamata default dall'oggetto di export:

import moduleName, {foo} from '../moduleName';

jest.mock('../moduleName', () => {
  return {
    __esModule: true,
    default: jest.fn(() => 42),
    foo: jest.fn(() => 43),
  };
});

moduleName(); // Will return 42
foo(); // Will return 43

Il terzo argomento può essere usato per creare mock virtuali – simulazioni di moduli che non esistono da nessuna parte nel sistema:

jest.mock(
  '../moduleName',
  () => {
    /*
     * Custom implementation of a module that doesn't exist in JS,
     * like a generated module or a native module in react-native.
     */
  },
  {virtual: true},
);

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

L'importazione di un modulo in un file di setup (come specificato da setupFilesAfterEnv) impedirà il mocking per il modulo in questione, così come tutti i moduli che importa.

I moduli mockati con jest.mock sono mockati solo per il file che chiama jest.mock. Un altro file che importa il modulo riceverà l'implementazione originale anche se viene eseguito dopo il file di test che mocka il modulo.

Restituisce l'oggetto jest per il chaining.

suggerimento

Scrivi test in TypeScript? Usa il tipo di utilità jest.Mocked o il metodo helper jest.mocked() per avere i moduli mockati tipizzati.

`jest.Mocked<Source>`

Consulta il capitolo Utilizzo in TypeScript della pagina Funzioni Mock per la documentazione.

`jest.mocked(source, options?)`

Consulta il capitolo Utilizzo in TypeScript della pagina Funzioni Mock per la documentazione.

`jest.unmock(moduleName)`

Indica che il sistema di moduli non dovrebbe mai restituire una versione mockata del modulo specificato da require() (ad esempio, dovrebbe sempre restituire il modulo reale).

L'uso più comune di questa API è specificare il modulo che un test intende testare (e quindi non vuole che venga mockato automaticamente).

Restituisce l'oggetto jest per il chaining.

`jest.deepUnmock(moduleName)`

Indica che il sistema di moduli non dovrebbe mai restituire una versione mockata del modulo specificato e delle sue dipendenze.

Restituisce l'oggetto jest per il chaining.

`jest.doMock(moduleName, factory, options)`

Quando si utilizza babel-jest, le chiamate a mock vengono automaticamente sollevate (hoisted) all'inizio del blocco di codice. Usa questo metodo se vuoi evitare esplicitamente questo comportamento.

Un esempio in cui questo è utile è quando vuoi mockare un modulo in modo diverso all'interno dello stesso file:

JavaScript
TypeScript

beforeEach(() => {
  jest.resetModules();
});

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(1);
});

test('moduleName 2', () => {
  jest.doMock('../moduleName', () => {
    return jest.fn(() => 2);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(2);
});

beforeEach(() => {
  jest.resetModules();
});

test('moduleName 1', () => {
  // The optional type argument provides typings for the module factory
  jest.doMock<typeof import('../moduleName')>('../moduleName', () => {
    return jest.fn(() => 1);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(1);
});

test('moduleName 2', () => {
  jest.doMock<typeof import('../moduleName')>('../moduleName', () => {
    return jest.fn(() => 2);
  });
  const moduleName = require('../moduleName');
  expect(moduleName()).toBe(2);
});

L'uso di jest.doMock() con gli import ES6 richiede passaggi aggiuntivi. Segui questi passaggi se non vuoi usare require nei tuoi test:

Dobbiamo specificare la proprietà __esModule: true (vedi l'API jest.mock() per maggiori informazioni).
Gli import statici dei moduli ES6 vengono sollevati (hoisted) all'inizio del file, quindi dobbiamo invece importarli dinamicamente usando import().
Infine, abbiamo bisogno di un ambiente che supporti l'importazione dinamica. Consulta Utilizzo di Babel per la configurazione iniziale. Poi aggiungi il plugin babel-plugin-dynamic-import-node, o un equivalente, alla tua configurazione Babel per abilitare l'importazione dinamica in Node.

beforeEach(() => {
  jest.resetModules();
});

test('moduleName 1', () => {
  jest.doMock('../moduleName', () => {
    return {
      __esModule: true,
      default: 'default1',
      foo: 'foo1',
    };
  });
  return import('../moduleName').then(moduleName => {
    expect(moduleName.default).toBe('default1');
    expect(moduleName.foo).toBe('foo1');
  });
});

test('moduleName 2', () => {
  jest.doMock('../moduleName', () => {
    return {
      __esModule: true,
      default: 'default2',
      foo: 'foo2',
    };
  });
  return import('../moduleName').then(moduleName => {
    expect(moduleName.default).toBe('default2');
    expect(moduleName.foo).toBe('foo2');
  });
});

Restituisce l'oggetto jest per il chaining.

`jest.dontMock(moduleName)`

Quando si utilizza babel-jest, le chiamate a unmock vengono automaticamente portate all'inizio del blocco di codice. Utilizza questo metodo se vuoi evitare esplicitamente questo comportamento.

Restituisce l'oggetto jest per il chaining.

`jest.setMock(moduleName, moduleExports)`

Fornisce esplicitamente l'oggetto mock che il sistema di moduli dovrebbe restituire per il modulo specificato.

Talvolta può capitare che il mock generato automaticamente dal sistema di moduli non sia sufficiente per le tue esigenze di testing. Normalmente in questi casi dovresti creare un mock manuale più adatto al modulo in questione. Tuttavia, in casi estremamente rari, anche un mock manuale potrebbe non essere adatto ai tuoi scopi e dovrai costruire il mock direttamente nel tuo test.

In questi rari scenari puoi utilizzare questa API per riempire manualmente lo slot nel registro dei mock-moduli del sistema.

Restituisce l'oggetto jest per il chaining.

info

Si raccomanda di utilizzare invece jest.mock(). Il secondo argomento dell'API jest.mock è una factory di moduli anziché l'oggetto modulo esportato atteso.

`jest.requireActual(moduleName)`

Restituisce il modulo effettivo invece di un mock, bypassando tutti i controlli sulla necessità di un'implementazione mock.

JavaScript
TypeScript

jest.mock('../myModule', () => {
  // Require the original module to not be mocked...
  const originalModule = jest.requireActual('../myModule');

  return {
    __esModule: true, // Use it when dealing with esModules
    ...originalModule,
    getRandom: jest.fn(() => 10),
  };
});

const getRandom = require('../myModule').getRandom;

getRandom(); // Always returns 10

jest.mock('../myModule', () => {
  // Require the original module to not be mocked...
  const originalModule =
    jest.requireActual<typeof import('../myModule')>('../myModule');

  return {
    __esModule: true, // Use it when dealing with esModules
    ...originalModule,
    getRandom: jest.fn(() => 10),
  };
});

const getRandom = require('../myModule').getRandom;

getRandom(); // Always returns 10

`jest.requireMock(moduleName)`

Restituisce un modulo mock invece di quello effettivo, bypassando tutti i controlli sulla necessità di caricamento normale.

`jest.onGenerateMock(cb)`

Registra una funzione di callback che viene invocata ogni volta che Jest genera un mock per un modulo. Questa callback ti consente di modificare il mock prima che venga restituito al resto dei test.

Parametri della callback:

modulePath: string - Il percorso assoluto del modulo da mockare.
moduleMock: T - L'oggetto mock generato da Jest per il modulo. Questo oggetto può essere modificato o sostituito prima della restituzione.

Comportamento:

Se vengono registrate più callback tramite chiamate consecutive a onGenerateMock, verranno invocate nell'ordine di registrazione.
Ogni callback riceve l'output della callback precedente come moduleMock, consentendo di applicare trasformazioni multiple allo stesso mock.

jest.onGenerateMock((modulePath, moduleMock) => {
  // Inspect the module name and decide how to transform the mock
  if (modulePath.includes('Database')) {
    // For demonstration, let's replace a method with our own custom mock
    moduleMock.connect = jest.fn().mockImplementation(() => {
      console.log('Connected to mock DB');
    });
  }

  // Return the (potentially modified) mock
  return moduleMock;
});

// Apply mock for module
jest.mock('./Database');

// Later in your tests
import Database from './Database';
// The `Database` mock now has any transformations applied by our callback

nota

La callback onGenerateMock non viene chiamata per mock creati manualmente, come:

Mock definiti in cartelle __mocks__
Factory esplicite fornite tramite jest.mock('moduleName', () => { ... })

`jest.resetModules()`

Reimposta il registro dei moduli (cache di tutti i moduli caricati). Utile per isolare moduli dove lo stato locale potrebbe causare conflitti tra test.

Esempio:

const sum1 = require('../sum');
jest.resetModules();
const sum2 = require('../sum');
sum1 === sum2;
// > false (Both sum modules are separate "instances" of the sum module.)

Esempio in un test:

beforeEach(() => {
  jest.resetModules();
});

test('works', () => {
  const sum = require('../sum');
});

test('works too', () => {
  const sum = require('../sum');
  // sum is a different copy of the sum module from the previous test.
});

Restituisce l'oggetto jest per il chaining.

`jest.isolateModules(fn)`

jest.isolateModules(fn) va oltre jest.resetModules() creando un registro sandbox per i moduli caricati nella funzione callback. Utile per isolare moduli specifici tra test ed evitare conflitti di stato.

let myModule;
jest.isolateModules(() => {
  myModule = require('myModule');
});

const otherCopyOfMyModule = require('myModule');

`jest.isolateModulesAsync(fn)`

jest.isolateModulesAsync() è l'equivalente asincrono di jest.isolateModules(). Il chiamante deve attendere (await) il completamento di isolateModulesAsync.

let myModule;
await jest.isolateModulesAsync(async () => {
  myModule = await import('myModule');
  // do async stuff here
});

const otherCopyOfMyModule = await import('myModule');

Funzioni Mock

`jest.fn(implementation?)`

Restituisce una nuova funzione mock non utilizzata. Accetta opzionalmente un'implementazione mock.

const mockFn = jest.fn();
mockFn();
expect(mockFn).toHaveBeenCalled();

// With a mock implementation:
const returnsTrue = jest.fn(() => true);
console.log(returnsTrue()); // true;

suggerimento

Consulta la pagina Funzioni Mock per i dettagli sull'utilizzo con TypeScript.

`jest.isMockFunction(fn)`

Determina se la funzione specificata è una funzione mock.

`jest.replaceProperty(object, propertyKey, value)`

Sostituisce object[propertyKey] con un value. La proprietà deve già esistere nell'oggetto. La stessa proprietà può essere sostituita più volte. Restituisce una proprietà sostituita di Jest.

nota

Per simulare proprietà definite come getter o setter, utilizza invece jest.spyOn(object, methodName, accessType). Per simulare funzioni, utilizza invece jest.spyOn(object, methodName).

suggerimento

Tutte le proprietà sostituite con jest.replaceProperty possono essere ripristinate al valore originale chiamando jest.restoreAllMocks nel metodo afterEach.

Esempio:

const utils = {
  isLocalhost() {
    return process.env.HOSTNAME === 'localhost';
  },
};

module.exports = utils;

Esempio di test:

const utils = require('./utils');

afterEach(() => {
  // restore replaced property
  jest.restoreAllMocks();
});

test('isLocalhost returns true when HOSTNAME is localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'localhost'});
  expect(utils.isLocalhost()).toBe(true);
});

test('isLocalhost returns false when HOSTNAME is not localhost', () => {
  jest.replaceProperty(process, 'env', {HOSTNAME: 'not-localhost'});
  expect(utils.isLocalhost()).toBe(false);
});

`jest.spyOn(object, methodName)`

Crea una funzione mock simile a jest.fn ma tiene anche traccia delle chiamate a object[methodName]. Restituisce una funzione mock di Jest.

nota

Per impostazione predefinita, jest.spyOn chiama anche il metodo spiato. Questo comportamento è diverso dalla maggior parte delle altre librerie di test. Se vuoi sovrascrivere la funzione originale, puoi usare jest.spyOn(object, methodName).mockImplementation(() => customImplementation) oppure object[methodName] = jest.fn(() => customImplementation).

suggerimento

Poiché jest.spyOn è un mock, puoi ripristinare lo stato iniziale chiamando jest.restoreAllMocks nel corpo della callback passata all'hook afterEach.

Esempio:

const video = {
  play() {
    return true;
  },
};

module.exports = video;

Esempio di test:

const video = require('./video');

afterEach(() => {
  // restore the spy created with spyOn
  jest.restoreAllMocks();
});

test('plays video', () => {
  const spy = jest.spyOn(video, 'play');
  const isPlaying = video.play();

  expect(spy).toHaveBeenCalled();
  expect(isPlaying).toBe(true);
});

Metodi spiati e la parola chiave `using`

Se il tuo codice è configurato per transpilare la "gestione esplicita delle risorse" (ad esempio se usi TypeScript >= 5.2 o il plugin @babel/plugin-proposal-explicit-resource-management), puoi combinare spyOn con la parola chiave using:

test('logs a warning', () => {
  using spy = jest.spyOn(console, 'warn');
  doSomeThingWarnWorthy();
  expect(spy).toHaveBeenCalled();
});

Questo codice è semanticamente equivalente a:

test('logs a warning', () => {
  let spy;
  try {
    spy = jest.spyOn(console, 'warn');
    doSomeThingWarnWorthy();
    expect(spy).toHaveBeenCalled();
  } finally {
    spy.mockRestore();
  }
});

In questo modo, il tuo spy verrà automaticamente ripristinato al valore originale quando il blocco di codice corrente termina.

Puoi andare oltre e usare un blocco di codice per limitare il mock a una sola parte del test senza compromettere la leggibilità.

test('testing something', () => {
  {
    using spy = jest.spyOn(console, 'warn');
    setupStepThatWillLogAWarning();
  }
  // here, console.warn is already restored to the original value
  // your test can now continue normally
});

nota

Se ricevi un avviso che Symbol.dispose non esiste, potresti aver bisogno di un polyfill, ad esempio con questo codice:

if (!Symbol.dispose) {
  Object.defineProperty(Symbol, 'dispose', {
    get() {
      return Symbol.for('nodejs.dispose');
    },
  });
}

`jest.spyOn(object, methodName, accessType?)`

Dalla versione Jest 22.1.0+, il metodo jest.spyOn accetta un terzo argomento opzionale accessType che può essere 'get' o 'set', utile quando vuoi spiare rispettivamente un getter o un setter.

Esempio:

const video = {
  // it's a getter!
  get play() {
    return true;
  },
};

module.exports = video;

const audio = {
  _volume: false,
  // it's a setter!
  set volume(value) {
    this._volume = value;
  },
  get volume() {
    return this._volume;
  },
};

module.exports = audio;

Esempio di test:

const audio = require('./audio');
const video = require('./video');

afterEach(() => {
  // restore the spy created with spyOn
  jest.restoreAllMocks();
});

test('plays video', () => {
  const spy = jest.spyOn(video, 'play', 'get'); // we pass 'get'
  const isPlaying = video.play;

  expect(spy).toHaveBeenCalled();
  expect(isPlaying).toBe(true);
});

test('plays audio', () => {
  const spy = jest.spyOn(audio, 'volume', 'set'); // we pass 'set'
  audio.volume = 100;

  expect(spy).toHaveBeenCalled();
  expect(audio.volume).toBe(100);
});

`jest.Replaced<Source>`

Consulta il capitolo Utilizzo con TypeScript nella pagina delle Funzioni Mock per la documentazione.

`jest.Spied<Source>`

Consulta il capitolo Utilizzo con TypeScript nella pagina delle Funzioni Mock per la documentazione.

`jest.clearAllMocks()`

Cancella le proprietà mock.calls, mock.instances, mock.contexts e mock.results di tutti i mock. Equivale a chiamare .mockClear() su ogni funzione mockata.

Restituisce l'oggetto jest per il chaining.

`jest.resetAllMocks()`

Reimposta lo stato di tutti i mock. Equivale a chiamare .mockReset() su ogni funzione mockata.

Restituisce l'oggetto jest per il chaining.

`jest.restoreAllMocks()`

Ripristina tutti i mock e le proprietà sostituite ai loro valori originali. Equivale a chiamare .mockRestore() su ogni funzione mockata e .restore() su ogni proprietà sostituita. Nota che jest.restoreAllMocks() funziona solo per i mock creati con jest.spyOn() e le proprietà sostituite con jest.replaceProperty(); altri mock richiederanno un ripristino manuale.

Timer Fittizi

`jest.useFakeTimers(fakeTimersConfig?)`

Indica a Jest di utilizzare versioni fittizie delle API globali per data, performance, tempo e timer. L'implementazione si basa su @sinonjs/fake-timers.

I timer fittizi sostituiranno Date, performance.now(), queueMicrotask(), setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() con un'implementazione che ottiene l'ora dall'orologio fittizio.

In ambiente Node anche process.hrtime, process.nextTick() e in ambiente JSDOM requestAnimationFrame(), cancelAnimationFrame(), requestIdleCallback(), cancelIdleCallback() verranno sostituiti.

Opzioni di configurazione:

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

type FakeTimersConfig = {
  /**
   * 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>;
  /**
   * 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 | Date;
  /**
   * The maximum number of recursive timers that will be run when calling `jest.runAllTimers()`.
   * The default is `100_000` timers.
   */
  timerLimit?: number;
};

Chiamare jest.useFakeTimers() attiverà i timer fittizi per tutti i test nel file, fino al ripristino dei timer originali con jest.useRealTimers().

Puoi chiamare jest.useFakeTimers() o jest.useRealTimers() da qualsiasi punto: livello superiore, dentro un blocco test, ecc. Tieni presente che è un'operazione globale e influenzerà altri test nello stesso file. Richiamare jest.useFakeTimers() nello stesso file resetta lo stato interno (es. conteggio timer) e reinstalla i timer fittizi con le opzioni fornite:

test('advance the timers automatically', () => {
  jest.useFakeTimers({advanceTimers: true});
  // ...
});

test('do not advance the timers and do not fake `performance`', () => {
  jest.useFakeTimers({doNotFake: ['performance']});
  // ...
});

test('uninstall fake timers for the rest of tests in the file', () => {
  jest.useRealTimers();
  // ...
});

Timer Fittizi Legacy

In alcuni casi potresti dover usare l'implementazione legacy dei timer fittizi. Puoi attivarla così (opzioni aggiuntive non supportate):

jest.useFakeTimers({
  legacyFakeTimers: true,
});

I timer fittizi legacy sostituiranno setImmediate(), clearImmediate(), setInterval(), clearInterval(), setTimeout(), clearTimeout() con le funzioni mock di Jest. In ambiente Node anche process.nextTick() e in JSDOM requestAnimationFrame(), cancelAnimationFrame() verranno sostituiti.

Restituisce l'oggetto jest per il chaining.

`jest.useRealTimers()`

Indica a Jest di ripristinare le implementazioni originali delle API globali per data, performance, tempo e timer. Ad esempio, puoi chiamare jest.useRealTimers() dentro l'hook afterEach per ripristinare i timer dopo ogni test:

afterEach(() => {
  jest.useRealTimers();
});

test('do something with fake timers', () => {
  jest.useFakeTimers();
  // ...
});

test('do something with real timers', () => {
  // ...
});

Restituisce l'oggetto jest per il chaining.

`jest.runAllTicks()`

Svuota la coda dei task micro (di solito gestita in Node tramite process.nextTick).

Quando viene chiamata questa API, tutte le micro-task in sospeso accodate tramite process.nextTick verranno eseguite. Inoltre, se queste micro-task ne schedulano di nuove, queste verranno esaurite continuamente finché non rimangono più micro-task nella coda.

`jest.runAllTimers()`

Esaurisce sia la coda di macro-task (cioè tutte le task accodate da setTimeout(), setInterval() e setImmediate()) sia la coda di micro-task (normalmente gestita in Node.js tramite process.nextTick).

Quando viene chiamata questa API, tutte le macro-task e micro-task in sospeso verranno eseguite. Se queste task ne schedulano di nuove, queste verranno esaurite continuamente finché non rimangono più task nella coda.

Questo è spesso utile per eseguire sincronicamente i setTimeout durante un test, permettendo di verificare in modo sincrono comportamenti che si verificherebbero solo dopo l'esecuzione dei callback di setTimeout() o setInterval(). Consulta la documentazione Timer mocks per maggiori informazioni.

`jest.runAllTimersAsync()`

Equivalente asincrono di jest.runAllTimers(). Permette a qualsiasi callback di promise schedulata di eseguirsi prima dell'esecuzione dei timer.

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

`jest.runAllImmediates()`

Esaurisce tutte le task accodate da setImmediate().

info

Questa funzione è disponibile solo con l'implementazione legacy dei fake timers.

`jest.advanceTimersByTime(msToRun)`

Esegue solo la coda delle macro-task (cioè tutte le task accodate da setTimeout(), setInterval() e setImmediate()).

Quando viene chiamata questa API, tutti i timer vengono avanzati di msToRun millisecondi. Tutte le "macro-task" in sospeso accodate tramite setTimeout() o setInterval() che verrebbero eseguite in questo intervallo temporale verranno eseguite. Inoltre, se queste macro-task ne schedulano di nuove che verrebbero eseguite nello stesso intervallo, queste verranno eseguite finché non rimangono più macro-task nella coda programmate per l'esecuzione entro msToRun millisecondi.

`jest.advanceTimersByTimeAsync(msToRun)`

Equivalente asincrono di jest.advanceTimersByTime(msToRun). Permette a qualsiasi callback di promise schedulata di eseguirsi prima dell'avanzamento dei timer.

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

`jest.runOnlyPendingTimers()`

Esegue esclusivamente le macro-task attualmente in sospeso (cioè solo le task accodate da setTimeout() o setInterval() fino a questo momento). Se le macro-task in sospeso ne schedulano di nuove, queste non verranno eseguite da questa chiamata.

È utile in scenari come un modulo sotto test che schedulasse ricorsivamente un setTimeout() il cui callback ne schedula un altro setTimeout() (creando una schedulazione infinita). In questi casi, è utile poter avanzare nel tempo un singolo passo alla volta.

`jest.runOnlyPendingTimersAsync()`

Equivalente asincrono di jest.runOnlyPendingTimers(). Permette a qualsiasi callback di promise schedulata di eseguirsi prima dell'esecuzione dei timer.

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

`jest.advanceTimersToNextTimer(steps)`

Avanza tutti i timer dei millisecondi necessari affinché venga eseguita solo la prossima timeout/interval schedulata.

Opzionalmente, puoi fornire steps per far eseguire i prossimi steps timeout/intervals.

`jest.advanceTimersToNextTimerAsync(steps)`

Equivalente asincrono di jest.advanceTimersToNextTimer(steps). Consente l'esecuzione di qualsiasi callback di promise schedulata prima di eseguire i timer.

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

`jest.advanceTimersToNextFrame()`

Avanza tutti i timer dei millisecondi necessari per eseguire le callback attualmente programmate con requestAnimationFrame. advanceTimersToNextFrame() è un modo utile per eseguire codice programmato usando requestAnimationFrame.

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

`jest.clearAllTimers()`

Rimuove qualsiasi timer in sospeso dal sistema dei timer.

Ciò significa che, se è stato programmato un timer (ma non è ancora stato eseguito), verrà cancellato e non avrà mai più l'opportunità di essere eseguito in futuro.

`jest.getTimerCount()`

Restituisce il numero di timer fittizi ancora da eseguire.

`jest.now()`

Restituisce l'ora in ms dell'orologio corrente. Equivale a Date.now() se vengono utilizzati timer reali o se Date è simulato. In altri casi (come i timer legacy) può essere utile per implementare mock personalizzati di Date.now(), performance.now(), ecc.

`jest.setSystemTime(now?: number | Date)`

Imposta l'ora di sistema corrente utilizzata dai timer fittizi. Simula un utente che cambia l'orologio di sistema durante l'esecuzione del programma. Influisce sull'ora corrente ma di per sé non causa, ad esempio, lo scatto dei timer; questi scatteranno esattamente come avrebbero fatto senza la chiamata a jest.setSystemTime().

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

`jest.setTimerTickMode(mode)`

Permette di configurare come i timer fake avanzano nel tempo.

Opzioni di configurazione:

type TimerTickMode =
  | {mode: 'manual'}
  | {mode: 'nextAsync'}
  | {mode: 'interval'; delta?: number};

manual: I timer non avanzano senza chiamate esplicite e manuali alle API tick (jest.advanceTimersByTime(ms), jest.runAllTimers(), ecc.).
nextAsync: L'orologio interromperà continuamente l'event loop, quindi eseguirà il timer successivo finché la modalità non cambia.
interval: Equivale a specificare advanceTimers: true con un advanceTimeDelta. Se il delta non è specificato, verrà utilizzato 20 per impostazione predefinita.

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

`jest.getRealSystemTime()`

Quando si simula il tempo, anche Date.now() verrà simulato. Se per qualche motivo hai bisogno di accedere all'ora corrente reale, puoi invocare questa funzione.

info

Questa funzione non è disponibile quando si utilizza l'implementazione legacy dei timer fittizi.

Varie

`jest.getSeed()`

Ogni volta che Jest viene eseguito, viene generato casualmente un valore di seed che puoi utilizzare in un generatore di numeri pseudocasuali o altrove.

suggerimento

Usa il flag --showSeed per stampare il seed nel riepilogo del report dei test. Per impostare manualmente il valore del seed usa l'argomento CLI --seed=<num>.

`jest.isEnvironmentTornDown()`

Restituisce true se l'ambiente di test è stato smontato.

`jest.retryTimes(numRetries, options?)`

Esegue i test falliti n volte finché non passano o fino a quando non viene raggiunto il numero massimo di tentativi.

jest.retryTimes(3);

test('will fail', () => {
  expect(true).toBe(false);
});

Se l'opzione logErrorsBeforeRetry è abilitata, gli errori che hanno causato il fallimento del test verranno registrati nella console.

jest.retryTimes(3, {logErrorsBeforeRetry: true});

test('will fail', () => {
  expect(true).toBe(false);
});

waitBeforeRetry è il numero di millisecondi di attesa prima di riprovare.

jest.retryTimes(3, {waitBeforeRetry: 1000});

test('will fail', () => {
  expect(true).toBe(false);
});

L'opzione retryImmediately viene utilizzata per riprovare il test fallito immediatamente dopo il fallimento. Se questa opzione non è specificata, i test vengono riprovati dopo che Jest ha terminato di eseguire tutti gli altri test nel file.

jest.retryTimes(3, {retryImmediately: true});

test('will fail', () => {
  expect(true).toBe(false);
});

Restituisce l'oggetto jest per il chaining.

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

jest.retryTimes() deve essere dichiarato al livello superiore di un file di test o in un blocco describe.

info

Questa funzione è disponibile solo con il runner predefinito jest-circus.

`jest.setTimeout(timeout)`

Imposta l'intervallo di timeout predefinito (in millisecondi) per tutti i test e gli hook before/after nel file di test. Questo influisce solo sul file di test da cui viene chiamata la funzione. L'intervallo di timeout predefinito è di 5 secondi se questo metodo non viene chiamato.

Esempio:

jest.setTimeout(1000); // 1 second

suggerimento

Per impostare intervalli di timeout diversi per test nello stesso file, usa l'opzione timeout su ogni singolo test.

Se vuoi impostare il timeout per tutti i file di test, usa l'opzione di configurazione testTimeout.

Metodi
Moduli Mock
Funzioni Mock
Timer Fittizi
Varie

Metodi​

Moduli Mock​

jest.disableAutomock()​

jest.enableAutomock()​

jest.createMockFromModule(moduleName)​

Function​

Class​

Object​

Array​

Primitives​

jest.mock(moduleName, factory, options)​

jest.Mocked<Source>​

jest.mocked(source, options?)​

jest.unmock(moduleName)​

jest.deepUnmock(moduleName)​

jest.doMock(moduleName, factory, options)​

jest.dontMock(moduleName)​

jest.setMock(moduleName, moduleExports)​

jest.requireActual(moduleName)​

jest.requireMock(moduleName)​

jest.onGenerateMock(cb)​

jest.resetModules()​

jest.isolateModules(fn)​

jest.isolateModulesAsync(fn)​

Funzioni Mock​

jest.fn(implementation?)​

jest.isMockFunction(fn)​

jest.replaceProperty(object, propertyKey, value)​

jest.spyOn(object, methodName)​

Metodi spiati e la parola chiave using​

jest.spyOn(object, methodName, accessType?)​

jest.Replaced<Source>​

jest.Spied<Source>​

jest.clearAllMocks()​

jest.resetAllMocks()​

jest.restoreAllMocks()​

Timer Fittizi​

jest.useFakeTimers(fakeTimersConfig?)​

jest.useRealTimers()​

jest.runAllTicks()​

jest.runAllTimers()​

jest.runAllTimersAsync()​

jest.runAllImmediates()​

jest.advanceTimersByTime(msToRun)​

jest.advanceTimersByTimeAsync(msToRun)​

jest.runOnlyPendingTimers()​

jest.runOnlyPendingTimersAsync()​

jest.advanceTimersToNextTimer(steps)​

jest.advanceTimersToNextTimerAsync(steps)​

jest.advanceTimersToNextFrame()​

jest.clearAllTimers()​

jest.getTimerCount()​

jest.now()​

jest.setSystemTime(now?: number | Date)​

jest.setTimerTickMode(mode)​

jest.getRealSystemTime()​

Varie​

jest.getSeed()​

jest.isEnvironmentTornDown()​

jest.retryTimes(numRetries, options?)​

jest.setTimeout(timeout)​

Metodi

Moduli Mock

`jest.disableAutomock()`

`jest.enableAutomock()`

`jest.createMockFromModule(moduleName)`

`Function`

`Class`

`Object`

`Array`

`Primitives`

`jest.mock(moduleName, factory, options)`

`jest.Mocked<Source>`

`jest.mocked(source, options?)`

`jest.unmock(moduleName)`

`jest.deepUnmock(moduleName)`

`jest.doMock(moduleName, factory, options)`

`jest.dontMock(moduleName)`

`jest.setMock(moduleName, moduleExports)`

`jest.requireActual(moduleName)`

`jest.requireMock(moduleName)`

`jest.onGenerateMock(cb)`

`jest.resetModules()`

`jest.isolateModules(fn)`

`jest.isolateModulesAsync(fn)`

Funzioni Mock

`jest.fn(implementation?)`

`jest.isMockFunction(fn)`

`jest.replaceProperty(object, propertyKey, value)`

`jest.spyOn(object, methodName)`

Metodi spiati e la parola chiave `using`

`jest.spyOn(object, methodName, accessType?)`

`jest.Replaced<Source>`

`jest.Spied<Source>`

`jest.clearAllMocks()`

`jest.resetAllMocks()`

`jest.restoreAllMocks()`

Timer Fittizi

`jest.useFakeTimers(fakeTimersConfig?)`

`jest.useRealTimers()`

`jest.runAllTicks()`

`jest.runAllTimers()`

`jest.runAllTimersAsync()`

`jest.runAllImmediates()`

`jest.advanceTimersByTime(msToRun)`

`jest.advanceTimersByTimeAsync(msToRun)`

`jest.runOnlyPendingTimers()`

`jest.runOnlyPendingTimersAsync()`

`jest.advanceTimersToNextTimer(steps)`

`jest.advanceTimersToNextTimerAsync(steps)`

`jest.advanceTimersToNextFrame()`

`jest.clearAllTimers()`

`jest.getTimerCount()`

`jest.now()`

`jest.setSystemTime(now?: number | Date)`

`jest.setTimerTickMode(mode)`

`jest.getRealSystemTime()`

Varie

`jest.getSeed()`

`jest.isEnvironmentTornDown()`

`jest.retryTimes(numRetries, options?)`

`jest.setTimeout(timeout)`