API de Plugin 3.1.0+

WARNING

Esta é uma API avançada. Se você deseja apenas executar testes, provavelmente não precisa dela. Ela é usada principalmente por autores de bibliotecas.

Este guia pressupõe que você saiba como trabalhar com plugins do Vite.

O Vitest suporta um hook experimental configureVitest para plugins desde a versão 3.1. Qualquer feedback sobre esta API é bem-vindo no 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

O Vitest reexporta todas as importações de tipo do Vite através de um namespace Vite, que você pode usar para manter suas versões sincronizadas. No entanto, se você estiver escrevendo um plugin para Vite e Vitest, pode continuar usando o tipo Plugin do ponto de entrada vite. Apenas certifique-se de que vitest/config esteja referenciado em algum lugar para que configureVitest seja estendido corretamente:

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

Ao contrário de reporter.onInit, este hook é executado no início do ciclo de vida do Vitest, permitindo alterações na configuração, como coverage e reporters. Uma mudança mais notável é a possibilidade de manipular a configuração global de um projeto de teste, caso seu plugin esteja definido no projeto e não na configuração global.

Contexto

project

O projeto de teste atual ao qual o plugin pertence.

Modo Navegador

Observe que, se você estiver dependendo de um recurso do navegador, o campo project.browser ainda não está definido. Use o evento reporter.onBrowserInit em vez disso.

vitest

A instância global do Vitest. Você pode alterar a configuração global modificando diretamente a propriedade vitest.config:

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

Configuração Resolvida

Observe que o Vitest já resolveu a configuração; portanto, alguns tipos podem ser diferentes da configuração usual do usuário. Isso também significa que algumas propriedades não serão resolvidas novamente, como setupFiles. Se você estiver adicionando novos arquivos, certifique-se de que eles sejam resolvidos primeiro.

Neste ponto, os reporters ainda não foram criados, então modificar vitest.reporters não terá efeito porque será sobrescrito. Se você precisar injetar seu próprio reporter, modifique a configuração.

injectTestProjects

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

Este método aceita uma configuração de projeto de teste, um caminho de arquivo de configuração ou uma configuração embutida. Ele retorna um array de projetos de teste resolvidos.

// injeta um único projeto com um alias personalizado
const newProjects = await injectTestProjects({
  // você pode herdar a configuração do projeto atual usando `extends`
  // observe que não é permitido ter um projeto com um nome já existente,
  // portanto, é uma boa prática definir um nome personalizado
  extends: project.vite.config.configFile,
  test: {
    name: 'my-custom-alias',
    alias: {
      customAlias: resolve('./custom-path.js'),
    },
  },
});

Projetos são Filtrados

O Vitest filtra projetos durante a resolução da configuração. Portanto, se o usuário definiu um filtro, o projeto injetado pode não ser resolvido, a menos que corresponda ao filtro. Você pode atualizar o filtro usando a opção vitest.config.project para sempre incluir seu projeto de teste:

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

Observe que isso afetará apenas os projetos injetados pelo método injectTestProjects.

Referenciando a Configuração Atual

Se você quiser preservar a configuração do usuário, pode especificar a propriedade extends. Todas as outras propriedades serão mescladas com a configuração do usuário.

O configFile do projeto pode ser acessado na configuração do Vite, em project.vite.config.configFile.

Observe que isso também herdará o name. O Vitest não permite vários projetos com o mesmo nome, o que gerará um erro. Certifique-se de especificar um nome diferente. Você pode acessar o nome atual através da propriedade project.name, e todos os nomes em uso estão disponíveis no array vitest.projects.