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

Vitest 1.3.0 ha dejado de recomendar el uso de opciones como el último parámetro. Verá un mensaje de advertencia hasta la versión 2.0.0, cuando se eliminará esta sintaxis. Si necesita pasar opciones, use el segundo argumento de la función test.

import { test } from 'vitest';

test('flaky test', () => {}, { retry: 3 }); 
test('flaky test', { retry: 3 }, () => {});

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.

Desde Vitest 1.3.0, la mayoría de las opciones admiten tanto la sintaxis de punto como la sintaxis de objeto, lo que le permite utilizar el estilo que prefiera.

dot-syntaxobject-syntax 1.3.0+

import { test } from 'vitest';

test.skip('skipped test', () => {
  // some logic that fails right now
});

import { test } from 'vitest';

test('skipped test', { skip: true }, () => {
  // some logic that fails right now
});

test

Alias: it

test define 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.

import { expect, test } from 'vitest';

test('should work as expected', () => {
  expect(Math.sqrt(4)).toBe(2);
});

test.extend 0.32.3+

Alias: it.extend

Use test.extend para extender el contexto de la prueba con fixtures personalizadas. Esto devuelve un nuevo test que 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.

import { 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

Alias: it.skip

Si desea omitir la ejecución de ciertas pruebas, pero no quiere eliminar el código, puede usar test.skip para evitar que se ejecuten.

import { 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 skip en su contexto dinámicamente:

import { assert, test } from 'vitest';

test('skipped test', context => {
  context.skip();
  // Prueba omitida, sin errores
  assert.equal(Math.sqrt(4), 3);
});

test.skipIf

Alias: it.skipIf

En 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 if para controlar la ejecución, puede usar test.skipIf para omitir la prueba si la condición se cumple.

import { 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

Alias: it.runIf

Es el opuesto a test.skipIf.

import { 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

Alias: it.only

Use test.only para ejecutar únicamente ciertas pruebas dentro de un conjunto. Esto es útil para la depuración.

import { 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 only en un determinado archivo, ignorando todas las demás pruebas del conjunto, que contaminan la salida.

Para hacer eso, ejecute vitest con el archivo específico que contiene las pruebas en cuestión.

# vitest interesting.test.ts

test.concurrent

Alias: it.concurrent

test.concurrent marca 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).

import { 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.only y test.todo funcionan con pruebas concurrentes. Todas las siguientes combinaciones son válidas:

test.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 expect del Contexto de prueba local para asegurar que se detecte la prueba correcta.

test.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.sequential

Alias: it.sequential

test.sequential marca una prueba como secuencial. Esto es útil si desea ejecutar pruebas en secuencia dentro de describe.concurrent o con la opción de línea de comandos --sequence.concurrent.

import { describe, test } from 'vitest';

// ---cut---
// con la opción de configuración { sequence: { concurrent: true } }
test('concurrent test 1', async () => {
  /* ... */
});
test('concurrent test 2', async () => {
  /* ... */
});

test.sequential('sequential test 1', async () => {
  /* ... */
});
test.sequential('sequential test 2', async () => {
  /* ... */
});

// dentro del conjunto de pruebas concurrentes
describe.concurrent('suite', () => {
  test('concurrent test 1', async () => {
    /* ... */
  });
  test('concurrent test 2', async () => {
    /* ... */
  });

  test.sequential('sequential test 1', async () => {
    /* ... */
  });
  test.sequential('sequential test 2', async () => {
    /* ... */
  });
});

test.todo

Alias: it.todo

Use test.todo para 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.

// Se mostrará una entrada en el informe para esta prueba
test.todo('unimplemented test');

test.fails

Alias: it.fails

Use test.fails para indicar que una aserción fallará de manera explícita.

import { 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

Alias: it.each

Use test.each cuando 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 ('%')

import { expect, test } from 'vitest';

// ---cut---
test.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) -> 3

También puede acceder a las propiedades del objeto con el prefijo $, si está utilizando objetos como argumentos:

test.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) -> 3

También puede acceder a los atributos del objeto con ., si está utilizando objetos como argumentos:

test.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) -> 3b

A 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}.

import { expect, test } from 'vitest';

// ---cut---
test.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, utilice describe.each con 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: number | string) {
  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

Alias: suite.skip

Usa describe.skip en una suite para evitar la ejecución de un bloque describe en particular.

import { assert, describe, test } from 'vitest';

describe.skip('suite omitida', () => {
  test('sqrt', () => {
    // Suite skipped, no error
    assert.equal(Math.sqrt(4), 3);
  });
});

describe.skipIf

Alias: suite.skipIf

En 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 usar describe.skipIf para omitir la suite siempre que la condición sea verdadera.

import { 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.runIf

Alias: suite.runIf

Opuesto a describe.skipIf.

import { assert, describe, test } from 'vitest';

const isDev = process.env.NODE_ENV === 'development';

describe.runIf(isDev)('dev only test suite', () => {
  // this test suite only runs in development
});

WARNING

No puedes usar esta sintaxis cuando usas Vitest como verificador de tipo.

describe.only

Tipo: (name: string | Function, fn: TestFunction, options?: number | TestOptions) => void

Usa describe.only para ejecutar solo ciertas suites.

import { assert, describe, test } from 'vitest';
// ---cut---
// 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 only en un archivo específico, ignorando todas las demás pruebas del conjunto de pruebas, que podrían contaminar la salida.

Para hacer eso, ejecuta vitest con el archivo específico que contiene las pruebas en cuestión.

# vitest interesting.test.ts

describe.concurrent

Alias: suite.concurrent

describe.concurrent en una suite marca cada prueba dentro de ella como concurrente.

import { describe, test } from 'vitest';
// ---cut---
// 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, .only y .todo funcionan con suites concurrentes. Todas las siguientes combinaciones son válidas:

describe.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

Alias: suite.sequential

describe.sequential en una suite marca cada prueba dentro de ella como secuencial. Esto es útil si quieres ejecutar pruebas en secuencia dentro de describe.concurrent o con la opción de comando --sequence.concurrent.

import { describe, test } from 'vitest';
// ---cut---
describe.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

Alias: suite.shuffle

Vitest proporciona una forma de ejecutar todas las pruebas en orden aleatorio a través del flag de la CLI --sequence.shuffle o la opción de configuración sequence.shuffle, pero si quieres que solo una parte de tu suite ejecute las pruebas en orden aleatorio, puedes marcarla con este flag.

import { describe, test } from 'vitest';
// ---cut---
describe.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

Alias: suite.todo

Usa describe.todo para 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.

// An entry will be shown in the report for this suite
describe.todo('conjunto no implementado');

describe.each

Alias: suite.each

Usa describe.each si tienes más de una prueba que depende de los mismos datos.

import { describe, expect, test } from 'vitest';
// ---cut---
describe.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}.

import { describe, expect, test } from 'vitest';
// ---cut---
describe.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);
  });
});

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.

import { 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 beforeEach asegura que el usuario se agregue para cada prueba.

A partir de Vitest v0.10.0, beforeEach también acepta una función de limpieza opcional (cleanup), que es equivalente a afterEach.

import { 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.

import { afterEach } from 'vitest';

afterEach(async () => {
  await clearTestingData(); // clear testing data after each test run
});

Aquí, el afterEach asegura que los datos de prueba se limpien después de que se ejecute cada prueba.

TIP

Vitest 1.3.0 agregó el hook onTestFinished. Puede llamarlo durante la ejecución de la prueba para limpiar cualquier estado una vez que haya terminado la 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.

import { beforeAll } from 'vitest';

beforeAll(async () => {
  await startMocking(); // called once before all tests run
});

Aquí, el beforeAll asegura que los datos mock se configuren antes de que se ejecuten las pruebas.

A partir de Vitest v0.10.0, beforeAll también acepta una función de limpieza opcional (cleanup), que es equivalente a afterAll.

import { 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.

import { afterAll } from 'vitest';

afterAll(async () => {
  await stopMocking(); // this method is called after all tests run
});

Aquí, el afterAll asegura que el método stopMocking se llame después de que se ejecuten todas las pruebas.

Hooks de prueba

Vitest proporciona algunos hooks que puedes llamar durante la ejecución de la prueba para limpiar el estado cuando la prueba haya terminado de ejecutarse.

WARNING

Estos hooks lanzarán un error si se llaman fuera del cuerpo de la prueba.

onTestFinished 1.3.0+

Este hook siempre se llama después de que la prueba ha terminado de ejecutarse. Se llama después de los hooks afterEach ya que pueden influir en el resultado de la prueba. Recibe un objeto TaskResult con el resultado actual de la prueba.

import { onTestFinished, test from 'vitest'

test('realiza una consulta', () => {
  const db = connectDb()
  onTestFinished(()(() => db.close())
  db.query('SELECT * FROM users')
})

WARNING

Si estás ejecutando pruebas concurrentemente, siempre debes usar el hook onTestFinished desde el contexto de la prueba ya que Vitest no rastrea las pruebas concurrentes en los hooks globales:

import { test from 'vitest'

test.concurrent('realiza una consulta', ({ onTestFinished }) => {
  const db = connectDb()
  onTestFinished(()(() => db.close())
  db.query('SELECT * FROM users')
})

Este hook es particularmente útil cuando se crea lógica reutilizable:

// esto puede estar en un archivo separado
function getTestDb() {
  const db = connectMockedDb()
  onTestFinished(()(() => db.close())
  return db
}

test('realiza una consulta de usuario', async () => {
  const db = getTestDb()
  expect(await db.query('SELECT * from users').perform()).toEqual([])
})

test('realiza una consulta de organización', async () => {
  const db = getTestDb()
  expect(await db.query('SELECT * from organizations').perform()).toEqual([])
})

TIP

Este hook siempre se llama en orden inverso y no se ve afectado por la opción sequence.hooks.

onTestFailed

Este hook se llama solo después de que la prueba ha fallado. Se llama después de los hooks afterEach ya que pueden influir en el resultado de la prueba. Recibe un objeto TaskResult con el resultado actual de la prueba. Este hook es útil para la depuración.

import { onTestFailed, test from 'vitest'

test('realiza una consulta', () => {
  const db = connectDb()
  onTestFailed((e) => {
    console.log(e.result.errors)
  })
  db.query('SELECT * FROM users')
})

WARNING

Si estás ejecutando pruebas concurrentemente, siempre debes usar el hook onTestFailed desde el contexto de la prueba ya que Vitest no rastrea las pruebas concurrentes en los hooks globales:

import { test from 'vitest'

test.concurrent('realiza una consulta', ({ onTestFailed }) => {
  const db = connectDb()
  onTestFailed((result) => {
    console.log(result.errors)
  })
  db.query('SELECT * FROM users')
})

Referencia de la API de pruebas ​

test ​

test.extend 0.32.3+ ​

test.skip ​

test.skipIf ​

test.runIf ​

test.only ​

test.concurrent ​

test.sequential ​

test.todo ​

test.fails ​

test.each ​

bench ​

bench.skip ​

bench.only ​

bench.todo ​

describe ​

describe.skip ​

describe.skipIf ​

describe.runIf ​

describe.only ​

describe.concurrent ​

describe.sequential ​

describe.shuffle ​

describe.todo ​

describe.each ​

Configuración (Setup) y Desmontaje (Teardown) ​

beforeEach ​

afterEach ​

beforeAll ​

afterAll ​

Hooks de prueba ​

onTestFinished 1.3.0+ ​

onTestFailed ​

Referencia de la API de pruebas

test

test.extend 0.32.3+

test.skip

test.skipIf

test.runIf

test.only

test.concurrent

test.sequential

test.todo

test.fails

test.each

bench

bench.skip

bench.only

bench.todo

describe

describe.skip

describe.skipIf

describe.runIf

describe.only

describe.concurrent

describe.sequential

describe.shuffle

describe.todo

describe.each

Configuración (Setup) y Desmontaje (Teardown)

beforeEach

afterEach

beforeAll

afterAll

Hooks de prueba

onTestFinished 1.3.0+

onTestFailed