API de Plugins 3.1.0+

WARNING

Esta es una API avanzada. Si solo deseas ejecutar pruebas, es probable que no la necesites. Su uso principal es para autores de bibliotecas.

Esta guía asume que tienes conocimientos sobre cómo trabajar con plugins de Vite.

Vitest soporta un hook de plugin experimental configureVitest a partir de la versión 3.1. Agradecemos cualquier comentario sobre esta API en GitHub.

only vitest

import type { Vite, VitestPluginContext } from 'vitest/node';

export function plugin(): Vite.Plugin {
  return {
    name: 'vitest:my-plugin',
    configureVitest(context: VitestPluginContext) {
      // ...
    },
  };
}

vite and vitest

/// <reference types="vitest/config" />

import type { Plugin } from 'vite';

export function plugin(): Plugin {
  return {
    name: 'vitest:my-plugin',
    transform() {
      // ...
    },
    configureVitest(context) {
      // ...
    },
  };
}

TypeScript

Vitest reexporta todos los tipos de importación de Vite a través de un espacio de nombres Vite, que puedes usar para mantener tus versiones sincronizadas. Sin embargo, si estás escribiendo un plugin tanto para Vite como para Vitest, puedes seguir usando el tipo Plugin del módulo vite. Solo asegúrate de tener vitest/config referenciado en algún lugar para que configureVitest se extienda correctamente:

/// <reference types="vitest/config" />

A diferencia de reporter.onInit, este hook se ejecuta al inicio del ciclo de vida de Vitest, lo que te permite realizar cambios en la configuración, como coverage y reporters. Un cambio aún más notable es que puedes manipular la configuración global desde un proyecto de prueba si tu plugin está definido en el proyecto y no en la configuración global.

Contexto

project

El proyecto de prueba actual al que está asociado el plugin.

Browser Mode

Ten en cuenta que si dependes de alguna característica del navegador, el campo project.browser aún no está establecido. Usa el evento reporter.onBrowserInit en su lugar.

vitest

La instancia global de Vitest. Puedes cambiar la configuración global modificando directamente la propiedad vitest.config:

vitest.config.coverage.enabled = false;
vitest.config.reporters.push([['my-reporter', {}]]);

Configuración resuelta

Ten en cuenta que Vitest ya ha resuelto la configuración, por lo que algunos tipos podrían ser diferentes de la configuración de usuario estándar. Esto también significa que algunas propiedades no se volverán a resolver, como setupFile. Si estás añadiendo nuevos archivos, asegúrate de resolverlos primero.

En este punto, los reporters aún no se han creado, por lo que modificar vitest.reporters no tendrá ningún efecto, ya que será sobrescrito. Si necesitas inyectar tu propio reporter, modifica la configuración en su lugar.

injectTestProjects

function injectTestProjects(
  config: TestProjectConfiguration | TestProjectConfiguration[]
): Promise<TestProject[]>;

Este método acepta un patrón glob de configuración, una ruta de archivo a la configuración o una configuración en línea. Devuelve un arreglo de proyectos de prueba resueltos.

// inyecta un solo proyecto con un alias personalizado
const newProjects = await injectTestProjects({
  // puedes heredar la configuración del proyecto actual referenciando `extends`
  // ten en cuenta que no puedes tener un proyecto con un nombre que ya exista,
  // por lo que es una buena práctica definir un nombre personalizado
  extends: project.vite.config.configFile,
  test: {
    name: 'my-custom-alias',
    alias: {
      customAlias: resolve('./custom-path.js'),
    },
  },
});

Proyectos filtrados

Vitest filtra los proyectos durante la resolución de la configuración, por lo que si el usuario definió un filtro, el proyecto inyectado podría no resolverse a menos que cumpla con el filtro. Puedes actualizar el filtro a través de la opción vitest.config.project para incluir siempre tu proyecto de prueba:

vitest.config.project.push('my-project-name');

Ten en cuenta que esto solo tendrá efecto en los proyectos inyectados con el método injectTestProjects.

Referenciando la configuración actual

Si quieres mantener la configuración del usuario, puedes especificar la propiedad extends. Todas las demás propiedades se fusionarán con la configuración definida por el usuario.

Se puede acceder al archivo de configuración (configFile) del proyecto en la configuración de Vite: project.vite.config.configFile.

Ten en cuenta que esto también heredará el nombre. Vitest no permite múltiples proyectos con el mismo nombre, por lo que esto lanzará un error. Asegúrate de especificar un nombre diferente. Puedes acceder al nombre actual mediante la propiedad project.name y todos los nombres utilizados están disponibles en el arreglo vitest.projects.