TestProject 3.0.0+

WARNING

Este guia descreve a API avançada do Node.js. Se você deseja apenas definir projetos, consulte o guia "Test Projects".

name

O nome é uma string única atribuída pelo usuário ou determinada pelo Vitest. Se o usuário não fornecer um nome, o Vitest tentará carregar um package.json na raiz do projeto e obterá a propriedade name a partir dele. Se não houver um package.json, o Vitest usará o nome da pasta por padrão. Projetos inline usam números como nomes (convertidos para string).

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // tem package.json com "@pkg/server"
      './utils', // não tem um arquivo package.json
      {
        // não personaliza o nome
        test: {
          pool: 'threads',
        },
      },
      {
        // personaliza o nome
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Se o projeto raiz não fizer parte dos projetos do usuário, seu name não será resolvido.

vitest

vitest referencia o processo global Vitest.

serializedConfig

Esta é a configuração recebida pelos processos de teste. O Vitest serializa a configuração manualmente, removendo todas as funções e propriedades que não são serializáveis. Como este valor está disponível tanto em testes quanto em nós, seu tipo é exportado do ponto de entrada principal.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

A propriedade serializedConfig é um getter. Sempre que é acessada, o Vitest serializa novamente a configuração, caso tenha sido alterada. Isso também significa que ela sempre retorna uma referência diferente:

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

A configuração de teste com a qual o Vitest foi inicializado. Se este for o projeto raiz, globalConfig e config farão referência ao mesmo objeto. Esta configuração é útil para valores que não podem ser definidos em nível de projeto, como coverage ou reporters.

import type { ResolvedConfig } from 'vitest/node';

vitest.config === vitest.projects[0].globalConfig;

config

Esta é a configuração de teste resolvida do projeto.

hash 3.2.0+

O hash único deste projeto. Este valor permanece consistente entre as reexecuções.

Ele é baseado na raiz do projeto e em seu nome. Observe que o caminho raiz não é consistente entre diferentes sistemas operacionais, então o hash também será diferente.

vite

Este é o ViteDevServer do projeto. Cada projeto tem seu próprio servidor Vite.

browser

Este valor só será definido se os testes estiverem sendo executados no navegador. Se browser estiver habilitado, mas os testes ainda não foram executados, o valor será undefined. Se você precisar verificar se o projeto suporta testes de navegador, use o método project.isBrowserEnabled().

WARNING

A API do navegador é ainda mais experimental e não segue o SemVer. A API do navegador será padronizada separadamente do restante das APIs.

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Um meio de fornecer valores personalizados para testes, além do campo config.provide. Todos os valores são validados com structuredClone antes de serem armazenados, mas os próprios valores em providedContext não são clonados.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

Os valores podem ser fornecidos de forma dinâmica. O valor fornecido nos testes será atualizado em sua próxima execução.

TIP

Este método também está disponível para arquivos de configuração global para situações em que a API pública não pode ser utilizada:

export default function setup({ provide }) {
  provide('wsPort', 3000);
}

getProvidedContext

function getProvidedContext(): ProvidedContext;

Isso retorna o objeto de contexto. Cada projeto também herda o contexto global definido por vitest.provide.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

Os valores de contexto do projeto sempre sobrescrevem o contexto do projeto raiz.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

Cria uma especificação de teste que pode ser usada em vitest.runTestSpecifications. A especificação delimita o arquivo de teste a um project específico e a locations de teste (opcional). As locations de teste são linhas de código onde o teste é definido no código-fonte. Se as locations forem fornecidas, o Vitest executará apenas os testes definidos nessas linhas. Observe que, se testNamePattern estiver definido, ele também será aplicado.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // linhas de teste opcionais
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification espera um ID de módulo resolvido. Ele não resolve o arquivo automaticamente nem verifica sua existência no sistema de arquivos.

Observe também que project.createSpecification sempre retorna uma nova instância.

isRootProject

function isRootProject(): boolean;

Verifica se o projeto atual é o projeto raiz. Você também pode obter o projeto raiz chamando vitest.getRootProject().

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Arquivos de teste que correspondem aos filtros.
   */
  testFiles: string[];
  /**
   * Arquivos de teste de verificação de tipo que correspondem aos filtros. Isso estará vazio, a menos que `typecheck.enabled` seja `true`.
   */
  typecheckTestFiles: string[];
};

Localiza todos os arquivos de teste. Esta função retorna um objeto com testes regulares e testes de verificação de tipo.

Este método aceita filters. Os filtros podem ser apenas uma porção do caminho do arquivo, diferentemente de outros métodos na instância Vitest:

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

O Vitest usa fast-glob para encontrar arquivos de teste. test.dir, test.root, root ou process.cwd() definem a opção cwd.

Este método leva em conta várias opções de configuração:

• test.include, test.exclude para encontrar arquivos de teste regulares
• test.includeSource, test.exclude para encontrar testes in-source
• test.typecheck.include, test.typecheck.exclude para encontrar testes de verificação de tipo

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

Este método verifica se o arquivo é um arquivo de testes comum. Ele usa as mesmas propriedades de configuração que globTestFiles usa para validação.

Este método também aceita um segundo parâmetro, que é o código-fonte. Isso é usado para validar se o arquivo é um teste in-source. Se você chamar este método várias vezes para diferentes projetos, é recomendável ler o arquivo uma vez e passá-lo diretamente como argumento. Se o arquivo não for um arquivo de teste, mas corresponder ao glob includeSource, o Vitest lerá o arquivo sincronamente, a menos que o source seja fornecido.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // true se `includeSource` estiver definido

import

function import<T>(moduleId: string): Promise<T>

Importa um arquivo usando o executor de módulos do Vite. O arquivo será transformado pelo Vite utilizando a configuração do projeto fornecido e executado em um contexto separado. Observe que moduleId será relativo a config.root.

DANGER

project.import reutiliza o grafo de módulos do Vite, então importar o mesmo módulo usando uma importação regular resultará em um módulo diferente:

import * as staticExample from './example.js';
const dynamicExample = await project.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

Internamente, o Vitest usa este método para importar configurações globais, provedores de cobertura personalizados e relatórios personalizados, significando que todos eles compartilham o mesmo grafo de módulos, desde que pertençam ao mesmo servidor Vite.

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Este é um atalho para project.vitest.onTestsRerun. Ele aceita um callback que será aguardado quando os testes forem agendados para reexecução (geralmente, devido a uma alteração de arquivo).

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Retorna true se este projeto executa testes no navegador.

close

function close(): Promise<void>;

Fecha o projeto e todos os recursos associados. Isso só pode ser chamado uma vez; a promessa de fechamento fica em cache até que o servidor seja reiniciado. Se os recursos forem novamente necessários, crie um novo projeto.

Em detalhes, este método fecha o servidor Vite, interrompe o serviço de verificação de tipo, fecha o navegador se estiver em execução, exclui o diretório temporário do código-fonte e redefine o contexto fornecido.