Primeros Pasos

Resumen

Vitest (pronunciado como "vi-test", similar a "vite" y "test") es un framework de pruebas de próxima generación impulsado por Vite.

Puedes aprender más sobre la razón detrás del proyecto en la sección Por qué Vitest.

Probando Vitest en línea

Puedes probar Vitest en línea en StackBlitz. Ejecuta Vitest directamente en el navegador; es casi idéntico a la configuración local, pero no requiere instalar nada en tu máquina.

Añadiendo Vitest a tu proyecto

Aprende a instalarlo con un video

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

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

Se recomienda instalar vitest en tu package.json utilizando uno de los métodos listados anteriormente. Sin embargo, si prefieres ejecutar vitest directamente, puedes usar npx vitest (la herramienta npx viene incluida con npm y Node.js).

La herramienta npx ejecutará el comando especificado. Por defecto, npx primero verificará si el comando existe en los ejecutables del proyecto local. Si no lo encuentra allí, npx buscará en el $PATH del sistema y lo ejecutará si está presente. Si el comando no se encuentra en ninguna de las ubicaciones, npx lo instalará temporalmente antes de la ejecución.

Escribiendo pruebas

Como ejemplo, escribiremos una prueba simple que verifica el resultado 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.js';

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

TIP

Por defecto, los archivos de prueba deben contener ".test." o ".spec." en su nombre.

A continuación, para ejecutar la prueba, agrega la siguiente sección a tu package.json:

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

Por último, ejecuta npm run test, yarn test o pnpm test, según tu gestor de paquetes, y Vitest mostrará 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

WARNING

Si estás usando Bun como tu gestor de paquetes, asegúrate de usar el comando bun run test en lugar de bun test, de lo contrario Bun ejecutará su propio ejecutor de pruebas.

Para aprender más sobre el uso de Vitest, consulta la sección API.

Configurando Vitest

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

• Crear vitest.config.ts, que tendrá la mayor 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 sobrescribe) 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 admite la extensión .json.

Si no estás usando Vite como tu herramienta de construcción, 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, Vitest depende en gran medida de él para su cadena de transformación. Por esa razón, también puedes configurar cualquier propiedad descrita en la documentación de Vite.

Si ya estás usando Vite, añade la propiedad test en tu configuración de Vite. También necesitarás añadir una referencia a los tipos de Vitest usando una directiva de tres barras en la parte superior de tu archivo de configuración.

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

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

El <reference types="vitest" /> dejará de ser compatible en Vitest 3, pero puedes empezar a migrar a vitest/config en Vitest 2.1:

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

export default defineConfig({
  test: {
    // ... Especifica las opciones aquí.
  },
});

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 lo sobrescribirá 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 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()],
});

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

Soporte de Workspaces

Gestiona diferentes configuraciones de proyectos dentro del mismo proyecto con Vitest Workspaces. Puedes definir una lista de archivos y carpetas que definen tu espacio de trabajo en el archivo vitest.workspace. El archivo admite extensiones js/ts/json. Esta característica funciona muy bien con proyectos monorepo.

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 con npx vitest. Aquí están los scripts de npm por defecto en un proyecto Vitest inicializado:

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

Para ejecutar las pruebas una vez sin observar los cambios en los archivos, usa vitest run. Puedes especificar opciones adicionales de CLI como --port o --https. Para 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

Instalación Automática de Dependencias

Vitest te solicitará que instales ciertas dependencias si aún no están instaladas. Puedes desactivar este comportamiento configurando la variable de entorno VITEST_SKIP_INSTALL_CHECKS=1.

Integraciones IDE

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

Instalar desde VS Code Marketplace

Aprende más sobre las Integraciones IDE

Ejemplos

Ejemplo	Fuente	Playground
basic	GitHub	Probar en línea
fastify	GitHub	Probar en línea
in-source-test	GitHub	Probar en línea
lit	GitHub	Probar en línea
vue	GitHub	Probar en línea
marko	GitHub	Probar en línea
preact	GitHub	Probar en línea
react	GitHub	Probar en línea
solid	GitHub	Probar en línea
svelte	GitHub	Probar en línea
sveltekit	GitHub	Probar en línea
profiling	GitHub	No disponible
typecheck	GitHub	Probar en línea
workspace	GitHub	Probar en línea

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

Usando Commits no publicados

Cada commit en la rama principal y una solicitud de extracción (PR) con la etiqueta cr-tracked se publican en pkg.pr.new. Puedes instalarlo usando npm i https://pkg.pr.new/vitest@{commit}.

Si quieres probar tu propia modificación localmente, puedes compilarla y enlazarla 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 dirígete al proyecto donde estás usando Vitest y ejecuta pnpm link --global vitest (o el gestor de paquetes que hayas utilizado para enlazar vitest globalmente).

Comunidad

Si tienes preguntas o necesitas ayuda, dirígete a la comunidad en Discord y GitHub Discussions.