Referencia de la API de pruebas
Los siguientes tipos se utilizan en las firmas de tipo que se muestran a continuación:
type Awaitable<T> = T | PromiseLike<T>;
type TestFunction = () => Awaitable<void>;
interface TestOptions {
/**
* La prueba fallará si tarda demasiado en ejecutarse.
*/
timeout?: number;
/**
* Reintentará la prueba un número determinado de veces si falla.
*
* @default 0
*/
retry?: number;
/**
* Repetirá la misma prueba varias veces, incluso si falla en cada intento.
* Si se establece la opción "retry" y la prueba falla, se utilizará cada reintento en cada ciclo.
* Es útil para depurar fallos aleatorios.
*
* @default 0
*/
repeats?: number;
}Cuando una función de prueba devuelve una promesa, el ejecutor esperará a que se resuelva para recopilar las expectativas asíncronas. Si la promesa se rechaza, la prueba fallará.
TIP
En Jest, TestFunction también puede ser del tipo (done: DoneCallback) => void. Si se utiliza esta forma, la prueba no se concluirá hasta que se llame a done. Puede lograr lo mismo usando una función async, consulte la sección Guía de migración Done Callback.
test
Tipo:
(name: string | Function, fn: TestFunction, timeout?: number | TestOptions) => voidAlias:
ittestdefine un caso de prueba con un conjunto de expectativas relacionadas. Recibe el nombre de la prueba y una función que contiene las aserciones a probar.Opcionalmente, puede especificar un tiempo de espera (en milisegundos) para indicar cuánto tiempo esperar antes de que la prueba finalice por timeout. El valor predeterminado es de 5 segundos y se puede configurar globalmente con testTimeout.
tsimport { expect, test } from 'vitest'; test('should work as expected', () => { expect(Math.sqrt(4)).toBe(2); });
test.extend
Tipo:
<T extends Record<string, any>>(fixtures: Fixtures<T>): TestAPI<ExtraContext & T>Alias:
it.extendVersión: Vitest 0.32.3
Use
test.extendpara extender el contexto de la prueba con fixtures personalizadas. Esto devuelve un nuevotestque también es extensible, lo que permite componer más fixtures o sobrescribir las existentes según sea necesario. Consulte Extender el contexto de la prueba para obtener más información.tsimport { expect, test } from 'vitest'; const todos = []; const archive = []; const myTest = test.extend({ todos: async ({ task }, use) => { todos.push(1, 2, 3); await use(todos); todos.length = 0; }, archive, }); myTest('add item', ({ todos }) => { expect(todos.length).toBe(3); todos.push(4); expect(todos.length).toBe(4); });
test.skip
Tipo:
(name: string | Function, fn: TestFunction, timeout?: number | TestOptions) => voidAlias:
it.skipSi desea omitir la ejecución de ciertas pruebas, pero no quiere eliminar el código, puede usar
test.skippara evitar que se ejecuten.tsimport { assert, test } from 'vitest'; test.skip('skipped test', () => { // Prueba omitida, sin errores assert.equal(Math.sqrt(4), 3); });También puede omitir la prueba llamando a
skipen su contexto dinámicamente:tsimport { assert, test } from 'vitest'; test('skipped test', context => { context.skip(); // Prueba omitida, sin errores assert.equal(Math.sqrt(4), 3); });
test.skipIf
Tipo:
(condition: any) => TestAlias:
it.skipIfEn algunos casos, puede que necesite ejecutar pruebas varias veces en diferentes entornos, y algunas de ellas ser específicas de un entorno. En lugar de usar una sentencia
ifpara controlar la ejecución, puede usartest.skipIfpara omitir la prueba si la condición se cumple.tsimport { assert, test } from 'vitest'; const isDev = process.env.NODE_ENV === 'development'; test.skipIf(isDev)('prod only test', () => { // esta prueba solo se ejecuta en producción });
WARNING
No puede utilizar esta sintaxis cuando utilice Vitest como verificador de tipos.
test.runIf
Tipo:
(condition: any) => TestAlias:
it.runIfEs el opuesto a test.skipIf.
tsimport { assert, test } from 'vitest'; const isDev = process.env.NODE_ENV === 'development'; test.runIf(isDev)('dev only test', () => { // esta prueba solo se ejecuta en desarrollo });
WARNING
No puede utilizar esta sintaxis cuando utilice Vitest como verificador de tipos.
test.only
Tipo:
(name: string | Function, fn: TestFunction, timeout?: number) => voidAlias:
it.onlyUse
test.onlypara ejecutar únicamente ciertas pruebas dentro de un conjunto. Esto es útil para la depuración.Opcionalmente, puede especificar un tiempo de espera (en milisegundos) para indicar cuánto tiempo esperar antes de que la prueba finalice por timeout. El valor predeterminado es de 5 segundos y se puede configurar globalmente con testTimeout.
tsimport { assert, test } from 'vitest'; test.only('test', () => { // Solo se ejecutan esta prueba (y otras marcadas con only) assert.equal(Math.sqrt(4), 2); });A veces, es muy útil ejecutar pruebas
onlyen un determinado archivo, ignorando todas las demás pruebas del conjunto, que contaminan la salida.Para hacer eso, ejecute
vitestcon el archivo específico que contiene las pruebas en cuestión.# vitest interesting.test.ts
test.concurrent
Tipo:
(name: string | Function, fn: TestFunction, timeout?: number) => voidAlias:
it.concurrenttest.concurrentmarca las pruebas para que se ejecuten en paralelo. Recibe el nombre de la prueba, una función asíncrona con las aserciones a probar y un tiempo de espera opcional (en milisegundos).tsimport { describe, test } from 'vitest'; // Las dos pruebas marcadas con concurrent se ejecutarán en paralelo describe('suite', () => { test('serial test', async () => { /* ... */ }); test.concurrent('concurrent test 1', async () => { /* ... */ }); test.concurrent('concurrent test 2', async () => { /* ... */ }); });test.skip,test.onlyytest.todofuncionan con pruebas concurrentes. Todas las siguientes combinaciones son válidas:tstest.concurrent(/* ... */); test.skip.concurrent(/* ... */); // or test.concurrent.skip(/* ... */) test.only.concurrent(/* ... */); // or test.concurrent.only(/* ... */) test.todo.concurrent(/* ... */); // or test.concurrent.todo(/* ... */)Cuando se ejecutan pruebas concurrentes, las instantáneas y las aserciones deben usar
expectdel Contexto de prueba local para asegurar que se detecte la prueba correcta.tstest.concurrent('test 1', async ({ expect }) => { expect(foo).toMatchSnapshot(); }); test.concurrent('test 2', async ({ expect }) => { expect(foo).toMatchSnapshot(); });
WARNING
No puede utilizar esta sintaxis cuando utilice Vitest como verificador de tipos.
test.todo
Tipo:
(name: string | Function) => voidAlias:
it.todoUse
test.todopara crear stubs de pruebas que se implementarán en el futuro. Se mostrará una entrada en el informe para indicar que la prueba está pendiente de implementación.ts// Se mostrará una entrada en el informe para esta prueba test.todo('unimplemented test');
test.fails
Tipo:
(name: string | Function, fn: TestFunction, timeout?: number) => voidAlias:
it.failsUse
test.failspara indicar que una aserción fallará de manera explícita.tsimport { expect, test } from 'vitest'; function myAsyncFunc() { return new Promise(resolve => resolve(1)); } test.fails('fail test', async () => { await expect(myAsyncFunc()).rejects.toBe(1); });
WARNING
No puede utilizar esta sintaxis cuando utilice Vitest como verificador de tipos.
test.each
Tipo:
(cases: ReadonlyArray<T>, ...args: any[]) => voidAlias:
it.eachUse
test.eachcuando necesite ejecutar la misma prueba con diferentes variables. Puede inyectar parámetros utilizando formato printf en el nombre de la prueba, en el orden de los parámetros de la función de prueba.%s: string%d: number%i: integer%f: floating point value%j: json%o: object%#: índice del caso de prueba%%: signo de porcentaje único ('%')
tstest.each([ [1, 1, 2], [1, 2, 3], [2, 1, 3], ])('add(%i, %i) -> %i', (a, b, expected) => { expect(a + b).toBe(expected); }); // this will return // ✓ add(1, 1) -> 2 // ✓ add(1, 2) -> 3 // ✓ add(2, 1) -> 3También puede acceder a las propiedades del objeto con el prefijo
$, si está utilizando objetos como argumentos:tstest.each([ { a: 1, b: 1, expected: 2 }, { a: 1, b: 2, expected: 3 }, { a: 2, b: 1, expected: 3 }, ])('add($a, $b) -> $expected', ({ a, b, expected }) => { expect(a + b).toBe(expected); }); // this will return // ✓ add(1, 1) -> 2 // ✓ add(1, 2) -> 3 // ✓ add(2, 1) -> 3También puede acceder a los atributos del objeto con
., si está utilizando objetos como argumentos:tstest.each` a | b | expected ${{ val: 1 }} | ${'b'} | ${'1b'} ${{ val: 2 }} | ${'b'} | ${'2b'} ${{ val: 3 }} | ${'b'} | ${'3b'} `('add($a.val, $b) -> $expected', ({ a, b, expected }) => { expect(a.val + b).toBe(expected); }); // this will return // ✓ add(1, b) -> 1b // ✓ add(2, b) -> 2b // ✓ add(3, b) -> 3bA partir de Vitest 0.25.3, también puede utilizar la tabla de cadenas de plantilla.
- La primera fila debe ser los nombres de las columnas, separados por
|; - Una o más filas subsiguientes de datos suministrados como expresiones literales de plantilla utilizando la sintaxis
${value}.
tstest.each` a | b | expected ${1} | ${1} | ${2} ${'a'} | ${'b'} | ${'ab'} ${[]} | ${'b'} | ${'b'} ${{}} | ${'b'} | ${'[object Object]b'} ${{ asd: 1 }} | ${'b'} | ${'[object Object]b'} `('returns $expected when $a is added $b', ({ a, b, expected }) => { expect(a + b).toBe(expected); });Si desea tener acceso a
TestContext, utilicedescribe.eachcon una sola prueba.
TIP
Vitest procesa $values con el método format de chai. Si el valor está demasiado truncado, puede aumentar chaiConfig.truncateThreshold en su archivo de configuración.
WARNING
No puede utilizar esta sintaxis cuando utilice Vitest como verificador de tipos.
bench
- Tipo:
(name: string | Function, fn: BenchFunction, options?: BenchOptions) => void
bench define un benchmark o prueba de rendimiento. En términos de Vitest, un benchmark es una función que define una serie de operaciones. Vitest ejecuta esta función varias veces para mostrar diferentes resultados de rendimiento.
Vitest utiliza la biblioteca tinybench por debajo, heredando todas sus opciones que se pueden utilizar como un tercer argumento.
import { bench } from 'vitest';
bench(
'normal sorting',
() => {
const x = [1, 5, 4, 2, 3];
x.sort((a, b) => {
return a - b;
});
},
{ time: 1000 }
);export interface Options {
/**
* Tiempo necesario para ejecutar una tarea de benchmark (milisegundos).
* @default 500
*/
time?: number;
/**
* Número de veces que una tarea debe ejecutarse incluso si la opción de tiempo ha finalizado.
* @default 10
*/
iterations?: number;
/**
* Función para obtener la marca de tiempo actual en milisegundos.
*/
now?: () => number;
/**
* Un AbortSignal para abortar el benchmark.
*/
signal?: AbortSignal;
/**
* Tiempo de calentamiento (milisegundos).
* @default 100ms
*/
warmupTime?: number;
/**
* Iteraciones de calentamiento.
* @default 5
*/
warmupIterations?: number;
/**
* Función de configuración que se ejecuta antes de cada tarea de benchmark (ciclo).
*/
setup?: Hook;
/**
* Función de desmontaje que se ejecuta después de cada tarea de benchmark (ciclo).
*/
teardown?: Hook;
}bench.skip
- Tipo:
(name: string | Function, fn: BenchFunction, options?: BenchOptions) => void
Puede usar la sintaxis bench.skip para omitir la ejecución de ciertos benchmarks.
import { bench } from 'vitest';
bench.skip('normal sorting', () => {
const x = [1, 5, 4, 2, 3];
x.sort((a, b) => {
return a - b;
});
});bench.only
- Tipo:
(name: string | Function, fn: BenchFunction, options?: BenchOptions) => void
Use bench.only para ejecutar únicamente ciertos benchmarks en un conjunto dado. Esto es útil para la depuración.
import { bench } from 'vitest';
bench.only('normal sorting', () => {
const x = [1, 5, 4, 2, 3];
x.sort((a, b) => {
return a - b;
});
});bench.todo
- Tipo:
(name: string | Function) => void
Use bench.todo para crear stubs de benchmarks que se implementarán posteriormente.
import { bench } from 'vitest';
bench.todo('unimplemented test');describe
Cuando usas test o bench en el nivel superior de un archivo, se recopilan como parte de la suite implícita del archivo. Usando describe puedes definir una nueva suite en el contexto actual, como un conjunto de pruebas o puntos de referencia relacionados, y otras suites anidadas. Una suite te permite organizar tus pruebas y puntos de referencia para que los informes sean más claros.
// basic.spec.ts
// organizando pruebas
import { describe, expect, test } from 'vitest';
const person = {
isActive: true,
age: 32,
};
describe('person', () => {
test('person is defined', () => {
expect(person).toBeDefined();
});
test('is active', () => {
expect(person.isActive).toBe(true);
});
test('age limit', () => {
expect(person.age).toBeLessThanOrEqual(32);
});
});// basic.bench.ts
// organizando benchmarks
import { bench, describe } from 'vitest';
describe('sort', () => {
bench('normal', () => {
const x = [1, 5, 4, 2, 3];
x.sort((a, b) => {
return a - b;
});
});
bench('reverse', () => {
const x = [1, 5, 4, 2, 3];
x.reverse().sort((a, b) => {
return a - b;
});
});
});También puedes anidar bloques describe si tienes una jerarquía de pruebas o puntos de referencia:
import { describe, expect, test } from 'vitest';
function numberToCurrency(value) {
if (typeof value !== 'number') throw new Error('Value must be a number');
return value
.toFixed(2)
.toString()
.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
}
describe('numberToCurrency', () => {
describe('given an invalid number', () => {
test('debe lanzar un error si no es un número', () => {
expect(() => numberToCurrency('abc')).toThrowError();
});
});
describe('given a valid number', () => {
test('devuelve el formato de moneda correcto', () => {
expect(numberToCurrency(10000)).toBe('10,000.00');
});
});
});describe.skip
Tipo:
(name: string | Function, fn: TestFunction, options?: number | TestOptions) => voidUsa
describe.skipen una suite para evitar la ejecución de un bloquedescribeen particular.tsimport { assert, describe, test } from 'vitest'; describe.skip('suite omitida', () => { test('sqrt', () => { // Suite skipped, no error assert.equal(Math.sqrt(4), 3); }); });
describe.skipIf
Tipo:
(condition: any) => voidEn algunos casos, podrías ejecutar suites múltiples veces con diferentes entornos, y algunas de las suites podrían ser específicas de un entorno. En lugar de envolver la suite con
if, puedes usardescribe.skipIfpara omitir la suite siempre que la condición sea verdadera.tsimport { describe, test } from 'vitest'; const isDev = process.env.NODE_ENV === 'development'; describe.skipIf(isDev)('prueba solo en producción', () => { // this test only runs in production });
WARNING
No puedes usar esta sintaxis cuando uses Vitest como verificador de tipos.
describe.only
Tipo:
(name: string | Function, fn: TestFunction, options?: number | TestOptions) => voidUsa
describe.onlypara ejecutar solo ciertas suites.ts// Only this suite (and others marked with only) are run describe.only('conjunto', () => { test('sqrt', () => { assert.equal(Math.sqrt(4), 3); }); }); describe('other suite', () => { // ... will be skipped });A veces es útil ejecutar pruebas
onlyen un archivo específico, ignorando todas las demás pruebas del conjunto de pruebas, que podrían contaminar la salida.Para hacer eso, ejecuta
vitestcon el archivo específico que contiene las pruebas en cuestión.# vitest interesting.test.ts
describe.concurrent
Tipo:
(name: string | Function, fn: TestFunction, options?: number | TestOptions) => voiddescribe.concurrenten una suite marca cada prueba dentro de ella como concurrente.ts// All tests within this suite will be run in parallel describe.concurrent('conjunto', () => { test('concurrent test 1', async () => { /* ... */ }); test('concurrent test 2', async () => { /* ... */ }); test.concurrent('concurrent test 3', async () => { /* ... */ }); });.skip,.onlyy.todofuncionan con suites concurrentes. Todas las siguientes combinaciones son válidas:tsdescribe.concurrent(/* ... */); describe.skip.concurrent(/* ... */); // or describe.concurrent.skip(/* ... */) describe.only.concurrent(/* ... */); // or describe.concurrent.only(/* ... */) describe.todo.concurrent(/* ... */); // or describe.concurrent.todo(/* ... */)
Cuando se ejecutan pruebas concurrentes, las Instantáneas (Snapshots) y las Aserciones (Assertions) deben usar expect del Contexto de Prueba local para asegurar que se detecte la prueba correcta.
describe.concurrent('suite', () => {
test('concurrent test 1', async ({ expect }) => {
expect(foo).toMatchSnapshot();
});
test('concurrent test 2', async ({ expect }) => {
expect(foo).toMatchSnapshot();
});
});WARNING
No puedes usar esta sintaxis cuando uses Vitest como verificador de tipos.
describe.sequential
Tipo:
(name: string | Function, fn: TestFunction, options?: number | TestOptions) => voiddescribe.sequentialen una suite marca cada prueba dentro de ella como secuencial. Esto es útil si quieres ejecutar pruebas en secuencia dentro dedescribe.concurrento con la opción de comando--sequence.concurrent.tsdescribe.concurrent('suite', () => { test('concurrent test 1', async () => { /* ... */ }); test('concurrent test 2', async () => { /* ... */ }); describe.sequential('secuencial', () => { test('sequential test 1', async () => { /* ... */ }); test('sequential test 2', async () => { /* ... */ }); }); });
describe.shuffle
Tipo:
(name: string | Function, fn: TestFunction, options?: number | TestOptions) => voidVitest proporciona una forma de ejecutar todas las pruebas en orden aleatorio a través del flag de la CLI
--sequence.shuffleo la opción de configuraciónsequence.shuffle, pero si quieres que solo una parte de tu suite ejecute las pruebas en orden aleatorio, puedes marcarla con este flag.tsdescribe.shuffle('conjunto', () => { test('random test 1', async () => { /* ... */ }); test('random test 2', async () => { /* ... */ }); test('random test 3', async () => { /* ... */ }); }); // order depends on sequence.seed option in config (Date.now() by default)
.skip, .only y .todo funcionan con suites aleatorias.
WARNING
No puedes usar esta sintaxis cuando uses Vitest como verificador de tipos.
describe.todo
Tipo:
(name: string | Function) => voidUsa
describe.todopara crear stubs de suites que se implementarán más tarde. Se mostrará una entrada en el informe para esta suite, indicando la cantidad de pruebas que aún deben implementarse.ts// An entry will be shown in the report for this suite describe.todo('conjunto no implementado');
describe.each
Tipo:
(cases: ReadonlyArray<T>, ...args: any[]): (name: string | Function, fn: (...args: T[]) => void, options?: number | TestOptions) => voidUsa
describe.eachsi tienes más de una prueba que depende de los mismos datos.tsdescribe.each([ { a: 1, b: 1, expected: 2 }, { a: 1, b: 2, expected: 3 }, { a: 2, b: 1, expected: 3 }, ])('describe object add($a, $b)', ({ a, b, expected }) => { test(`returns ${expected}`, () => { expect(a + b).toBe(expected); }); test(`el valor devuelto no debe ser mayor que ${expected}`, () => { expect(a + b).not.toBeGreaterThan(expected); }); test(`el valor devuelto no debe ser menor que ${expected}`, () => { expect(a + b).not.toBeLessThan(expected); }); });A partir de Vitest 0.25.3, también puedes usar una tabla de cadenas de plantilla.
- La primera fila debe ser los nombres de las columnas, separados por
|; - Una o más filas subsiguientes de datos suministrados como expresiones literales de plantilla usando la sintaxis
${value}.
tsdescribe.each` a | b | expected ${1} | ${1} | ${2} ${'a'} | ${'b'} | ${'ab'} ${[]} | ${'b'} | ${'b'} ${{}} | ${'b'} | ${'[object Object]b'} ${{ asd: 1 }} | ${'b'} | ${'[object Object]b'} `('describe template string add($a, $b)', ({ a, b, expected }) => { test(`returns ${expected}`, () => { expect(a + b).toBe(expected); }); });- La primera fila debe ser los nombres de las columnas, separados por
WARNING
No puedes usar esta sintaxis cuando uses Vitest como verificador de tipos.
Configuración (Setup) y Desmontaje (Teardown)
Estas funciones te permiten engancharte al ciclo de vida de las pruebas para evitar repetir el código de configuración y desmontaje. Se aplican al contexto actual: el archivo si se usan en el nivel superior, o la suite actual si están dentro de un bloque describe. Estos hooks no se ejecutan cuando estás usando Vitest como un verificador de tipos.
beforeEach
Tipo:
beforeEach(fn: () => Awaitable<void>, timeout?: number)Registra una función callback que se llamará antes de la ejecución de cada prueba en el contexto actual. Si la función devuelve una promesa, Vitest esperará a que se resuelva antes de ejecutar la prueba.
Opcionalmente, puedes pasar un tiempo de espera máximo (en milisegundos) que define cuánto tiempo esperar antes de terminar. El valor predeterminado es 5 segundos.
tsimport { beforeEach } from 'vitest'; beforeEach(async () => { // Clear mocks and add some testing data after before each test run await stopMocking(); await addUser({ name: 'John' }); });Aquí, el
beforeEachasegura que el usuario se agregue para cada prueba.A partir de Vitest v0.10.0,
beforeEachtambién acepta una función de limpieza opcional (cleanup), que es equivalente aafterEach.tsimport { beforeEach } from 'vitest'; beforeEach(async () => { // Se llama una vez antes de cada ejecución de prueba await prepareSomething(); // Función de limpieza, se llama una vez después de cada ejecución de prueba return async () => { await resetSomething(); }; });
afterEach
Tipo:
afterEach(fn: () => Awaitable<void>, timeout?: number)Registra una función callback que se llamará después de que se complete cada prueba en el contexto actual. Si la función devuelve una promesa, Vitest esperará a que se resuelva antes de continuar.
Opcionalmente, puedes proporcionar un tiempo de espera máximo (en milisegundos) para especificar cuánto tiempo esperar antes de terminar. El valor predeterminado es 5 segundos.
tsimport { afterEach } from 'vitest'; afterEach(async () => { await clearTestingData(); // clear testing data after each test run });Aquí, el
afterEachasegura que los datos de prueba se limpien después de que se ejecute cada prueba.
beforeAll
Tipo:
beforeAll(fn: () => Awaitable<void>, timeout?: number)Registra una función callback que se llamará una vez antes de que comiencen a ejecutarse todas las pruebas en el contexto actual. Si la función devuelve una promesa, Vitest esperará a que se resuelva antes de ejecutar las pruebas.
Opcionalmente, puedes proporcionar un tiempo de espera máximo (en milisegundos) para especificar cuánto tiempo esperar antes de terminar. El valor predeterminado es 5 segundos.
tsimport { beforeAll } from 'vitest'; beforeAll(async () => { await startMocking(); // called once before all tests run });Aquí, el
beforeAllasegura que los datos mock se configuren antes de que se ejecuten las pruebas.A partir de Vitest v0.10.0,
beforeAlltambién acepta una función de limpieza opcional (cleanup), que es equivalente aafterAll.tsimport { beforeAll } from 'vitest'; beforeAll(async () => { // Se llama una vez antes de que se ejecuten todas las pruebas await startMocking(); // Función de limpieza, se llama una vez después de que se ejecuten todas las pruebas return async () => { await stopMocking(); }; });
afterAll
Tipo:
afterAll(fn: () => Awaitable<void>, timeout?: number)Registra una función callback que se llamará una vez después de que se hayan ejecutado todas las pruebas en el contexto actual. Si la función devuelve una promesa, Vitest esperará a que se resuelva antes de continuar.
Opcionalmente, puedes proporcionar un tiempo de espera máximo (en milisegundos) para especificar cuánto tiempo esperar antes de terminar. El valor predeterminado es 5 segundos.
tsimport { afterAll } from 'vitest'; afterAll(async () => { await stopMocking(); // this method is called after all tests run });Aquí, el
afterAllasegura que el métodostopMockingse llame después de que se ejecuten todas las pruebas.