Primeros pasos

Resumen

Vitest (pronunciado como "vii-test") es un marco de pruebas de próxima generación impulsado por Vite.

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

Probar Vitest en línea

Puedes ejecutar Vitest directamente en el navegador en StackBlitz. Esta experiencia es prácticamente idéntica a la configuración local, pero no requiere instalar nada en tu máquina.

Añadir Vitest a tu proyecto

Aprende a instalarlo mediante 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 una copia de 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 se incluye con npm y Node.js).

La herramienta npx ejecuta el comando especificado. Por defecto, npx primero verifica si el comando existe en los binarios del proyecto local. Si no lo encuentra allí, npx buscará en el $PATH del sistema y lo ejecutará si lo encuentra. Si el comando no se encuentra en ninguna ubicación, npx lo instalará en una ubicación temporal antes de la ejecución.

Escribir pruebas

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

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

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 nombres de archivo de las pruebas deben contener .test. o .spec..

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

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

Finalmente, ejecuta npm run test, yarn test o pnpm test, según 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

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 usará su propio ejecutor de pruebas.

Para obtener más información sobre el uso de 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 vite.config.ts raíz para que coincida con los plugins y la configuración de 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á mayor prioridad.
• Pasar el parámetro --config a la CLI, por ejemplo, vitest --config ./path/to/vitest.config.ts.
• Usar process.env.VITEST o la propiedad mode en defineConfig (será test a menos que se especifique lo contrario) para aplicar condicionalmente una configuración diferente en vite.config.ts.

Vitest admite 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 directamente, Vitest depende mucho 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 agregar una referencia a los tipos de Vitest usando 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: {
    // ...
  },
});

El <reference types="vitest" /> dejará de ser compatible en la próxima actualización principal, pero puedes empezar a migrar a vitest/config en Vitest 2.1:

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

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

Revisa 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 sobrescribirá tu archivo de Vite, no lo extenderá. También puedes usar el método mergeConfig de las entradas vite o vitest/config para combinar 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()],
});

Sin embargo, recomendamos utilizar el mismo archivo para Vite y Vitest, en lugar de crear dos archivos separados.

Soporte de proyectos

Vitest permite ejecutar diferentes configuraciones de proyecto dentro del mismo proyecto con Proyectos de prueba. Puedes especificar una lista de archivos y carpetas que definen tus proyectos en el archivo vitest.config.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      // puedes utilizar una lista de patrones glob para definir tus proyectos
      // Vitest espera una lista de archivos de configuración
      // o directorios que contengan un archivo de configuración
      'packages/*',
      'tests/*/vitest.config.{e2e,unit}.ts',
      // también puedes ejecutar las mismas pruebas,
      // pero con diferentes configuraciones en la misma instancia de "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. Estos son los scripts de npm predeterminados en un proyecto Vitest inicializado:

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

Para ejecutar las pruebas una sola vez sin observar cambios en los archivos, usa vitest run. Puedes agregar opciones adicionales a la CLI como --port o --https. Para una lista completa de opciones 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 solicitará que instales ciertas dependencias si aún no están instaladas. Puedes deshabilitar este comportamiento estableciendo 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 con las pruebas 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
projects	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 liberados

Cada commit en la rama principal y una PR con una etiqueta cr-tracked se publican en pkg.pr.new. Puedes instalarlo ejecutando npm i https://pkg.pr.new/vitest@{commit}.

Si quieres probar tu propia modificación localmente, puedes construirlo y enlazarlo tú mismo (es necesario pnpm):

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

Después, 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, ponte en contacto con la comunidad en Discord y GitHub Discussions.