expect

Los siguientes tipos son utilizados en las signaturas de tipo a continuación.

type Awaitable<T> = T | PromiseLike<T>;

expect se utiliza para crear aserciones. En este contexto, las aserciones son funciones que se pueden invocar para validar una declaración. Vitest proporciona aserciones de chai por defecto y también aserciones compatibles con Jest construidas sobre chai. A diferencia de Jest, Vitest admite un mensaje como segundo argumento; si la aserción falla, el mensaje de error será el proporcionado.

export interface ExpectStatic
  extends Chai.ExpectStatic,
    AsymmetricMatchersContaining {
  <T>(actual: T, message?: string): Assertion<T>;
  extend: (expects: MatchersObject) => void;
  anything: () => any;
  any: (constructor: unknown) => any;
  getState: () => MatcherState;
  setState: (state: Partial<MatcherState>) => void;
  not: AsymmetricMatchersContaining;
}

Por ejemplo, este código afirma que un valor input es igual a 2. Si no lo es, la aserción lanzará un error y la prueba fallará.

import { expect } from 'vitest';

const input = Math.sqrt(4);

expect(input).to.equal(2); // API de chai
expect(input).toBe(2); // API de jest

Técnicamente, este ejemplo no utiliza la función test, por lo que en la consola verá un error de Node.js en lugar de la salida de Vitest. Para obtener más información sobre test, lea la Referencia de la API de prueba.

Además, expect se puede usar estáticamente para acceder a las funciones de matcher, descritas más adelante, y más.

WARNING

expect no tiene efecto en los tipos de prueba si la expresión no presenta un error de tipo. Si desea usar Vitest como verificador de tipos, use expectTypeOf o assertType.

soft

• Tipo: ExpectStatic & (actual: any) => Assertions

expect.soft funciona de manera similar a expect, pero en lugar de terminar la ejecución de la prueba ante una aserción fallida, continúa ejecutándose y marca la prueba como fallida. Todos los errores encontrados durante la prueba se mostrarán hasta que la prueba se complete.

import { expect, test } from 'vitest';

test('expect.soft test', () => {
  expect.soft(1 + 1).toBe(3); // marca la prueba como fallida y continúa
  expect.soft(1 + 2).toBe(4); // marca la prueba como fallida y continúa
});
// el reportero informará de ambos errores al final de la ejecución

También se puede usar con expect. Si la aserción expect falla, la prueba se terminará y se mostrarán todos los errores.

import { expect, test } from 'vitest';

test('expect.soft test', () => {
  expect.soft(1 + 1).toBe(3); // marca la prueba como fallida y continúa
  expect(1 + 2).toBe(4); // falla y termina la prueba, se mostrarán todos los errores anteriores
  expect.soft(1 + 3).toBe(5); // no se ejecuta
});

WARNING

expect.soft solo se puede usar dentro de la función test.

poll

interface ExpectPoll extends ExpectStatic {
  (actual: () => T, options: { interval; timeout; message }): Promise<
    Assertions<T>
  >;
}

expect.poll vuelve a ejecutar la aserción hasta que sea exitosa. Puede configurar cuántas veces Vitest debe volver a ejecutar la devolución de llamada expect.poll estableciendo las opciones interval y timeout.

Si se lanza un error dentro de la devolución de llamada expect.poll, Vitest reintentará hasta que se agote el tiempo de espera.

import { expect, test } from 'vitest';

test('element exists', async () => {
  asyncInjectElement();

  await expect.poll(() => document.querySelector('.element')).toBeTruthy();
});

WARNING

expect.poll hace que cada aserción sea asíncrona, por lo que debe esperarla. Desde Vitest 3, si olvida esperarla, la prueba fallará con una advertencia para hacerlo.

expect.poll no funciona con varios matchers:

• Los matchers de instantáneas no son compatibles porque siempre tendrán éxito. Si su condición es inestable, considere usar vi.waitFor en su lugar para resolverla primero:

import { expect, vi } from 'vitest';

const flakyValue = await vi.waitFor(() => getFlakyValue());
expect(flakyValue).toMatchSnapshot();

• .resolves y .rejects no son compatibles. expect.poll ya espera la condición si es asíncrona.
• toThrow y sus alias no son compatibles porque la condición expect.poll siempre se resuelve antes de que el matcher reciba el valor.

not

El uso de not negará la aserción. Por ejemplo, este código afirma que un valor input no es igual a 2. Si es igual, la aserción lanzará un error y la prueba fallará.

import { expect, test } from 'vitest';

const input = Math.sqrt(16);

expect(input).not.to.equal(2); // API de chai
expect(input).not.toBe(2); // API de jest

toBe

• Tipo: (value: any) => Awaitable<void>

toBe se puede usar para afirmar si los tipos primitivos son iguales o si los objetos comparten la misma referencia. Es equivalente a llamar a expect(Object.is(3, 3)).toBe(true). Si los objetos no son los mismos, pero desea verificar si sus estructuras son idénticas, puede usar toEqual.

Por ejemplo, el código siguiente verifica si el comerciante tiene 13 manzanas.

import { expect, test } from 'vitest';

const stock = {
  type: 'apples',
  count: 13,
};

test('stock has 13 apples', () => {
  expect(stock.type).toBe('apples');
  expect(stock.count).toBe(13);
});

test('stocks are the same', () => {
  const refStock = stock; // misma referencia

  expect(stock).toBe(refStock);
});

Intente no usar toBe con números de punto flotante. Dado que JavaScript los redondea, 0.1 + 0.2 no es estrictamente 0.3. Para realizar aserciones confiables sobre números de punto flotante, use la aserción toBeCloseTo.

toBeCloseTo

• Tipo: (value: number, numDigits?: number) => Awaitable<void>

Use toBeCloseTo para comparar números de punto flotante. El argumento opcional numDigits limita el número de dígitos a verificar después del punto decimal. Por ejemplo:

import { expect, test } from 'vitest';

test.fails('decimals are not equal in javascript', () => {
  expect(0.2 + 0.1).toBe(0.3); // 0.2 + 0.1 es 0.30000000000000004
});

test('decimals are rounded to 5 after the point', () => {
  // 0.2 + 0.1 es 0.30000 | "000000000004" eliminado
  expect(0.2 + 0.1).toBeCloseTo(0.3, 5);
  // nada de 0.30000000000000004 es eliminado
  expect(0.2 + 0.1).not.toBeCloseTo(0.3, 50);
});

toBeDefined

• Tipo: () => Awaitable<void>

toBeDefined afirma que el valor no es igual a undefined. Sería útil para verificar si la función devolvió algo.

import { expect, test } from 'vitest';

function getApples() {
  return 3;
}

test('function returned something', () => {
  expect(getApples()).toBeDefined();
});

toBeUndefined

• Tipo: () => Awaitable<void>

Opuesto a toBeDefined, toBeUndefined afirma que el valor es igual a undefined. Sería útil para verificar si la función no devolvió nada.

import { expect, test } from 'vitest';

function getApplesFromStock(stock: string) {
  if (stock === 'Bill') {
    return 13;
  }
}

test("mary doesn't have a stock", () => {
  expect(getApplesFromStock('Mary')).toBeUndefined();
});

toBeTruthy

• Tipo: () => Awaitable<void>

toBeTruthy afirma que el valor es verdadero cuando se convierte a booleano. Útil si no le interesa el valor específico, pero solo quiere saber si se puede convertir a true.

Por ejemplo, con este código no necesita preocuparse por el valor de retorno de stocks.getInfo; puede ser un objeto complejo, una cadena o cualquier otra cosa. El código seguirá funcionando.

import { Stocks } from './stocks.js';

const stocks = new Stocks();
stocks.sync('Bill');
if (stocks.getInfo('Bill')) {
  stocks.sell('apples', 'Bill');
}

Entonces, si desea probar que stocks.getInfo evaluará como verdadero, podría escribir:

import { expect, test } from 'vitest';
import { Stocks } from './stocks.js';

const stocks = new Stocks();

test('if we know Bill stock, sell apples to him', () => {
  stocks.sync('Bill');
  expect(stocks.getInfo('Bill')).toBeTruthy();
});

Todo en JavaScript es truthy (evalúa como verdadero), excepto false, null, undefined, NaN, 0, -0, 0n, "" y document.all.

toBeFalsy

• Tipo: () => Awaitable<void>

toBeFalsy afirma que el valor es falso cuando se convierte a booleano. Útil si no le interesa el valor específico, pero solo quiere saber si se puede convertir a false.

Por ejemplo, con este código no necesita preocuparse por el valor de retorno de stocks.stockFailed; puede devolver cualquier valor falsy, pero el código seguirá funcionando.

import { Stocks } from './stocks.js';

const stocks = new Stocks();
stocks.sync('Bill');
if (!stocks.stockFailed('Bill')) {
  stocks.sell('apples', 'Bill');
}

Entonces, si desea probar que stocks.stockFailed evaluará como falso, podría escribir:

import { expect, test } from 'vitest';
import { Stocks } from './stocks.js';

const stocks = new Stocks();

test("if Bill stock hasn't failed, sell apples to him", () => {
  stocks.syncStocks('Bill');
  expect(stocks.stockFailed('Bill')).toBeFalsy();
});

Todo en JavaScript es truthy (evalúa como verdadero), excepto false, null, undefined, NaN, 0, -0, 0n, "" y document.all.

toBeNull

• Tipo: () => Awaitable<void>

toBeNull simplemente afirma si algo es null. Es un alias de .toBe(null).

import { expect, test } from 'vitest';

function apples() {
  return null;
}

test("we don't have apples", () => {
  expect(apples()).toBeNull();
});

toBeNaN

• Tipo: () => Awaitable<void>

toBeNaN simplemente afirma si algo es NaN. Es un alias de .toBe(NaN).

import { expect, test } from 'vitest';

let i = 0;

function getApplesCount() {
  i++;
  return i > 1 ? Number.NaN : i;
}

test('getApplesCount has some unusual side effects...', () => {
  expect(getApplesCount()).not.toBeNaN();
  expect(getApplesCount()).toBeNaN();
});

toBeOneOf

• Tipo: (sample: Array<any>) => any

toBeOneOf afirma si un valor coincide con alguno de los valores del array proporcionado.

import { expect, test } from 'vitest';

test('fruit is one of the allowed values', () => {
  expect(fruit).toBeOneOf(['apple', 'banana', 'orange']);
});

Este matcher asimétrico resulta particularmente útil al probar propiedades opcionales que podrían ser null o undefined:

test('optional properties can be null or undefined', () => {
  const user = {
    firstName: 'John',
    middleName: undefined,
    lastName: 'Doe',
  };

  expect(user).toEqual({
    firstName: expect.any(String),
    middleName: expect.toBeOneOf([expect.any(String), undefined]),
    lastName: expect.any(String),
  });
});

TIP

Puede usar expect.not con este matcher para asegurarse de que un valor NO coincida con ninguna de las opciones proporcionadas.

toBeTypeOf

• Tipo: (c: 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'undefined') => Awaitable<void>

toBeTypeOf afirma si un valor real es del tipo especificado.

import { expect, test } from 'vitest';

const actual = 'stock';

test('stock is type of string', () => {
  expect(actual).toBeTypeOf('string');
});

toBeInstanceOf

• Tipo: (c: any) => Awaitable<void>

toBeInstanceOf afirma si un valor real es una instancia de la clase recibida.

import { expect, test } from 'vitest';
import { Stocks } from './stocks.js';

const stocks = new Stocks();

test('stocks are instance of Stocks', () => {
  expect(stocks).toBeInstanceOf(Stocks);
});

toBeGreaterThan

• Tipo: (n: number | bigint) => Awaitable<void>

toBeGreaterThan afirma si el valor real es mayor que el recibido. Los valores iguales provocarán que la prueba falle.

import { expect, test } from 'vitest';
import { getApples } from './stocks.js';

test('have more then 10 apples', () => {
  expect(getApples()).toBeGreaterThan(10);
});

toBeGreaterThanOrEqual

• Tipo: (n: number | bigint) => Awaitable<void>

toBeGreaterThanOrEqual afirma si el valor real es mayor o igual que el recibido.

import { expect, test } from 'vitest';
import { getApples } from './stocks.js';

test('have 11 apples or more', () => {
  expect(getApples()).toBeGreaterThanOrEqual(11);
});

toBeLessThan

• Tipo: (n: number | bigint) => Awaitable<void>

toBeLessThan afirma si el valor real es menor que el recibido. Los valores iguales provocarán que la prueba falle.

import { expect, test } from 'vitest';
import { getApples } from './stocks.js';

test('have less then 20 apples', () => {
  expect(getApples()).toBeLessThan(20);
});

toBeLessThanOrEqual

• Tipo: (n: number | bigint) => Awaitable<void>

toBeLessThanOrEqual afirma si el valor real es menor o igual que el recibido.

import { expect, test } from 'vitest';
import { getApples } from './stocks.js';

test('have 11 apples or less', () => {
  expect(getApples()).toBeLessThanOrEqual(11);
});

toEqual

• Tipo: (received: any) => Awaitable<void>

toEqual afirma si el valor real es igual al valor recibido o tiene la misma estructura, si es un objeto (los compara recursivamente). Puede ver la diferencia entre toEqual y toBe en este ejemplo:

import { expect, test } from 'vitest';

const stockBill = {
  type: 'apples',
  count: 13,
};

const stockMary = {
  type: 'apples',
  count: 13,
};

test('stocks have the same properties', () => {
  expect(stockBill).toEqual(stockMary);
});

test('stocks are not the same', () => {
  expect(stockBill).not.toBe(stockMary);
});

WARNING

Para los objetos Error, las propiedades no enumerables como name, message, cause y AggregateError.errors también son comparadas. Para Error.cause, la comparación se realiza de forma asimétrica:

// éxito
expect(new Error('hi', { cause: 'x' })).toEqual(new Error('hi'));

// fallo
expect(new Error('hi')).toEqual(new Error('hi', { cause: 'x' }));

Para probar si se lanzó algo, use la aserción toThrowError.

toStrictEqual

• Tipo: (received: any) => Awaitable<void>

toStrictEqual afirma si el valor real es igual al valor recibido o tiene la misma estructura si es un objeto (los compara recursivamente), y del mismo tipo.

Diferencias con .toEqual:

• Se verifican las claves con propiedades undefined. Por ejemplo, {a: undefined, b: 2} no coincide con {b: 2} al usar .toStrictEqual.
• Se verifica la dispersión del array. Por ejemplo, [, 1] no coincide con [undefined, 1] al usar .toStrictEqual.
• Se verifica que los tipos de objeto sean iguales. Por ejemplo, una instancia de clase con campos a y b no será igual a un objeto literal con campos a y b.

import { expect, test } from 'vitest';

class Stock {
  constructor(type) {
    this.type = type;
  }
}

test('structurally the same, but semantically different', () => {
  expect(new Stock('apples')).toEqual({ type: 'apples' });
  expect(new Stock('apples')).not.toStrictEqual({ type: 'apples' });
});

toContain

• Tipo: (received: string) => Awaitable<void>

toContain afirma si el valor real está en un array. toContain también puede verificar si una cadena es una subcadena de otra cadena. Si está ejecutando pruebas en un entorno similar a un navegador, esta aserción también puede verificar si una clase CSS está contenida en una classList, o si un elemento está dentro de otro.

import { expect, test } from 'vitest';
import { getAllFruits } from './stocks.js';

test('the fruit list contains orange', () => {
  expect(getAllFruits()).toContain('orange');

  const element = document.querySelector('#el');
  // el elemento tiene una clase
  expect(element.classList).toContain('flex');
  // el elemento está dentro de otro
  expect(document.querySelector('#wrapper')).toContain(element);
});

toContainEqual

• Tipo: (received: any) => Awaitable<void>

toContainEqual afirma si un elemento con una estructura y valores específicos está contenido en un array. Funciona aplicando toEqual a cada elemento.

import { expect, test } from 'vitest';
import { getFruitStock } from './stocks.js';

test('apple available', () => {
  expect(getFruitStock()).toContainEqual({ fruit: 'apple', count: 5 });
});

toHaveLength

• Tipo: (received: number) => Awaitable<void>

toHaveLength afirma si un objeto tiene una propiedad .length y su valor es un número determinado.

import { expect, test } from 'vitest';

test('toHaveLength', () => {
  expect('abc').toHaveLength(3);
  expect([1, 2, 3]).toHaveLength(3);

  expect('').not.toHaveLength(3); // no tiene .length de 3
  expect({ length: 3 }).toHaveLength(3);
});

toHaveProperty

• Tipo: (key: any, received?: any) => Awaitable<void>

toHaveProperty afirma si una propiedad, identificada por la key de referencia proporcionada, existe en un objeto.

Puede proporcionar un argumento de valor opcional (conocido como comparación profunda), similar al matcher toEqual, para comparar el valor de la propiedad recibida.

import { expect, test } from 'vitest';

const invoice = {
  isActive: true,
  'P.O': '12345',
  customer: {
    first_name: 'John',
    last_name: 'Doe',
    location: 'China',
  },
  total_amount: 5000,
  items: [
    {
      type: 'apples',
      quantity: 10,
    },
    {
      type: 'oranges',
      quantity: 5,
    },
  ],
};

test('John Doe Invoice', () => {
  expect(invoice).toHaveProperty('isActive'); // afirma que la clave existe
  expect(invoice).toHaveProperty('total_amount', 5000); // afirma que la clave existe y el valor es igual

  expect(invoice).not.toHaveProperty('account'); // afirma que esta clave no existe

  // Referencia profunda usando notación de puntos
  expect(invoice).toHaveProperty('customer.first_name');
  expect(invoice).toHaveProperty('customer.last_name', 'Doe');
  expect(invoice).not.toHaveProperty('customer.location', 'India');

  // Referencia profunda usando un array que contiene la clave
  expect(invoice).toHaveProperty('items[0].type', 'apples');
  expect(invoice).toHaveProperty('items.0.type', 'apples'); // la notación de puntos también funciona

  // Referencia profunda usando un array que contiene la ruta de la clave
  expect(invoice).toHaveProperty(['items', 0, 'type'], 'apples');
  expect(invoice).toHaveProperty(['items', '0', 'type'], 'apples'); // la notación de cadena también funciona

  // Envuelva su clave en un array para evitar que la clave se analice como una referencia profunda
  expect(invoice).toHaveProperty(['P.O'], '12345');
});

toMatch

• Tipo: (received: string | regexp) => Awaitable<void>

toMatch afirma si una cadena coincide con una expresión regular o una cadena.

import { expect, test } from 'vitest';

test('top fruits', () => {
  expect('top fruits include apple, orange and grape').toMatch(/apple/);
  expect('applefruits').toMatch('fruit'); // toMatch también acepta una cadena
});

toMatchObject

• Tipo: (received: object | array) => Awaitable<void>

toMatchObject afirma si un objeto coincide con un subconjunto de sus propiedades.

También puede pasar un array de objetos. Esto es útil si desea verificar que dos arrays tengan el mismo número de elementos, a diferencia de arrayContaining, que permite elementos adicionales en el array recibido.

import { expect, test } from 'vitest';

const johnInvoice = {
  isActive: true,
  customer: {
    first_name: 'John',
    last_name: 'Doe',
    location: 'China',
  },
  total_amount: 5000,
  items: [
    {
      type: 'apples',
      quantity: 10,
    },
    {
      type: 'oranges',
      quantity: 5,
    },
  ],
};

const johnDetails = {
  customer: {
    first_name: 'John',
    last_name: 'Doe',
    location: 'China',
  },
};

test('invoice has john personal details', () => {
  expect(johnInvoice).toMatchObject(johnDetails);
});

test('the number of elements must match exactly', () => {
  // Afirma que un array de objetos coincide
  expect([{ foo: 'bar' }, { baz: 1 }]).toMatchObject([
    { foo: 'bar' },
    { baz: 1 },
  ]);
});

toThrowError

• Tipo: (received: any) => Awaitable<void>

• Alias: toThrow

toThrowError afirma si una función lanza un error al ser llamada.

Puede proporcionar un argumento opcional para probar que se lanza un error específico:

• RegExp: el mensaje de error coincide con el patrón
• string: el mensaje de error incluye la subcadena
• Error, AsymmetricMatcher: comparar con un objeto recibido similar a toEqual(received)

TIP

Debe envolver el código en una función; de lo contrario, el error no será capturado y la prueba fallará.

Esto no se aplica a las llamadas asíncronas, ya que rejects maneja correctamente la promesa:

test('expect rejects toThrow', async ({ expect }) => {
  const promise = Promise.reject(new Error('Test'));
  await expect(promise).rejects.toThrowError();
});

Por ejemplo, si queremos probar que getFruitStock('pineapples') lanza un error, podríamos escribir:

import { expect, test } from 'vitest';

function getFruitStock(type: string) {
  if (type === 'pineapples') {
    throw new Error('Pineapples are not in stock');
  }

  // Hacer otras cosas
}

test('throws on pineapples', () => {
  // Probar que el mensaje de error dice "stock" en algún lugar: estos son equivalentes
  expect(() => getFruitStock('pineapples')).toThrowError(/stock/);
  expect(() => getFruitStock('pineapples')).toThrowError('stock');

  // Probar el mensaje de error exacto
  expect(() => getFruitStock('pineapples')).toThrowError(
    /^Pineapples are not in stock$/
  );

  expect(() => getFruitStock('pineapples')).toThrowError(
    new Error('Pineapples are not in stock')
  );
  expect(() => getFruitStock('pineapples')).toThrowError(
    expect.objectContaining({
      message: 'Pineapples are not in stock',
    })
  );
});

TIP

Para probar funciones asíncronas, use en combinación con rejects.

function getAsyncFruitStock() {
  return Promise.reject(new Error('empty'));
}

test('throws on pineapples', async () => {
  await expect(() => getAsyncFruitStock()).rejects.toThrowError('empty');
});

toMatchSnapshot

• Tipo: <T>(shape?: Partial<T> | string, hint?: string) => void

Esto asegura que un valor coincida con la instantánea más reciente.

Puede proporcionar un argumento de cadena hint opcional que se adjunta al nombre de la prueba. Aunque Vitest siempre agrega un número al final de un nombre de instantánea, las sugerencias descriptivas cortas pueden ser más útiles que los números para diferenciar múltiples instantáneas en un solo bloque it o test. Vitest ordena las instantáneas por nombre en el archivo .snap correspondiente.

TIP

Cuando una instantánea no coincide y provoca que la prueba falle, si la falta de coincidencia es esperada, puede presionar la tecla u para actualizar la instantánea una vez. O puede pasar las opciones de CLI -u o --update para que Vitest siempre actualice las pruebas.

import { expect, test } from 'vitest';

test('matches snapshot', () => {
  const data = { foo: new Set(['bar', 'snapshot']) };
  expect(data).toMatchSnapshot();
});

También puede proporcionar un esquema de un objeto, si solo está probando la estructura de un objeto y no necesita que sea 100% compatible:

import { expect, test } from 'vitest';

test('matches snapshot', () => {
  const data = { foo: new Set(['bar', 'snapshot']) };
  expect(data).toMatchSnapshot({ foo: expect.any(Set) });
});

toMatchInlineSnapshot

• Tipo: <T>(shape?: Partial<T> | string, snapshot?: string, hint?: string) => void

Esto asegura que un valor coincida con la instantánea más reciente.

Vitest añade y actualiza el argumento de cadena inlineSnapshot al matcher en el archivo de prueba (en lugar de un archivo .snap externo).

import { expect, test } from 'vitest';

test('matches inline snapshot', () => {
  const data = { foo: new Set(['bar', 'snapshot']) };
  // Vitest actualizará el siguiente contenido al actualizar la instantánea
  expect(data).toMatchInlineSnapshot(`
    {
      "foo": Set {
        "bar",
        "snapshot",
      },
    }
  `);
});

También puede proporcionar un esquema de un objeto, si solo está probando la estructura de un objeto y no necesita que sea 100% compatible:

import { expect, test } from 'vitest';

test('matches snapshot', () => {
  const data = { foo: new Set(['bar', 'snapshot']) };
  expect(data).toMatchInlineSnapshot(
    { foo: expect.any(Set) },
    `
    {
      "foo": Any<Set>,
    }
  `
  );
});

toMatchFileSnapshot

• Tipo: <T>(filepath: string, hint?: string) => Promise<void>

Compara o actualiza la instantánea con el contenido de un archivo especificado explícitamente (en lugar del archivo .snap).

import { expect, it } from 'vitest';

it('render basic', async () => {
  const result = renderHTML(h('div', { class: 'foo' }));
  await expect(result).toMatchFileSnapshot('./test/basic.output.html');
});

Tenga en cuenta que, dado que la operación del sistema de archivos es asíncrona, debe usar await con toMatchFileSnapshot(). Si no se usa await, Vitest lo trata como expect.soft, lo que significa que el código después de la declaración continuará ejecutándose incluso si la instantánea no coincide. Una vez que la prueba finaliza, Vitest verificará la instantánea y fallará si no coincide.

toThrowErrorMatchingSnapshot

• Tipo: (hint?: string) => void

Lo mismo que toMatchSnapshot, pero espera el mismo valor que toThrowError.

toThrowErrorMatchingInlineSnapshot

• Tipo: (snapshot?: string, hint?: string) => void

Lo mismo que toMatchInlineSnapshot, pero espera el mismo valor que toThrowError.

toHaveBeenCalled

• Tipo: () => Awaitable<void>

Esta aserción es útil para probar que una función ha sido llamada. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

const market = {
  buy(subject: string, amount: number) {
    // ...
  },
};

test('spy function', () => {
  const buySpy = vi.spyOn(market, 'buy');

  expect(buySpy).not.toHaveBeenCalled();

  market.buy('apples', 10);

  expect(buySpy).toHaveBeenCalled();
});

toHaveBeenCalledTimes

• Tipo: (amount: number) => Awaitable<void>

Esta aserción verifica si una función fue llamada una cierta cantidad de veces. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

const market = {
  buy(subject: string, amount: number) {
    // ...
  },
};

test('spy function called two times', () => {
  const buySpy = vi.spyOn(market, 'buy');

  market.buy('apples', 10);
  market.buy('apples', 20);

  expect(buySpy).toHaveBeenCalledTimes(2);
});

toHaveBeenCalledWith

• Tipo: (...args: any[]) => Awaitable<void>

Esta aserción verifica si una función fue llamada al menos una vez con ciertos parámetros. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

const market = {
  buy(subject: string, amount: number) {
    // ...
  },
};

test('spy function', () => {
  const buySpy = vi.spyOn(market, 'buy');

  market.buy('apples', 10);
  market.buy('apples', 20);

  expect(buySpy).toHaveBeenCalledWith('apples', 10);
  expect(buySpy).toHaveBeenCalledWith('apples', 20);
});

toHaveBeenCalledBefore 3.0.0+

• Tipo: (mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>

Esta aserción verifica si un Mock fue llamado antes que otro Mock.

test('calls mock1 before mock2', () => {
  const mock1 = vi.fn();
  const mock2 = vi.fn();

  mock1();
  mock2();
  mock1();

  expect(mock1).toHaveBeenCalledBefore(mock2);
});

toHaveBeenCalledAfter 3.0.0+

• Tipo: (mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>

Esta aserción verifica si un Mock fue llamado después de otro Mock.

test('calls mock1 after mock2', () => {
  const mock1 = vi.fn();
  const mock2 = vi.fn();

  mock2();
  mock1();
  mock2();

  expect(mock1).toHaveBeenCalledAfter(mock2);
});

toHaveBeenCalledExactlyOnceWith 3.0.0+

• Tipo: (...args: any[]) => Awaitable<void>

Esta aserción verifica si una función fue llamada exactamente una vez y con ciertos parámetros. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

const market = {
  buy(subject: string, amount: number) {
    // ...
  },
};

test('spy function', () => {
  const buySpy = vi.spyOn(market, 'buy');

  market.buy('apples', 10);

  expect(buySpy).toHaveBeenCalledExactlyOnceWith('apples', 10);
});

toHaveBeenLastCalledWith

• Tipo: (...args: any[]) => Awaitable<void>

Esta aserción verifica si una función fue llamada con ciertos parámetros en su última invocación. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

const market = {
  buy(subject: string, amount: number) {
    // ...
  },
};

test('spy function', () => {
  const buySpy = vi.spyOn(market, 'buy');

  market.buy('apples', 10);
  market.buy('apples', 20);

  expect(buySpy).not.toHaveBeenLastCalledWith('apples', 10);
  expect(buySpy).toHaveBeenLastCalledWith('apples', 20);
});

toHaveBeenNthCalledWith

• Tipo: (time: number, ...args: any[]) => Awaitable<void>

Esta aserción verifica si una función fue llamada con ciertos parámetros en una invocación específica. El conteo comienza en 1. Por lo tanto, para verificar la segunda entrada, escribiría .toHaveBeenNthCalledWith(2, ...).

Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

const market = {
  buy(subject: string, amount: number) {
    // ...
  },
};

test('first call of spy function called with right params', () => {
  const buySpy = vi.spyOn(market, 'buy');

  market.buy('apples', 10);
  market.buy('apples', 20);

  expect(buySpy).toHaveBeenNthCalledWith(1, 'apples', 10);
});

toHaveReturned

• Tipo: () => Awaitable<void>

Esta aserción verifica si una función ha retornado un valor exitosamente al menos una vez (es decir, no lanzó un error). Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

function getApplesPrice(amount: number) {
  const PRICE = 10;
  return amount * PRICE;
}

test('spy function returned a value', () => {
  const getPriceSpy = vi.fn(getApplesPrice);

  const price = getPriceSpy(10);

  expect(price).toBe(100);
  expect(getPriceSpy).toHaveReturned();
});

toHaveReturnedTimes

• Tipo: (amount: number) => Awaitable<void>

Esta aserción verifica si una función ha retornado un valor exitosamente una cantidad exacta de veces (es decir, no lanzó un error). Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

test('spy function returns a value two times', () => {
  const sell = vi.fn((product: string) => ({ product }));

  sell('apples');
  sell('bananas');

  expect(sell).toHaveReturnedTimes(2);
});

toHaveReturnedWith

• Tipo: (returnValue: any) => Awaitable<void>

Puede usar esta aserción para verificar si una función ha retornado un valor exitosamente con ciertos parámetros al menos una vez. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

test('spy function returns a product', () => {
  const sell = vi.fn((product: string) => ({ product }));

  sell('apples');

  expect(sell).toHaveReturnedWith({ product: 'apples' });
});

toHaveLastReturnedWith

• Tipo: (returnValue: any) => Awaitable<void>

Puede usar esta aserción para verificar si una función ha retornado exitosamente un valor determinado cuando fue invocada por última vez. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

test('spy function returns bananas on a last call', () => {
  const sell = vi.fn((product: string) => ({ product }));

  sell('apples');
  sell('bananas');

  expect(sell).toHaveLastReturnedWith({ product: 'bananas' });
});

toHaveNthReturnedWith

• Tipo: (time: number, returnValue: any) => Awaitable<void>

Puede usar esta aserción para verificar si una función ha retornado un valor exitosamente con ciertos parámetros en una llamada específica. Para usarla, se requiere pasar una función espía a expect.

import { expect, test, vi } from 'vitest';

test('spy function returns bananas on second call', () => {
  const sell = vi.fn((product: string) => ({ product }));

  sell('apples');
  sell('bananas');

  expect(sell).toHaveNthReturnedWith(2, { product: 'bananas' });
});

toHaveResolved

• Tipo: () => Awaitable<void>

Esta aserción verifica si una función ha resuelto un valor exitosamente al menos una vez (es decir, no rechazó). Para usarla, se requiere pasar una función espía a expect.

Si la función devolvió una promesa, pero aún no ha sido resuelta, esto fallará.

import { expect, test, vi } from 'vitest';
import db from './db/apples.js';

async function getApplesPrice(amount: number) {
  return amount * (await db.get('price'));
}

test('spy function resolved a value', async () => {
  const getPriceSpy = vi.fn(getApplesPrice);

  const price = await getPriceSpy(10);

  expect(price).toBe(100);
  expect(getPriceSpy).toHaveResolved();
});

toHaveResolvedTimes

• Tipo: (amount: number) => Awaitable<void>

Esta aserción verifica si una función ha resuelto un valor exitosamente una cantidad exacta de veces (es decir, no rechazó). Para usarla, se requiere pasar una función espía a expect.

Esto solo contará las promesas resueltas. Si la función devolvió una promesa, pero aún no ha sido resuelta, no se contará.

import { expect, test, vi } from 'vitest';

test('spy function resolved a value two times', async () => {
  const sell = vi.fn((product: string) => Promise.resolve({ product }));

  await sell('apples');
  await sell('bananas');

  expect(sell).toHaveResolvedTimes(2);
});

toHaveResolvedWith

• Tipo: (returnValue: any) => Awaitable<void>

Puede usar esta aserción para verificar si una función ha resuelto exitosamente un valor determinado al menos una vez. Para usarla, se requiere pasar una función espía a expect.

Si la función devolvió una promesa, pero aún no ha sido resuelta, esto fallará.

import { expect, test, vi } from 'vitest';

test('spy function resolved a product', async () => {
  const sell = vi.fn((product: string) => Promise.resolve({ product }));

  await sell('apples');

  expect(sell).toHaveResolvedWith({ product: 'apples' });
});

toHaveLastResolvedWith

• Tipo: (returnValue: any) => Awaitable<void>

Puede usar esta aserción para verificar si una función ha resuelto exitosamente un valor determinado cuando fue invocada por última vez. Para usarla, se requiere pasar una función espía a expect.

Si la función devolvió una promesa, pero aún no ha sido resuelta, esto fallará.

import { expect, test, vi } from 'vitest';

test('spy function resolves bananas on a last call', async () => {
  const sell = vi.fn((product: string) => Promise.resolve({ product }));

  await sell('apples');
  await sell('bananas');

  expect(sell).toHaveLastResolvedWith({ product: 'bananas' });
});

toHaveNthResolvedWith

• Tipo: (time: number, returnValue: any) => Awaitable<void>

Puede usar esta aserción para verificar si una función ha resuelto exitosamente un valor determinado en una invocación específica. Para usarla, se requiere pasar una función espía a expect.

Si la función devolvió una promesa, pero aún no ha sido resuelta, esto fallará.

import { expect, test, vi } from 'vitest';

test('spy function returns bananas on second call', async () => {
  const sell = vi.fn((product: string) => Promise.resolve({ product }));

  await sell('apples');
  await sell('bananas');

  expect(sell).toHaveNthResolvedWith(2, { product: 'bananas' });
});

toSatisfy

• Tipo: (predicate: (value: any) => boolean) => Awaitable<void>

Esta aserción verifica si un valor satisface un predicado determinado.

import { describe, expect, it } from 'vitest';

const isOdd = (value: number) => value % 2 !== 0;

describe('toSatisfy()', () => {
  it('pass with 0', () => {
    expect(1).toSatisfy(isOdd);
  });

  it('pass with negation', () => {
    expect(2).not.toSatisfy(isOdd);
  });
});

resolves

• Tipo: Promisify<Assertions>

resolves está destinado a eliminar el código repetitivo al afirmar código asíncrono. Úselo para extraer el valor de la promesa pendiente y afirmar su valor con las aserciones habituales. Si la promesa se rechaza, la aserción fallará.

Devuelve el mismo objeto Assertions, pero todos los matchers ahora devuelven Promise, por lo que necesitaría awaitarlo. También funciona con las aserciones de chai.

Por ejemplo, si tiene una función que realiza una llamada a la API y devuelve algunos datos, puede usar este código para afirmar su valor de retorno:

import { expect, test } from 'vitest';

async function buyApples() {
  return fetch('/buy/apples').then(r => r.json());
}

test('buyApples returns new stock id', async () => {
  // toEqual ahora devuelve una promesa, por lo que DEBE esperarla
  await expect(buyApples()).resolves.toEqual({ id: 1 }); // API de jest
  await expect(buyApples()).resolves.to.equal({ id: 1 }); // API de chai
});

WARNING

Si la aserción no se espera, entonces tendrá una prueba de falso positivo que siempre pasará. Para asegurarse de que las aserciones se llamen realmente, puede usar expect.assertions(number).

Desde Vitest 3, si un método no se espera, Vitest mostrará una advertencia al final de la prueba. En Vitest 4, la prueba se marcará como "fallida" si la aserción no se espera.

rejects

• Tipo: Promisify<Assertions>

rejects está destinado a eliminar el código repetitivo al afirmar código asíncrono. Úselo para extraer la razón por la que la promesa fue rechazada y afirmar su valor con las aserciones habituales. Si la promesa se resuelve con éxito, la aserción fallará.

Devuelve el mismo objeto Assertions, pero todos los matchers ahora devuelven Promise, por lo que necesitaría awaitarlo. También funciona con las aserciones de chai.

Por ejemplo, si tiene una función que falla cuando la llama, puede usar este código para afirmar la razón:

import { expect, test } from 'vitest';

async function buyApples(id) {
  if (!id) {
    throw new Error('no id');
  }
}

test('buyApples throws an error when no id provided', async () => {
  // toThrow ahora devuelve una promesa, por lo que DEBE esperarla
  await expect(buyApples()).rejects.toThrow('no id');
});

WARNING

Si la aserción no se espera, entonces tendrá una prueba de falso positivo que siempre pasará. Para asegurarse de que las aserciones se llamaron realmente, puede usar expect.assertions(number).

Desde Vitest 3, si un método no se espera, Vitest mostrará una advertencia al final de la prueba. En Vitest 4, la prueba se marcará como "fallida" si la aserción no se espera.

expect.assertions

• Tipo: (count: number) => void

Después de que la prueba haya pasado o fallado, verifique que se haya llamado a un cierto número de aserciones durante una prueba. Es útil para verificar si se llamó a un código asíncrono.

Por ejemplo, si tenemos una función que llama asincrónicamente a dos matchers, podemos afirmar que realmente se llamaron.

import { expect, test } from 'vitest';

async function doAsync(...cbs) {
  await Promise.all(cbs.map((cb, index) => cb({ index })));
}

test('all assertions are called', async () => {
  expect.assertions(2);
  function callback1(data) {
    expect(data).toBeTruthy();
  }
  function callback2(data) {
    expect(data).toBeTruthy();
  }

  await doAsync(callback1, callback2);
});

WARNING

Al usar assertions con pruebas asíncronas concurrentes, se debe usar expect del Contexto de prueba local para garantizar que la prueba correcta sea detectada.

expect.hasAssertions

• Tipo: () => void

Después de que la prueba haya pasado o fallado, verifique que se haya llamado al menos a una aserción durante una prueba. Es útil para verificar si se llamó a un código asíncrono.

Por ejemplo, si tiene un código que llama a una devolución de llamada, podemos incluir una aserción dentro de una devolución de llamada, pero la prueba siempre pasará si no verificamos si se llamó a una aserción.

import { expect, test } from 'vitest';
import { db } from './db.js';

const cbs = [];

function onSelect(cb) {
  cbs.push(cb);
}

// después de seleccionar de la base de datos, llamamos a todas las devoluciones de llamada
function select(id) {
  return db.select({ id }).then(data => {
    return Promise.all(cbs.map(cb => cb(data)));
  });
}

test('callback was called', async () => {
  expect.hasAssertions();
  onSelect(data => {
    // debería llamarse al seleccionar
    expect(data).toBeTruthy();
  });
  // si no se espera, la prueba fallará
  // si no tiene expect.hasAssertions(), la prueba pasará
  await select(3);
});

expect.unreachable

• Tipo: (message?: string) => never

Este método se utiliza para afirmar que una línea de código nunca debería ser ejecutada.

Por ejemplo, si queremos probar que build() lanza un error porque los directorios de destino no contienen una carpeta src, y también manejar cada error por separado, podríamos hacer esto:

import { expect, test } from 'vitest';

async function build(dir) {
  if (dir.includes('no-src')) {
    throw new Error(`${dir}/src does not exist`);
  }
}

const errorDirs = [
  'no-src-folder',
  // ...
];

test.each(errorDirs)('build fails with "%s"', async dir => {
  try {
    await build(dir);
    expect.unreachable('Should not pass build');
  } catch (err: any) {
    expect(err).toBeInstanceOf(Error);
    expect(err.stack).toContain('build');

    switch (dir) {
      case 'no-src-folder':
        expect(err.message).toBe(`${dir}/src does not exist`);
        break;
      default:
        // para agotar todas las pruebas de error
        expect.unreachable('All error test must be handled');
        break;
    }
  }
});

expect.anything

• Tipo: () => any

Este matcher asimétrico, cuando se usa con una verificación de igualdad, siempre devolverá true. Útil, si solo quiere asegurarse de que la propiedad exista.

import { expect, test } from 'vitest';

test('object has "apples" key', () => {
  expect({ apples: 22 }).toEqual({ apples: expect.anything() });
});

expect.any

• Tipo: (constructor: unknown) => any

Este matcher asimétrico, cuando se usa con una verificación de igualdad, devolverá true solo si el valor es una instancia de un constructor especificado. Útil, si tiene un valor que se genera cada vez, y solo quiere saber que tiene el tipo correcto.

import { expect, test } from 'vitest';
import { generateId } from './generators.js';

test('"id" is a number', () => {
  expect({ id: generateId() }).toEqual({ id: expect.any(Number) });
});

expect.closeTo

• Tipo: (expected: any, precision?: number) => any

expect.closeTo es útil al comparar números de punto flotante en propiedades de objetos o en elementos de arrays. Si necesita comparar un número, use .toBeCloseTo en su lugar.

El argumento opcional precision limita el número de dígitos a verificar después del punto decimal. Para el valor predeterminado 2, el criterio de comparación es Math.abs(expected - received) < 0.005 (es decir, 10 ** -2 / 2).

Por ejemplo, esta prueba pasa con una precisión de 5 dígitos:

test('compare float in object properties', () => {
  expect({
    title: '0.1 + 0.2',
    sum: 0.1 + 0.2,
  }).toEqual({
    title: '0.1 + 0.2',
    sum: expect.closeTo(0.3, 5),
  });
});

expect.arrayContaining

• Tipo: <T>(expected: T[]) => any

Cuando se usa con una verificación de igualdad, este matcher asimétrico devolverá true si el valor es un array y contiene los elementos indicados.

import { expect, test } from 'vitest';

test('basket includes fuji', () => {
  const basket = {
    varieties: ['Empire', 'Fuji', 'Gala'],
    count: 3,
  };
  expect(basket).toEqual({
    count: 3,
    varieties: expect.arrayContaining(['Fuji']),
  });
});

TIP

Puede usar expect.not con este matcher para negar el valor esperado.

expect.objectContaining

• Tipo: (expected: any) => any

Cuando se usa con una verificación de igualdad, este matcher asimétrico devolverá true si el valor tiene una estructura similar.

import { expect, test } from 'vitest';

test('basket has empire apples', () => {
  const basket = {
    varieties: [
      {
        name: 'Empire',
        count: 1,
      },
    ],
  };
  expect(basket).toEqual({
    varieties: [expect.objectContaining({ name: 'Empire' })],
  });
});

TIP

Puede usar expect.not con este matcher para negar el valor esperado.

expect.stringContaining

• Tipo: (expected: any) => any

Cuando se usa con una verificación de igualdad, este matcher asimétrico devolverá true si el valor es una cadena y contiene una subcadena específica.

import { expect, test } from 'vitest';

test('variety has "Emp" in its name', () => {
  const variety = {
    name: 'Empire',
    count: 1,
  };
  expect(variety).toEqual({
    name: expect.stringContaining('Emp'),
    count: 1,
  });
});

TIP

Puede usar expect.not con este matcher para negar el valor esperado.

expect.stringMatching

• Tipo: (expected: any) => any

Cuando se usa con una verificación de igualdad, este matcher asimétrico devolverá true si el valor es una cadena y contiene una subcadena específica o si la cadena coincide con una expresión regular.

import { expect, test } from 'vitest';

test('variety ends with "re"', () => {
  const variety = {
    name: 'Empire',
    count: 1,
  };
  expect(variety).toEqual({
    name: expect.stringMatching(/re$/),
    count: 1,
  });
});

TIP

Puede usar expect.not con este matcher para negar el valor esperado.

expect.addSnapshotSerializer

• Tipo: (plugin: PrettyFormatPlugin) => void

Este método agrega serializadores personalizados que se utilizan al crear una instantánea. Esta es una característica avanzada; si desea saber más, lea una guía sobre serializadores personalizados.

Si está agregando serializadores personalizados, debe llamar a este método dentro de setupFiles. Esto se aplicará a cada instantánea.

TIP

Si anteriormente usaba Vue CLI con Jest, es posible que desee instalar jest-serializer-vue. De lo contrario, sus instantáneas se envolverán en una cadena, lo que provocará que el carácter " se escape.

expect.extend

• Tipo: (matchers: MatchersObject) => void

Puede extender los matchers predeterminados con sus propios matchers. Esta función se utiliza para extender el objeto de matchers con matchers personalizados.

Cuando define matchers de este modo, también crea matchers asimétricos que se pueden usar como expect.stringContaining.

import { expect, test } from 'vitest';

test('custom matchers', () => {
  expect.extend({
    toBeFoo: (received, expected) => {
      if (received !== 'foo') {
        return {
          message: () => `expected ${received} to be foo`,
          pass: false,
        };
      }
    },
  });

  expect('foo').toBeFoo();
  expect({ foo: 'foo' }).toEqual({ foo: expect.toBeFoo() });
});

TIP

Si desea que sus matchers estén disponibles en cada prueba, debe llamar a este método dentro de setupFiles.

Esta función es compatible con expect.extend de Jest, por lo que cualquier biblioteca que la utilice para crear matchers personalizados funcionará con Vitest.

Si está utilizando TypeScript, desde Vitest 0.31.0 puede extender la interfaz Assertion predeterminada en un archivo de declaración de tipos (por ejemplo: vitest.d.ts) con el siguiente código:

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R;
}

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

WARNING

No olvide incluir el archivo de declaración de tipos en su tsconfig.json.

TIP

Si desea saber más, consulte la guía sobre la extensión de matchers.

expect.addEqualityTesters

• Tipo: (tester: Array<Tester>) => void

Puede usar este método para definir comparadores personalizados, que son métodos utilizados por los matchers, para probar si dos objetos son iguales. Es compatible con expect.addEqualityTesters de Jest.

import { expect, test } from 'vitest';

class AnagramComparator {
  public word: string;

  constructor(word: string) {
    this.word = word;
  }

  equals(other: AnagramComparator): boolean {
    const cleanStr1 = this.word.replace(/ /g, '').toLowerCase();
    const cleanStr2 = other.word.replace(/ /g, '').toLowerCase();

    const sortedStr1 = cleanStr1.split('').sort().join('');
    const sortedStr2 = cleanStr2.split('').sort().join('');

    return sortedStr1 === sortedStr2;
  }
}

function isAnagramComparator(a: unknown): a is AnagramComparator {
  return a instanceof AnagramComparator;
}

function areAnagramsEqual(a: unknown, b: unknown): boolean | undefined {
  const isAAnagramComparator = isAnagramComparator(a);
  const isBAnagramComparator = isAnagramComparator(b);

  if (isAAnagramComparator && isBAnagramComparator) {
    return a.equals(b);
  } else if (isAAnagramComparator === isBAnagramComparator) {
    return undefined;
  } else {
    return false;
  }
}

expect.addEqualityTesters([areAnagramsEqual]);

test('custom equality tester', () => {
  expect(new AnagramComparator('listen')).toEqual(
    new AnagramComparator('silent')
  );
});