Mockovací funkce

Mockovací funkci můžete vytvořit pro sledování jejích volání pomocí metody vi.fn. Pokud chcete sledovat metodu na již vytvořeném objektu, můžete použít metodu vi.spyOn:

import { vi } from 'vitest';

const fn = vi.fn();
fn('hello world');
fn.mock.calls[0] === ['hello world'];

const market = {
  getApples: () => 100,
};

const getApplesSpy = vi.spyOn(market, 'getApples');
market.getApples();
getApplesSpy.mock.calls.length === 1;

Pro ověření výsledku mocku byste měli použít tvrzení pro mocky (např. toHaveBeenCalled) na expect. Tato API reference popisuje dostupné vlastnosti a metody pro manipulaci s chováním mocků.

TIP

Vlastní implementace funkce v níže uvedených typech je označena generickým typem <T>.

getMockImplementation

function getMockImplementation(): T | undefined;

Vrátí aktuální implementaci mocku, pokud nějaká existuje.

Pokud byl mock vytvořen pomocí metody vi.fn, použije se poskytnutá metoda jako implementace mocku.

Pokud byl mock vytvořen pomocí metody vi.spyOn, vrátí undefined, pokud není poskytnuta žádná vlastní implementace.

getMockName

function getMockName(): string;

Použijte tuto metodu k vrácení názvu přiřazeného mocku pomocí .mockName(name). Ve výchozím nastavení vrátí vi.fn() jako název.

mockClear

function mockClear(): MockInstance<T>;

Vymaže všechny informace o všech voláních. Po zavolání se všechny vlastnosti na .mock vrátí do svého počátečního stavu. Tato metoda neobnovuje implementace. Je užitečná pro úklid mocků mezi různými tvrzeními.

Pro automatické volání této metody před každým testem povolte nastavení clearMocks v konfiguraci.

mockName

function mockName(name: string): MockInstance<T>;

Nastaví interní název pro mock. To je užitečné pro identifikaci mocku, když dojde k selhání tvrzení.

mockImplementation

function mockImplementation(fn: T): MockInstance<T>;

Přijímá funkci, která bude použita jako implementace mocku. TypeScript očekává, že argumenty a návratový typ budou odpovídat těm původním.

const mockFn = vi.fn().mockImplementation((apples: number) => apples + 1);
// or: vi.fn(apples => apples + 1);

const NelliesBucket = mockFn(0);
const BobsBucket = mockFn(1);

NelliesBucket === 1; // true
BobsBucket === 2; // true

mockFn.mock.calls[0][0] === 0; // true
mockFn.mock.calls[1][0] === 1; // true

mockImplementationOnce

function mockImplementationOnce(fn: T): MockInstance<T>;

Přijímá funkci, která bude použita jako implementace mocku. TypeScript očekává, že argumenty a návratový typ budou odpovídat původní funkci. Tuto metodu lze řetězit, aby se dosáhlo různých výsledků pro více volání funkce.

const myMockFn = vi
  .fn()
  .mockImplementationOnce(() => true) // 1st call
  .mockImplementationOnce(() => false); // 2nd call

myMockFn(); // 1st call: true
myMockFn(); // 2nd call: false

Když mockované funkci dojdou definované implementace, vyvolá výchozí implementaci nastavenou pomocí vi.fn(() => defaultValue) nebo .mockImplementation(() => defaultValue), pokud byly nastaveny:

const myMockFn = vi
  .fn(() => 'default')
  .mockImplementationOnce(() => 'first call')
  .mockImplementationOnce(() => 'second call');

// 'first call', 'second call', 'default', 'default'
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn());

withImplementation

function withImplementation(fn: T, cb: () => void): MockInstance<T>;
function withImplementation(
  fn: T,
  cb: () => Promise<void>
): Promise<MockInstance<T>>;

Dočasně přepíše původní implementaci mocku po dobu provádění callbacku.

const myMockFn = vi.fn(() => 'original');

myMockFn.withImplementation(
  () => 'temp',
  () => {
    myMockFn(); // 'temp'
  }
);

myMockFn(); // 'original'

Lze použít s asynchronním callbackem. Metoda musí být očekávána, aby se poté obnovila původní implementace.

test('async callback', () => {
  const myMockFn = vi.fn(() => 'original');

  // We await this call since the callback is async
  await myMockFn.withImplementation(
    () => 'temp',
    async () => {
      myMockFn(); // 'temp'
    }
  );

  myMockFn(); // 'original'
});

Všimněte si, že tato metoda má přednost před mockImplementationOnce.

mockRejectedValue

function mockRejectedValue(value: unknown): MockInstance<T>;

Přijímá chybu, která bude zamítnuta při volání asynchronní funkce.

const asyncMock = vi.fn().mockRejectedValue(new Error('Async error'));

await asyncMock(); // throws Error<'Async error'>

mockRejectedValueOnce

function mockRejectedValueOnce(value: unknown): MockInstance<T>;

Přijímá hodnotu, která bude zamítnuta během dalšího volání funkce. Pokud je řetězena, každé následující volání zamítne zadanou hodnotu.

const asyncMock = vi
  .fn()
  .mockResolvedValueOnce('first call')
  .mockRejectedValueOnce(new Error('Async error'));

await asyncMock(); // 'first call'
await asyncMock(); // throws Error<'Async error'>

mockReset

function mockReset(): MockInstance<T>;

Provádí stejné akce jako mockClear a nastavuje vnitřní implementaci na prázdnou funkci (která při vyvolání vrací undefined). Tím se také resetují všechny "once" implementace. Je užitečné pro úplné resetování mocku do jeho výchozího stavu.

Pro automatické volání této metody před každým testem povolte nastavení mockReset v konfiguraci.

mockRestore

function mockRestore(): MockInstance<T>;

Provádí stejné akce jako mockReset a obnovuje vnitřní implementaci na původní funkci.

Všimněte si, že obnovení mocku vytvořeného pomocí vi.fn() nastaví implementaci na prázdnou funkci, která vrací undefined. Obnovení mocku vytvořeného pomocí vi.fn(impl) obnoví implementaci na impl.

Pro automatické volání této metody před každým testem povolte nastavení restoreMocks v konfiguraci.

mockResolvedValue

function mockResolvedValue(value: Awaited<ReturnType<T>>): MockInstance<T>;

Přijímá hodnotu, která bude splněna při volání asynchronní funkce. TypeScript přijme pouze hodnoty, které odpovídají návratovému typu původní funkce.

const asyncMock = vi.fn().mockResolvedValue(42);

await asyncMock(); // 42

mockResolvedValueOnce

function mockResolvedValueOnce(value: Awaited<ReturnType<T>>): MockInstance<T>;

Přijímá hodnotu, která bude splněna během dalšího volání funkce. TypeScript přijme pouze hodnoty, které odpovídají návratovému typu původní funkce. Pokud je řetězena, každé následující volání splní zadanou hodnotu.

const asyncMock = vi
  .fn()
  .mockResolvedValue('default')
  .mockResolvedValueOnce('first call')
  .mockResolvedValueOnce('second call');

await asyncMock(); // first call
await asyncMock(); // second call
await asyncMock(); // default
await asyncMock(); // default

mockReturnThis

function mockReturnThis(): MockInstance<T>;

Použijte tuto metodu, pokud potřebujete vrátit kontext this z metody bez vyvolání skutečné implementace. Toto je zkratka pro:

spy.mockImplementation(function () {
  return this;
});

mockReturnValue

function mockReturnValue(value: ReturnType<T>): MockInstance<T>;

Přijímá hodnotu, která bude vrácena při každém volání mockovací funkce. TypeScript přijme pouze hodnoty, které odpovídají návratovému typu původní funkce.

const mock = vi.fn();
mock.mockReturnValue(42);
mock(); // 42
mock.mockReturnValue(43);
mock(); // 43

mockReturnValueOnce

function mockReturnValueOnce(value: ReturnType<T>): MockInstance<T>;

Přijímá hodnotu, která bude vrácena při každém volání mockovací funkce. TypeScript přijme pouze hodnoty, které odpovídají návratovému typu původní funkce.

Když mockované funkci dojdou implementace, vyvolá výchozí implementaci nastavenou pomocí vi.fn(() => defaultValue) nebo .mockImplementation(() => defaultValue), pokud byly nastaveny:

const myMockFn = vi
  .fn()
  .mockReturnValue('default')
  .mockReturnValueOnce('first call')
  .mockReturnValueOnce('second call');

// 'first call', 'second call', 'default', 'default'
console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn());

mock.calls

const calls: Parameters<T>[];

Toto pole obsahuje všechny argumenty pro každé volání. Jedna položka pole obsahuje argumenty tohoto volání.

const fn = vi.fn();

fn('arg1', 'arg2');
fn('arg3');

fn.mock.calls ===
  [
    ['arg1', 'arg2'], // first call
    ['arg3'], // second call
  ];

mock.lastCall

const lastCall: Parameters<T> | undefined;

Zde jsou uloženy argumenty posledního volání. Pokud mock nebyl volán, vrátí undefined.

mock.results

interface MockResultReturn<T> {
  type: 'return';
  /**
   * The value that was returned from the function.
   * If function returned a Promise, then this will be a resolved value.
   */
  value: T;
}

interface MockResultIncomplete {
  type: 'incomplete';
  value: undefined;
}

interface MockResultThrow {
  type: 'throw';
  /**
   * An error that was thrown during function execution.
   */
  value: any;
}

type MockResult<T> =
  | MockResultReturn<T>
  | MockResultThrow
  | MockResultIncomplete;

const results: MockResult<ReturnType<T>>[];

Toto pole obsahuje všechny hodnoty, které byly vráceny z funkce. Jedna položka pole je objekt s vlastnostmi type a value. Dostupné typy jsou:

• 'return' - funkce se vrátila bez vyhození chyby.
• 'throw' - funkce vyhodila hodnotu.

Vlastnost value obsahuje vrácenou hodnotu nebo vyhozenou chybu. Pokud funkce vrátila Promise, pak result bude vždy 'return', i když byl promise zamítnut.

const fn = vi
  .fn()
  .mockReturnValueOnce('result')
  .mockImplementationOnce(() => {
    throw new Error('thrown error');
  });

const result = fn(); // returned 'result'

try {
  fn(); // threw Error
} catch {}

fn.mock.results ===
  [
    // first result
    {
      type: 'return',
      value: 'result',
    },
    // last result
    {
      type: 'throw',
      value: Error,
    },
  ];

mock.settledResults

interface MockSettledResultFulfilled<T> {
  type: 'fulfilled';
  value: T;
}

interface MockSettledResultRejected {
  type: 'rejected';
  value: any;
}

export type MockSettledResult<T> =
  | MockSettledResultFulfilled<T>
  | MockSettledResultRejected;

const settledResults: MockSettledResult<Awaited<ReturnType<T>>>[];

Pole obsahující všechny hodnoty, které byly splněny nebo zamítnuty z funkce.

Toto pole bude prázdné, pokud funkce nedokončila svůj běh nebo nebyla odmítnuta.

const fn = vi.fn().mockResolvedValueOnce('result');

const result = fn();

fn.mock.settledResults === [];

await result;

fn.mock.settledResults ===
  [
    {
      type: 'fulfilled',
      value: 'result',
    },
  ];

mock.invocationCallOrder

const invocationCallOrder: number[];

Tato vlastnost vrací pořadí spuštění mockovací funkce. Je to pole čísel sdílené mezi všemi definovanými mocky.

const fn1 = vi.fn();
const fn2 = vi.fn();

fn1();
fn2();
fn1();

fn1.mock.invocationCallOrder === [1, 3];
fn2.mock.invocationCallOrder === [2];

mock.contexts

const contexts: ThisParameterType<T>[];

Tato vlastnost je pole hodnot this použitých během každého volání mockovací funkce.

const fn = vi.fn();
const context = {};

fn.apply(context);
fn.call(context);

fn.mock.contexts[0] === context;
fn.mock.contexts[1] === context;

mock.instances

const instances: ReturnType<T>[];

Tato vlastnost je pole obsahující všechny instance, které byly vytvořeny, když byl mock volán s klíčovým slovem new. Pozor, jedná se o skutečný kontext (this) funkce, nikoli o návratovou hodnotu.

WARNING

Pokud byl mock instanciován pomocí new MyClass(), pak mock.instances bude pole s jednou hodnotou:

const MyClass = vi.fn();
const a = new MyClass();

MyClass.mock.instances[0] === a;

Pokud vrátíte hodnotu z konstruktoru, nebude v poli instances, ale místo toho uvnitř results:

const Spy = vi.fn(() => ({ method: vi.fn() }));
const a = new Spy();

Spy.mock.instances[0] !== a;
Spy.mock.results[0] === a;