Empezando

Resumen

Vitest es un framework de pruebas de última generación impulsado por Vite.

Puedes obtener más información sobre la razón de ser de este proyecto en la sección Por qué Vitest.

Probar Vitest en línea

Puedes probar Vitest online en StackBlitz. Ejecuta Vitest directamente en el navegador, de forma casi idéntica a una configuración local, pero sin necesidad de instalar nada en tu máquina.

Agregar Vitest a tu Proyecto

Aprende a instalarlo en este video

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

Vitest 1.0 requiere Vite >=v5.0.0 y Node >=v18.0.0

Se recomienda instalar vitest como una dependencia de desarrollo en tu package.json, utilizando uno de los métodos mencionados anteriormente. Sin embargo, si prefieres ejecutar vitest directamente, puedes usar npx vitest (el comando npx se incluye con npm y Node.js).

El comando npx ejecutará el comando desde node_modules/.bin local, instalando los paquetes necesarios para su ejecución. Por defecto, npx verificará si el comando existe en $PATH o en los binarios del proyecto local, y lo ejecutará. Si el comando no se encuentra, se instalará antes de la ejecución.

Escribir Pruebas

Como ejemplo, escribiremos una prueba sencilla que verifica la salida de una función que suma dos números.

// sum.js
export function sum(a, b) {
  return a + b;
}

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

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

TIP

De forma predeterminada, las pruebas deben contener ".test." o ".spec." en el nombre del archivo.

Para ejecutar la prueba, añade la siguiente sección a tu package.json:

{
  "scripts": {
    "test": "vitest"
  }
}

Finalmente, ejecuta npm run test, yarn test o pnpm test, dependiendo de tu gestor de paquetes, y Vitest imprimirá este mensaje:

✓ sum.test.js (1)
  ✓ adds 1 + 2 to equal 3

Test Files  1 passed (1)
    Tests  1 passed (1)
  Start at  02:15:44
  Duration  311ms

Para aprender más sobre cómo usar Vitest, consulta la sección API.

Configurar Vitest

Una de las principales ventajas de Vitest es su configuración unificada con Vite. Si está presente, vitest leerá tu archivo vite.config.ts raíz para coincidir con los plugins y la configuración de tu aplicación Vite. Por ejemplo, tu configuración de Vite para resolve.alias y plugins funcionará sin configuración adicional. Si deseas una configuración diferente durante las pruebas, puedes:

• Crear un archivo vitest.config.ts, que tendrá la máxima prioridad.
• Pasar la opción --config a la CLI, por ejemplo: vitest --config ./path/to/vitest.config.ts.
• Usar process.env.VITEST o la propiedad mode en defineConfig (se establecerá en test si no se anula) para aplicar condicionalmente una configuración diferente en vite.config.ts.

Vitest soporta las mismas extensiones para tu archivo de configuración que Vite: .js, .mjs, .cjs, .ts, .cts, .mts. Vitest no soporta la extensión .json.

Si no estás usando Vite como herramienta de build, puedes configurar Vitest usando la propiedad test en tu archivo de configuración:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ...
  },
});

TIP

Incluso si no usas Vite directamente, Vitest depende en gran medida de él para el proceso de transformación. Por esa razón, también puedes configurar cualquier propiedad descrita en la documentación de Vite.

También debes agregar una referencia a los tipos de Vitest mediante una directiva de triple barra en la parte superior de tu archivo de configuración.

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ...
  },
});

Consulta la lista de opciones de configuración en la Referencia de Configuración

WARNING

Si decides tener dos archivos de configuración separados para Vite y Vitest, asegúrate de definir las mismas opciones de Vite en tu archivo de configuración de Vitest, ya que reemplazará tu archivo de Vite, en lugar de extenderlo. También puedes usar el método mergeConfig de las entradas vite o vitest/config para fusionar la configuración de Vite con la configuración de Vitest:

vitest.config.mjs

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config.mjs';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // ...
    },
  })
);

vite.config.mjs

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [Vue()],
});

Pero recomendamos usar el mismo archivo tanto para Vite como para Vitest en lugar de crear dos archivos separados.

Soporte de Espacios de Trabajo (Workspaces)

Ejecuta diferentes configuraciones dentro de un mismo proyecto con Espacios de Trabajo (Workspaces) de Vitest. Puedes definir una lista de archivos y carpetas que definen tu espacio de trabajo en el archivo vitest.workspace. El archivo soporta las extensiones js/ts/json. Esta característica funciona muy bien con configuraciones de monorepositorios.

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  // puedes usar una lista de patrones glob para definir tus espacios de trabajo
  // Vitest espera una lista de archivos de configuración
  // o directorios donde haya un archivo de configuración
  'packages/*',
  'tests/*/vitest.config.{e2e,unit}.ts',
  // incluso puedes ejecutar las mismas pruebas,
  // pero con diferentes configuraciones en el mismo proceso "vitest"
  {
    test: {
      name: 'happy-dom',
      root: './shared_tests',
      environment: 'happy-dom',
      setupFiles: ['./setup.happy-dom.ts'],
    },
  },
  {
    test: {
      name: 'node',
      root: './shared_tests',
      environment: 'node',
      setupFiles: ['./setup.node.ts'],
    },
  },
]);

Interfaz de línea de comandos

En un proyecto donde Vitest está instalado, puedes usar el binario vitest en tus scripts de npm, o ejecutarlo directamente usando npx vitest. Aquí están los scripts de npm predeterminados en un proyecto de Vitest recién inicializado:

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

Para ejecutar las pruebas una sola vez sin observar los cambios en los archivos, usa vitest run. Puedes especificar opciones de CLI adicionales como --port o --https. Para obtener una lista completa de opciones de CLI, ejecuta npx vitest --help en tu proyecto.

Aprende más sobre la Interfaz de Línea de Comandos

Integración con IDEs

También proporcionamos una extensión oficial para Visual Studio Code para mejorar tu experiencia de pruebas con Vitest.

Instalar desde VS Code Marketplace

Aprende más sobre Integraciones con IDE

Ejemplos

Ejemplo	Fuente	Playground
basic	GitHub	Play Online
fastify	GitHub	Play Online
lit	GitHub	Play Online
marko	GitHub	Play Online
preact	GitHub	Play Online
react	GitHub	Play Online
solid	GitHub	Play Online
sveltekit	GitHub	Play Online
typecheck	GitHub	Play Online
workspace	GitHub	Play Online

Proyectos que usan Vitest

• unocss
• unplugin-auto-import
• unplugin-vue-components
• vue
• vite
• vitesse
• vitesse-lite
• fluent-vue
• vueuse
• milkdown
• gridjs-svelte
• spring-easing
• bytemd
• faker
• million
• Vitamin
• neodrag
• svelte-multiselect
• iconify
• tdesign-vue-next
• cz-git

Usar Commits sin publicar

Si no puedes esperar a una nueva versión para probar las últimas características, deberás clonar el repositorio de vitest a tu máquina local, compilarlo y luego vincularlo tú mismo (se requiere pnpm):

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # puedes usar tu gestor de paquetes preferido para este paso

Luego, ve al proyecto donde estás usando Vitest y ejecuta pnpm link --global vitest (o el gestor de paquetes que usaste para vincular vitest globalmente).

Comunidad

Si tienes preguntas o necesitas ayuda, contacta con la comunidad en Discord y GitHub Discussions.