Referencia de la API de prueba

Las siguientes tipologías se utilizan en las firmas de tipo que aparecen a continuación.

type Awaitable<T> = T | PromiseLike<T>;
type TestFunction = () => Awaitable<void>;

interface TestOptions {
  /**
   * La prueba fallará si su ejecución excede el tiempo límite especificado.
   */
  timeout?: number;
  /**
   * Reintenta la prueba un número determinado de veces en caso de fallo.
   *
   * @default 0
   */
  retry?: number;
  /**
   * Repite la misma prueba varias veces, incluso si falla en cada ocasión.
   * Si la opción "retry" está activada y la prueba falla, cada reintento se aplicará en cada ciclo de repetición.
   * Útil para depurar fallos intermitentes.
   *
   * @default 0
   */
  repeats?: number;
}

Cuando una función de prueba devuelve una promesa, el motor de ejecución esperará a que esta se resuelva para recopilar las expectativas asíncronas. Si la promesa es rechazada, la prueba fallará.

TIP

En Jest, TestFunction también puede ser de tipo (done: DoneCallback) => void. Si se utiliza esta forma, la prueba no finalizará hasta que se llame a done. Puedes lograr el mismo resultado usando una función async; consulta la sección Guía de migración de Done Callback para más detalles.

Puedes definir opciones encadenando propiedades a una función:

import { test } from 'vitest';

test.skip('skipped test', () => {
  // alguna lógica que actualmente falla
});

test.concurrent.skip('skipped concurrent test', () => {
  // alguna lógica que actualmente falla
});

También puedes proporcionar un objeto como segundo argumento:

import { test } from 'vitest';

test('skipped test', { skip: true }, () => {
  // alguna lógica que actualmente falla
});

test('skipped concurrent test', { skip: true, concurrent: true }, () => {
  // alguna lógica que actualmente falla
});

Ambas sintaxis funcionan exactamente de la misma manera. La elección de usar una u otra es puramente una cuestión de estilo.

Ten en cuenta que si proporcionas el timeout como último argumento, no podrás usar las opciones:

import { test } from 'vitest';

// ✅ Esto funciona
test.skip('heavy test', () => {
  // ...
}, 10_000);

// ❌ Esto no funciona
test(
  'heavy test',
  { skip: true },
  () => {
    // ...
  },
  10_000
);

Sin embargo, puedes especificar un timeout dentro del objeto de opciones:

import { test } from 'vitest';

// ✅ Esto funciona
test('heavy test', { skip: true, timeout: 10_000 }, () => {
  // ...
});

test

Alias: it

test define un conjunto de expectativas relacionadas. Recibe el nombre de la prueba y una función que contiene las expectativas a verificar.

Opcionalmente, puedes especificar un timeout (en milisegundos) que define cuánto tiempo esperar antes de que la prueba finalice. 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

Alias: it.extend

Usa test.extend para extender el contexto de la prueba con fixtures personalizados. Esto devolverá una nueva función test que también es extensible, lo que te permite componer más fixtures o sobrescribir los existentes según sea necesario. Consulta Extender el Contexto de 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 deseas omitir la ejecución de ciertas pruebas, pero no quieres eliminar el código por alguna razón, puedes usar test.skip para evitar que se ejecuten.

import { assert, test } from 'vitest';

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

También puedes omitir la prueba llamando a skip en su contexto de forma dinámica:

import { assert, test } from 'vitest';

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

A partir de Vitest 3.1, si la condición es desconocida, puedes proporcionarla al método skip como primer argumento:

import { assert, test } from 'vitest';

test('skipped test', context => {
  context.skip(Math.random() < 0.5, 'optional message');
  // Prueba omitida, sin error
  assert.equal(Math.sqrt(4), 3);
});

test.skipIf

Alias: it.skipIf

En algunos casos, podrías ejecutar pruebas varias veces con diferentes entornos, y algunas de las pruebas podrían ser específicas del entorno. En lugar de envolver el código de la prueba con una condición if, puedes usar test.skipIf para omitir la prueba siempre que la condición sea verdadera.

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 puedes usar esta sintaxis cuando utilizas Vitest como verificador de tipos.

test.runIf

Alias: it.runIf

Es lo 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 puedes usar esta sintaxis cuando utilizas Vitest como verificador de tipos.

test.only

Alias: it.only

Usa test.only para ejecutar solo ciertas pruebas dentro de un conjunto. Esto es útil durante la depuración.

Opcionalmente, puedes proporcionar un timeout (en milisegundos) para especificar cuánto tiempo esperar antes de que la prueba finalice. El valor predeterminado es de 5 segundos y se puede configurar globalmente con testTimeout.

import { assert, test } from 'vitest';

test.only('test', () => {
  // Solo se ejecuta esta prueba (y otras marcadas con only)
  assert.equal(Math.sqrt(4), 2);
});

A veces es muy útil ejecutar pruebas only en un archivo determinado, ignorando todas las demás pruebas de todo el conjunto de pruebas, lo que puede saturar la salida.

Para ello, ejecuta 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 pruebas a recopilar y un timeout 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(/* ... */); // o test.concurrent.skip(/* ... */)
test.only.concurrent(/* ... */); // o test.concurrent.only(/* ... */)
test.todo.concurrent(/* ... */); // o test.concurrent.todo(/* ... */)

Al ejecutar 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 puedes usar esta sintaxis cuando utilizas Vitest como verificador de tipos.

test.sequential

Alias: it.sequential

test.sequential marca una prueba 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';

// 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 de un conjunto concurrente
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

Usa test.todo para crear stubs de pruebas que se implementarán más tarde. Se mostrará una entrada en el informe de las pruebas para que sepas cuántas pruebas aún necesitas implementar.

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

test.fails

Alias: it.fails

Usa test.fails para indicar que una aserción fallará explícitamente.

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 puedes usar esta sintaxis cuando utilizas Vitest como verificador de tipos.

test.each

Alias: it.each

TIP

Aunque test.each se proporciona para la compatibilidad con Jest, Vitest también tiene test.for con una característica adicional para integrar TestContext.

Usa test.each cuando necesites ejecutar la misma prueba con diferentes variables. Puedes inyectar parámetros con formato printf en el nombre de la prueba, siguiendo el orden de los parámetros de la función de prueba.

%s: cadena
%d: número
%i: entero
%f: valor de punto flotante
%j: json
%o: objeto
%#: índice basado en 0 del caso de prueba
%$: índice basado en 1 del caso de prueba
%%: un solo signo de porcentaje ('%')

import { expect, test } from 'vitest';

test.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

// esto devolverá
// ✓ add(1, 1) -> 2
// ✓ add(1, 2) -> 3
// ✓ add(2, 1) -> 3

También puedes acceder a las propiedades de los objetos y a los elementos de los arrays con el prefijo $:

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

// esto devolverá
// ✓ add(1, 1) -> 2
// ✓ add(1, 2) -> 3
// ✓ add(2, 1) -> 3

test.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add($0, $1) -> $2', (a, b, expected) => {
  expect(a + b).toBe(expected);
});

// esto devolverá
// ✓ add(1, 1) -> 2
// ✓ add(1, 2) -> 3
// ✓ add(2, 1) -> 3

También puedes acceder a las propiedades de los objetos con ., si estás usando 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);
});

// esto devolverá
// ✓ add(1, b) -> 1b
// ✓ add(2, b) -> 2b
// ✓ add(3, b) -> 3b

A partir de Vitest 0.25.3, también puedes usar la sintaxis de tabla de cadenas de plantilla.

La primera fila debe contener 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 { expect, test } from 'vitest';

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

TIP

Vitest procesa los $values con el método format de Chai. Si el valor está demasiado truncado, puedes aumentar chaiConfig.truncateThreshold en tu archivo de configuración.

WARNING

No puedes usar esta sintaxis cuando utilizas Vitest como verificador de tipos.

test.for

Alias: it.for

Alternativa a test.each para proporcionar TestContext.

La diferencia con test.each radica en cómo se proporcionan los arrays en los argumentos. Los argumentos que no son arrays para test.for (incluido el uso de cadenas de plantilla) funcionan exactamente igual que para test.each.

// `each` desestructura arrays
test.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', (a, b, expected) => { 
  expect(a + b).toBe(expected);
});

// `for` no desestructura arrays (observa los corchetes alrededor de los argumentos)
test.for([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', ([a, b, expected]) => { 
  expect(a + b).toBe(expected);
});

El segundo argumento es TestContext y se puede usar para instantáneas concurrentes, por ejemplo:

test.concurrent.for([
  [1, 1],
  [1, 2],
  [2, 1],
])('add(%i, %i)', ([a, b], { expect }) => {
  expect(a + b).matchSnapshot();
});

bench

Tipo: (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

bench define un benchmark. 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 librería tinybench internamente, heredando todas sus opciones, las cuales pueden usarse como 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 el tiempo asignado ha finalizado.
   * @default 10
   */
  iterations?: number;

  /**
   * Función para obtener la marca de tiempo actual en milisegundos.
   */
  now?: () => number;

  /**
   * Una AbortSignal para abortar el benchmark.
   */
  signal?: AbortSignal;

  /**
   * Lanza un error si una tarea falla (los eventos no funcionarán si se establece en verdadero).
   */
  throws?: boolean;

  /**
   * Tiempo de calentamiento (milisegundos).
   * @default 100ms
   */
  warmupTime?: number;

  /**
   * Iteraciones de calentamiento.
   * @default 5
   */
  warmupIterations?: number;

  /**
   * Función de configuración para ejecutar antes de cada tarea de benchmark (ciclo).
   */
  setup?: Hook;

  /**
   * Función de limpieza para ejecutar después de cada tarea de benchmark (ciclo).
   */
  teardown?: Hook;
}

Después de ejecutar el caso de prueba, la información de la estructura de salida es la siguiente:

  name                      hz     min     max    mean     p75     p99    p995    p999     rme  samples
· normal sorting  6,526,368.12  0.0001  0.3638  0.0002  0.0002  0.0002  0.0002  0.0004  ±1.41%   652638

export interface TaskResult {
  /*
   * El último error que se lanzó al ejecutar la tarea.
   */
  error?: unknown;

  /**
   * La cantidad de tiempo en milisegundos para ejecutar la tarea de benchmark (ciclo).
   */
  totalTime: number;

  /**
   * El valor mínimo en las muestras.
   */
  min: number;
  /**
   * El valor máximo en las muestras.
   */
  max: number;

  /**
   * El número de operaciones por segundo.
   */
  hz: number;

  /**
   * Cuánto tiempo tarda cada operación (ms).
   */
  period: number;

  /**
   * Muestras del tiempo de cada iteración de la tarea (ms).
   */
  samples: number[];

  /**
   * Media/promedio de las muestras (estimación de la media de la población).
   */
  mean: number;

  /**
   * Varianza de las muestras (estimación de la varianza de la población).
   */
  variance: number;

  /**
   * Desviación estándar de las muestras (estimación de la desviación estándar de la población).
   */
  sd: number;

  /**
   * Error estándar de la media (también conocido como la desviación estándar de la distribución muestral de la media muestral).
   */
  sem: number;

  /**
   * Grados de libertad.
   */
  df: number;

  /**
   * Valor crítico de las muestras.
   */
  critical: number;

  /**
   * Margen de error.
   */
  moe: number;

  /**
   * Margen de error relativo.
   */
  rme: number;

  /**
   * Desviación absoluta de la mediana.
   */
  mad: number;

  /**
   * Percentil p50/mediana.
   */
  p50: number;

  /**
   * Percentil p75.
   */
  p75: number;

  /**
   * Percentil p99.
   */
  p99: number;

  /**
   * Percentil p995.
   */
  p995: number;

  /**
   * Percentil p999.
   */
  p999: number;
}

bench.skip

Tipo: (name: string | Function, fn: BenchFunction, options?: BenchOptions) => void

Puedes 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

Usa bench.only para ejecutar solo ciertos benchmarks dentro de un conjunto determinado. Esto es útil durante 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

Usa bench.todo para crear stubs de benchmarks que se implementarán más tarde.

import { bench } from 'vitest';

bench.todo('unimplemented test');

describe

Cuando utilizas test o bench en el nivel superior de un archivo, se recopilan como parte del conjunto implícito para este. Utilizando describe, puedes definir un nuevo conjunto en el contexto actual, como un conjunto de pruebas o comparativas relacionadas y otros conjuntos anidados. Un conjunto te permite organizar tus pruebas y comparativas 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 está definido', () => {
    expect(person).toBeDefined();
  });

  test('está activo', () => {
    expect(person.isActive).toBeTruthy();
  });

  test('límite de edad', () => {
    expect(person.age).toBeLessThanOrEqual(32);
  });
});

// basic.bench.ts
// organizando comparativas

import { bench, describe } from 'vitest';

describe('ordenar', () => {
  bench('normal', () => {
    const x = [1, 5, 4, 2, 3];
    x.sort((a, b) => {
      return a - b;
    });
  });

  bench('inverso', () => {
    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 comparativas:

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

function numberToCurrency(value: number | string) {
  if (typeof value !== 'number') {
    throw new TypeError('El valor debe ser un número');
  }

  return value
    .toFixed(2)
    .toString()
    .replace(/\B(?=(\d{3})+(?!\d))/g, ',');
}

describe('numberToCurrency', () => {
  describe('dado un número inválido', () => {
    test('compuesto por no-números debe lanzar un error', () => {
      expect(() => numberToCurrency('abc')).toThrowError();
    });
  });

  describe('dado un número válido', () => {
    test('devuelve el formato de moneda correcto', () => {
      expect(numberToCurrency(10000)).toBe('10,000.00');
    });
  });
});

describe.skip

Alias: suite.skip

Usa describe.skip en un conjunto para evitar ejecutar un bloque describe en particular.

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

describe.skip('conjunto saltado', () => {
  test('sqrt', () => {
    // Conjunto saltado, sin error
    assert.equal(Math.sqrt(4), 3);
  });
});

describe.skipIf

Alias: suite.skipIf

En algunos casos, podrías ejecutar conjuntos varias veces con diferentes entornos, y algunos de los conjuntos podrían ser específicos del entorno. En lugar de envolver el conjunto con un if, puedes usar describe.skipIf para saltar el conjunto siempre que la condición sea verdadera.

import { describe, test } from 'vitest';

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

describe.skipIf(isDev)('conjunto de pruebas solo para prod', () => {
  // este conjunto de pruebas solo se ejecuta en producción
});

WARNING

No puedes usar esta sintaxis cuando usas 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)('conjunto de pruebas solo para dev', () => {
  // este conjunto de pruebas solo se ejecuta en desarrollo
});

WARNING

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

describe.only

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

Usa describe.only para ejecutar solo ciertos conjuntos.

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

// Solo se ejecuta este conjunto (y otros marcados con only)
describe.only('conjunto', () => {
  test('sqrt', () => {
    assert.equal(Math.sqrt(4), 3);
  });
});

describe('otro conjunto', () => {
  // ... será saltado
});

A veces es muy útil ejecutar pruebas only en un archivo determinado, ignorando todas las demás pruebas de todo el conjunto de pruebas, que contaminan la salida.

Para ello, 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 ejecuta todos los conjuntos y pruebas internas en paralelo.

import { describe, test } from 'vitest';

// Todos los conjuntos y pruebas dentro de este conjunto se ejecutarán en paralelo
describe.concurrent('conjunto', () => {
  test('prueba concurrente 1', async () => {
    /* ... */
  });
  describe('conjunto concurrente 2', async () => {
    test('prueba concurrente interna 1', async () => {
      /* ... */
    });
    test('prueba concurrente interna 2', async () => {
      /* ... */
    });
  });
  test.concurrent('prueba concurrente 3', async () => {
    /* ... */
  });
});

.skip, .only y .todo funcionan con conjuntos concurrentes. Todas las siguientes combinaciones son válidas:

describe.concurrent(/* ... */);
describe.skip.concurrent(/* ... */); // o describe.concurrent.skip(/* ... */)
describe.only.concurrent(/* ... */); // o describe.concurrent.only(/* ... */)
describe.todo.concurrent(/* ... */); // o describe.concurrent.todo(/* ... */)

Al ejecutar pruebas concurrentes, las Instantáneas (Snapshots) y las Aserciones deben usar expect del Contexto de Prueba local para asegurar que se detecte la prueba correcta.

describe.concurrent('conjunto', () => {
  test('prueba concurrente 1', async ({ expect }) => {
    expect(foo).toMatchSnapshot();
  });
  test('prueba concurrente 2', async ({ expect }) => {
    expect(foo).toMatchSnapshot();
  });
});

WARNING

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

describe.sequential

Alias: suite.sequential

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

import { describe, test } from 'vitest';

describe.concurrent('conjunto', () => {
  test('prueba concurrente 1', async () => {
    /* ... */
  });
  test('prueba concurrente 2', async () => {
    /* ... */
  });

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

describe.shuffle

Alias: suite.shuffle

Vitest proporciona una forma de ejecutar todas las pruebas en orden aleatorio a través de la bandera CLI --sequence.shuffle o la opción de configuración sequence.shuffle, pero si solo deseas que parte de tu conjunto de pruebas ejecute las pruebas en orden aleatorio, puedes marcarlo con esta bandera.

import { describe, test } from 'vitest';

// o describe('conjunto', { shuffle: true }, ...)
describe.shuffle('conjunto', () => {
  test('prueba aleatoria 1', async () => {
    /* ... */
  });
  test('prueba aleatoria 2', async () => {
    /* ... */
  });
  test('prueba aleatoria 3', async () => {
    /* ... */
  });

  // `shuffle` se hereda
  describe('todavía aleatorio', () => {
    test('aleatoria 4.1', async () => {
      /* ... */
    });
    test('aleatoria 4.2', async () => {
      /* ... */
    });
  });

  // deshabilita shuffle en el interior
  describe('no aleatorio', { shuffle: false }, () => {
    test('en orden 5.1', async () => {
      /* ... */
    });
    test('en orden 5.2', async () => {
      /* ... */
    });
  });
});
// el orden depende de la opción sequence.seed en la configuración (Date.now() por defecto)

.skip, .only y .todo funcionan con conjuntos aleatorios.

WARNING

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

describe.todo

Alias: suite.todo

Usa describe.todo para definir conjuntos que se implementarán más tarde. Se mostrará una entrada en el informe para las pruebas para que sepas cuántas pruebas aún necesitas implementar.

// Se mostrará una entrada en el informe para este conjunto
describe.todo('conjunto no implementado');

describe.each

Alias: suite.each

TIP

Si bien describe.each se proporciona para compatibilidad con Jest, Vitest también tiene describe.for que simplifica los tipos de argumentos y se alinea con test.for.

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

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

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(`devuelve ${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 cadena de plantilla.

La primera fila debe ser nombres de columna, separados por |;
Una o más filas subsiguientes de datos proporcionados como expresiones literales de plantilla usando la sintaxis ${valor}.

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

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(`devuelve ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

WARNING

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

describe.for

Alias: suite.for

La diferencia con describe.each es cómo se proporciona el caso de array en los argumentos. Otros casos que no son array (incluido el uso de cadena de plantilla) funcionan exactamente igual.

// `each` expande el caso de array
describe.each([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', (a, b, expected) => { 
  test('prueba', () => {
    expect(a + b).toBe(expected);
  });
});

// `for` no expande el caso de array
describe.for([
  [1, 1, 2],
  [1, 2, 3],
  [2, 1, 3],
])('add(%i, %i) -> %i', ([a, b, expected]) => { 
  test('prueba', () => {
    expect(a + b).toBe(expected);
  });
});

Configuración y Desmontaje

Estas funciones te permiten engancharte al ciclo de vida de las pruebas para evitar repetir 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 llaman cuando ejecutas Vitest como verificador de tipos.

beforeEach

Tipo: beforeEach(fn: () => Awaitable<void>, timeout?: number)

Registra una función de callback para ser llamada antes de que se ejecute cada una de las pruebas en el contexto actual. Si la función devuelve una promesa, Vitest espera hasta que la promesa se resuelva antes de ejecutar la prueba.

Opcionalmente, puedes pasar un timeout (en milisegundos) que define cuánto tiempo esperar antes de que la prueba finalice. El valor predeterminado es de 5 segundos.

import { beforeEach } from 'vitest';

beforeEach(async () => {
  // Limpiar mocks y añadir algunos datos de prueba antes de cada ejecución de prueba
  await stopMocking();
  await addUser({ name: 'John' });
});

Aquí, beforeEach asegura que el usuario se agregue para cada prueba.

beforeEach también acepta una función de limpieza opcional (equivalente a afterEach).

import { beforeEach } from 'vitest';

beforeEach(async () => {
  // llamada una vez antes de cada ejecución de prueba
  await prepareSomething();

  // función de limpieza, llamada 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 de callback para ser llamada después de que cada una de las pruebas en el contexto actual se complete. Si la función devuelve una promesa, Vitest espera hasta que la promesa se resuelva antes de continuar.

Opcionalmente, puedes proporcionar un timeout (en milisegundos) para especificar cuánto tiempo esperar antes de que la prueba finalice. El valor predeterminado es de 5 segundos.

import { afterEach } from 'vitest';

afterEach(async () => {
  await clearTestingData(); // limpiar datos de prueba después de cada ejecución de prueba
});

Aquí, afterEach asegura que los datos de prueba se limpien después de cada ejecución de prueba.

TIP

Vitest 1.3.0 añadió el hook onTestFinished. Puedes llamarlo durante la ejecución de la prueba para limpiar cualquier estado después de que la prueba haya terminado de ejecutarse.

beforeAll

Tipo: beforeAll(fn: () => Awaitable<void>, timeout?: number)

Registra una función de callback para ser llamada una vez antes de comenzar a ejecutar todas las pruebas en el contexto actual. Si la función devuelve una promesa, Vitest espera hasta que la promesa se resuelva antes de ejecutar las pruebas.

Opcionalmente, puedes proporcionar un timeout (en milisegundos) para especificar cuánto tiempo esperar antes de que la prueba finalice. El valor predeterminado es de 5 segundos.

import { beforeAll } from 'vitest';

beforeAll(async () => {
  await startMocking(); // llamada una vez antes de que se ejecuten todas las pruebas
});

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

beforeAll también acepta una función de limpieza opcional (equivalente a afterAll).

import { beforeAll } from 'vitest';

beforeAll(async () => {
  // llamada una vez antes de que se ejecuten todas las pruebas
  await startMocking();

  // función de limpieza, llamada 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 de callback para ser llamada una vez después de que todas las pruebas se hayan ejecutado en el contexto actual. Si la función devuelve una promesa, Vitest espera hasta que la promesa se resuelva antes de continuar.

Opcionalmente, puedes proporcionar un timeout (en milisegundos) para especificar cuánto tiempo esperar antes de que la prueba finalice. El valor predeterminado es de 5 segundos.

import { afterAll } from 'vitest';

afterAll(async () => {
  await stopMocking(); // este método se llama después de que se ejecutan todas las pruebas
});

Aquí, 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 ha terminado de ejecutarse.

WARNING

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

onTestFinished

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 ExtendedContext como beforeEach y afterEach.

import { onTestFinished, test } from 'vitest';

test('performs a query', () => {
  const db = connectDb();
  onTestFinished(() => db.close());
  db.query('SELECT * FROM users');
});

WARNING

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

import { test } from 'vitest';

test.concurrent('performs a query', ({ onTestFinished }) => {
  const db = connectDb();
  onTestFinished(() => db.close());
  db.query('SELECT * FROM users');
});

Este hook es particularmente útil al crear lógica reutilizable:

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

test('performs a user query', async () => {
  const db = getTestDb();
  expect(await db.query('SELECT * from users').perform()).toEqual([]);
});

test('performs an organization query', 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 ExtendedContext como beforeEach y afterEach. Este hook es útil para depurar.

import { onTestFailed, test } from 'vitest';

test('performs a query', () => {
  const db = connectDb();
  onTestFailed(({ task }) => {
    console.log(task.result.errors);
  });
  db.query('SELECT * FROM users');
});

WARNING

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

import { test } from 'vitest';

test.concurrent('performs a query', ({ onTestFailed }) => {
  const db = connectDb();
  onTestFailed(({ task }) => {
    console.log(task.result.errors);
  });
  db.query('SELECT * FROM users');
});

Referencia de la API de prueba ​

test ​

test.extend ​

test.skip ​

test.skipIf ​

test.runIf ​

test.only ​

test.concurrent ​

test.sequential ​

test.todo ​

test.fails ​

test.each ​

test.for ​

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 ​

describe.for ​

Configuración y Desmontaje ​

beforeEach ​

afterEach ​

beforeAll ​

afterAll ​

Hooks de Prueba ​

onTestFinished ​

onTestFailed ​

Referencia de la API de prueba

test

test.extend

test.skip

test.skipIf

test.runIf

test.only

test.concurrent

test.sequential

test.todo

test.fails

test.each

test.for

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

describe.for

Configuración y Desmontaje

beforeEach

afterEach

beforeAll

afterAll

Hooks de Prueba

onTestFinished

onTestFailed