Configurando o Vitest

Configuração

O vitest lerá o seu arquivo vite.config.ts na raiz do projeto, caso ele exista, para corresponder aos plugins e configurações do seu aplicativo Vite. Se você deseja uma configuração diferente para testes ou se seu aplicativo principal não depende especificamente do Vite, você pode:

Criar um arquivo vitest.config.ts. Este terá maior prioridade e substituirá a configuração de vite.config.ts.
Passar a opção --config para a CLI, por exemplo: vitest --config ./path/to/vitest.config.ts.
Usar process.env.VITEST ou a propriedade mode em defineConfig (que será definida como test/benchmark se não for substituída) para aplicar condicionalmente uma configuração diferente em vite.config.ts.

Para configurar o próprio vitest, adicione a propriedade test à sua configuração do Vite. Se você estiver importando defineConfig do próprio vite, também precisará adicionar uma referência aos tipos do Vitest usando um comando de barra tripla no topo do seu arquivo de configuração.

Ao usar defineConfig do vite, você deve seguir este exemplo:

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

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

Ao usar defineConfig do vitest/config, você deve seguir este exemplo:

import { defineConfig } from 'vitest/config';

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

Você pode obter as opções padrão do Vitest para expandi-las, se necessário:

import { configDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    exclude: [...configDefaults.exclude, 'packages/template/*'],
  },
});

Ao usar um arquivo vitest.config.js separado, você também pode estender as opções do Vite a partir de outro arquivo de configuração, se necessário:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      exclude: ['packages/template/*'],
    },
  })
);

WARNING

O auxiliar mergeConfig está disponível no Vitest a partir da versão v0.30.0. Se você estiver usando uma versão inferior, pode importá-lo diretamente do vite.

Se a sua configuração do Vite for definida como uma função, você pode definir a configuração desta forma:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default defineConfig(configEnv =>
  mergeConfig(
    viteConfig(configEnv),
    defineConfig({
      test: {
        exclude: ['packages/template/*'],
      },
    })
  )
);

Opções

TIP

Além das opções a seguir, você também pode usar qualquer opção de configuração do Vite. Por exemplo, define para definir variáveis globais ou resolve.alias para definir aliases.

TIP

Todas as opções de configuração que não são suportadas dentro de uma configuração de projeto workspace possuem o sinal * ao lado.

include

Tipo: string[]
Padrão: ['**/*.{test,spec}.?(c|m)[jt]s?(x)']

Arquivos a serem incluídos na execução dos testes, utilizando padrões glob.

exclude

Tipo: string[]
Padrão: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*']

Arquivos a serem excluídos da execução dos testes, utilizando padrões glob.

includeSource

Tipo: string[]
Padrão: []

Inclui padrões glob para arquivos de teste in-source (incorporados ao código fonte).

Quando definido, o Vitest executará todos os arquivos que contenham import.meta.vitest.

server

Tipo: { sourcemap?, deps?, ... }
Versão: A partir do Vitest 0.34.0

Opções do servidor Vite-Node.

server.sourcemap

Tipo: 'inline' | boolean
Padrão: 'inline'

Injeta sourcemaps embutidos nos módulos.

server.debug

Tipo: { dumpModules?, loadDumppedModules? }

Opções de depuração do Vite-Node.

server.debug.dumpModules

Tipo: boolean | string

Salva o módulo transformado no sistema de arquivos. Ao passar uma string, o módulo será salvo no caminho especificado.

server.debug.loadDumppedModules

Tipo: boolean

Lê o módulo salvo no sistema de arquivos, caso ele exista. Útil para depurar, modificando o resultado salvo no sistema de arquivos.

server.deps

Tipo: { external?, inline?, ... }

Configurações para resolução de dependências.

server.deps.external

Tipo: (string | RegExp)[]
Padrão: [/\/node_modules\//]

Externalizar significa que o Vite não processará o pacote, delegando sua execução para o Node nativo.

As dependências externalizadas não passarão pelos transformadores e resolvedores do Vite e, portanto, não suportam HMR (Hot Module Replacement) durante o recarregamento. Por padrão, todos os pacotes dentro de node_modules são externalizados.

Essas opções aceitam nomes de pacotes da forma como estão definidos em node_modules ou especificados em deps.moduleDirectories. Por exemplo, o pacote @company/some-name localizado dentro de packages/some-name deve ser especificado como some-name, e packages deve ser incluído em deps.moduleDirectories. Basicamente, o Vitest sempre verifica o caminho do arquivo, não o nome real do pacote.

Se uma expressão regular for utilizada, o Vitest a aplicará ao caminho do arquivo, e não ao nome do pacote.

server.deps.inline

Tipo: (string | RegExp)[] | true
Padrão: []

O Vite processará módulos inline (incorporados). Isso pode ser útil para lidar com pacotes que distribuem arquivos .js no formato ESM, que o Node não consegue processar nativamente.

Se definido como true, todas as dependências serão incorporadas. Todas as dependências especificadas em ssr.noExternal serão inlined por padrão.

server.deps.fallbackCJS

Tipo boolean
Padrão: false

Quando uma dependência é um pacote ESM válido, o Vitest tentará identificar a versão CJS correspondente com base no caminho do arquivo. Isso pode ser útil caso uma dependência possua um arquivo ESM incorreto.

Isso pode causar inconsistências caso um pacote implemente lógicas diferentes para os formatos ESM e CJS.

server.deps.cacheDir

Tipo string
Padrão: 'node_modules/.vite'

Diretório para salvar arquivos de cache.

deps

Tipo: { optimizer?, registerNodeLoader?, ... }

Configurações para resolução de dependências.

deps.optimizer

Tipo: { ssr?, web? }
Versão: A partir do Vitest 0.34.0
Veja também: Opções de Otimização de Dependências

Habilita a otimização de dependências. Isso pode melhorar o desempenho dos seus testes, especialmente se você tiver muitas dependências. Em versões anteriores ao Vitest 0.34.0, essa opção era chamada deps.experimentalOptimizer.

Quando o Vitest encontra uma biblioteca externa listada em include, ela será agrupada em um único arquivo usando o esbuild e importada como um único módulo. Isso é vantajoso por vários motivos:

Importar pacotes com muitas importações pode ser custoso em termos de desempenho. Ao agrupá-los em um único arquivo, podemos economizar tempo.
Importar bibliotecas de UI pode ser custoso, pois elas geralmente não são projetadas para serem executadas diretamente no Node.js.
Sua configuração de alias agora será respeitada dentro dos pacotes agrupados.
O código dos seus testes será executado de forma mais similar ao ambiente do navegador.

Lembre-se de que apenas os pacotes especificados na opção deps.optimizer?.[mode].include serão agrupados (alguns plugins preenchem essa lista automaticamente, como o plugin do Svelte). Você pode encontrar mais informações sobre as opções disponíveis na documentação do Vite. O Vitest não oferece suporte às opções disable e noDiscovery. Por padrão, o Vitest utiliza optimizer.web para os ambientes jsdom e happy-dom, e optimizer.ssr para os ambientes node e edge. Essa configuração pode ser alterada através da opção transformMode.

Essas opções também herdam a sua configuração optimizeDeps (para o ambiente web, o Vitest estenderá a configuração optimizeDeps; para o ambiente SSR, será utilizada a configuração ssr.optimizeDeps). Se você redefinir as opções include ou exclude em deps.optimizer, elas serão mescladas com a sua configuração optimizeDeps durante a execução dos testes. O Vitest remove automaticamente as opções que aparecem tanto em include quanto em exclude, priorizando a exclusão.

TIP

Você não poderá editar o código dentro de node_modules para fins de depuração, pois o código em execução estará localizado no diretório cacheDir ou test.cache.dir. Se você precisar depurar utilizando instruções console.log, edite o código diretamente no diretório de cache ou force a reconstrução do pacote com a opção deps.optimizer?.[mode].force.

deps.optimizer.{mode}.enabled

Tipo: boolean
Padrão: true se estiver usando >= Vite 4.3.2, false caso contrário

Habilita a otimização de dependências.

WARNING

Esta opção funciona apenas com Vite 4.3.2 ou superior.

deps.web

Tipo: { transformAssets?, ... }
Versão: Desde Vite 0.34.2

Opções aplicadas a arquivos externos quando o modo de transformação é definido como web. Por padrão, os ambientes jsdom e happy-dom utilizam o modo web, enquanto os ambientes node e edge utilizam o modo de transformação ssr. Portanto, essas opções não terão efeito sobre os arquivos nesses últimos ambientes.

Normalmente, os arquivos dentro de node_modules são externalizados, mas essas opções também podem afetar os arquivos listados em server.deps.external.

deps.web.transformAssets

Tipo: boolean
Padrão: true

Determina se o Vitest deve processar arquivos de recursos (como .png, .svg, .jpg, etc.) e resolvê-los da mesma forma que o Vite faz no navegador.

Este módulo terá uma exportação padrão que corresponderá ao caminho do asset, a menos que uma consulta seja especificada.

WARNING

No momento, esta opção só funciona com o pool (grupo) experimentalVmThreads.

deps.web.transformCss

Tipo: boolean
Padrão: true

Determina se o Vitest deve processar arquivos CSS (como .css, .scss, .sass, etc.) e resolvê-los da mesma forma que o Vite faz no navegador.

Se o processamento de arquivos CSS estiver desativado através das opções css, esta opção apenas evitará que erros do tipo ERR_UNKNOWN_FILE_EXTENSION sejam exibidos.

WARNING

No momento, esta opção só funciona com o pool (grupo) experimentalVmThreads.

deps.web.transformGlobPattern

Tipo: RegExp | RegExp[]
Padrão: []

Padrão de expressão regular para identificar arquivos externos que devem ser transformados.

Por padrão, os arquivos dentro de node_modules são externalizados e não transformados, exceto se forem arquivos CSS ou recursos e a opção correspondente não estiver desativada.

WARNING

No momento, esta opção só funciona com o pool (grupo) experimentalVmThreads.

deps.registerNodeLoader*

Tipo: boolean
Padrão: false

Utiliza o carregador Node experimental para resolver importações dentro de arquivos externalizados, empregando o algoritmo de resolução do Vite.

Se desativado, as configurações de alias e <plugin>.resolveId não terão efeito sobre as importações dentro de pacotes externalizados (como os de node_modules, por padrão).

deps.interopDefault

Tipo: boolean
Padrão: true

Interpreta a exportação padrão de um módulo CJS como exportações nomeadas. Algumas dependências distribuem apenas módulos CJS e não utilizam exportações nomeadas, que o Node.js pode analisar estaticamente quando um pacote é importado com a sintaxe import em vez de require. Ao importar essas dependências no ambiente Node utilizando exportações nomeadas, você poderá encontrar o seguinte erro:

import { read } from 'fs-jetpack';
         ^^^^
SyntaxError: Named export 'read' not found. The requested module 'fs-jetpack' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export.

O Vitest não realiza análise estática e, portanto, não pode identificar esse tipo de problema antes da execução do código. Se este recurso estiver desativado, você provavelmente encontrará o erro a seguir ao executar os testes:

TypeError: createAsyncThunk is not a function
TypeError: default is not a function

Por padrão, o Vitest assume que você está utilizando um bundler para contornar essa limitação e, portanto, não reportará um erro. No entanto, você pode desativar esse comportamento manualmente caso o seu código não seja processado por um bundler.

deps.moduleDirectories

Tipo: string[]
Padrão: ['node_modules']

Uma lista de diretórios que devem ser considerados como diretórios de módulo. Esta opção de configuração afeta o comportamento de vi.mock. Quando nenhuma função de fábrica é fornecida e o caminho do módulo que você está mockando corresponde a um dos valores em moduleDirectories, o Vitest tentará encontrar o mock procurando por uma pasta __mocks__ na raiz do projeto.

Esta opção também influencia a forma como um arquivo é tratado ao externalizar dependências. Por padrão, o Vitest importa módulos externos utilizando o Node.js nativo, sem aplicar as transformações do Vite.

Definir esta opção irá substituir o valor padrão. Se você deseja continuar a pesquisar por pacotes em node_modules, inclua-o explicitamente na lista, juntamente com as outras opções:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    deps: {
      moduleDirectories: ['node_modules', path.resolve('../../packages')],
    },
  },
});

runner

Tipo: VitestRunnerConstructor
Padrão: node, ao executar testes, ou benchmark, ao executar benchmarks

Caminho para um executor de testes personalizado. Este é um recurso avançado e deve ser utilizado com executores de bibliotecas personalizadas. Você pode ler mais sobre isso na documentação.

benchmark

Tipo: { include?, exclude?, ... }

Opções utilizadas ao executar vitest bench.

benchmark.include

Tipo: string[]
Padrão: ['**/*.{bench,benchmark}.?(c|m)[jt]s?(x)']

Define padrões glob para incluir arquivos de teste de benchmark.

benchmark.exclude

Tipo: string[]
Padrão: ['node_modules', 'dist', '.idea', '.git', '.cache']

Define padrões glob para excluir arquivos de teste de benchmark.

benchmark.includeSource

Tipo: string[]
Padrão: []

Define padrões glob para incluir arquivos de teste de benchmark incorporados ao código fonte (in-source). Esta opção é similar a includeSource.

Quando definido, o Vitest executará todos os arquivos que contenham import.meta.vitest.

benchmark.reporters

Tipo: Arrayable<BenchmarkBuiltinReporters | Reporter>
Padrão: 'default'

Reporter personalizado para a saída dos resultados. Pode conter um ou mais nomes de relatórios integrados, instâncias de reporter e/ou caminhos para reporters personalizados.

benchmark.outputFile

Tipo: string | Record<string, string>

Salva os resultados do benchmark em um arquivo quando a opção --reporter=json também é especificada. Ao fornecer um objeto em vez de uma string, você pode definir arquivos de saída individuais para cada reporter.

Para fornecer um objeto via linha de comando (CLI), use a seguinte sintaxe: --outputFile.json=./path --outputFile.junit=./other-path.

alias

Tipo: Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

Define aliases personalizados para serem utilizados durante a execução dos testes. Esses aliases serão mesclados com os aliases definidos em resolve.alias.

globals

Tipo: boolean
Padrão: false
CLI: --globals, --globals=false

Por padrão, o vitest não disponibiliza APIs globais para garantir maior clareza no código. Se você preferir utilizar as APIs globalmente, como no Jest, você pode passar a opção --globals para a CLI ou adicionar globals: true na configuração.

// vite.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
  },
});

Para que o TypeScript reconheça as APIs globais, adicione vitest/globals ao campo types no seu arquivo tsconfig.json.

json

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Se você já estiver utilizando o unplugin-auto-import no seu projeto, você também pode utilizá-lo para importar automaticamente essas APIs.

// vite.config.ts
import { defineConfig } from 'vitest/config';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // (gera a declaração TypeScript)
    }),
  ],
});

environment

Tipo: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
Padrão: 'node'
CLI: --environment=<env>

Define o ambiente a ser utilizado para os testes. O ambiente padrão do Vitest é o Node.js. Para aplicações web, você pode usar um ambiente similar ao de um navegador com jsdom ou happy-dom. Para funções edge, utilize o ambiente edge-runtime.

Para especificar um ambiente diferente para um arquivo de teste, adicione um docblock @vitest-environment ou um comentário no topo do arquivo:

Estilo Docblock:

/**
 * @vitest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Estilo Comentário:

// @vitest-environment happy-dom

test('use happy-dom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Para compatibilidade com Jest, o @jest-environment também é suportado:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Se você executar o Vitest com a flag --threads=false, os testes serão executados nesta ordem: node, jsdom, happy-dom, edge-runtime, custom environments (ambientes personalizados). Isso garante que testes com o mesmo ambiente sejam agrupados e executados sequencialmente.

A partir da versão 0.23.0, você pode definir um ambiente personalizado. Quando um ambiente não nativo é utilizado, o Vitest tentará carregar o pacote vitest-environment-${name}. Este pacote deve exportar um objeto no formato de Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // custom setup (configuração personalizada)
    return {
      teardown() {
        // chamado após a execução de todos os testes neste ambiente
      },
    };
  },
};

O Vitest também expõe builtinEnvironments através da entrada vitest/environments, caso você queira estender um ambiente existente. Mais informações em nosso guia.

environmentOptions

Tipo: Record<'jsdom' | string, unknown>
Padrão: {}

Opções passadas para o método setup do environment atual. Por padrão, você pode configurar as opções do JSDOM, se este for o ambiente de teste.

environmentMatchGlobs

Tipo: [string, EnvironmentName][]
Padrão: []

Atribui automaticamente o ambiente com base em padrões glob. A primeira correspondência será utilizada.

Exemplo:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // todos os testes em tests/dom usarão jsdom
      ['tests/dom/**', 'jsdom'],
      // todos os testes em tests/ que terminam com .edge.test.ts usarão edge-runtime
      ['**/*.edge.test.ts', 'edge-runtime'],
      // ...
    ],
  },
});

poolMatchGlobs

Tipo: [string, 'threads' | 'child_process' | 'experimentalVmThreads'][]
Padrão: []
Versão: Desde Vitest 0.29.4

Atribui automaticamente o pool no qual os testes serão executados, com base em padrões glob. A primeira correspondência será utilizada.

Exemplo:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // todos os testes no diretório "worker-specific" serão executados dentro de um worker como se você tivesse habilitado `--threads` para eles
      ['**/tests/worker-specific/**', 'threads'],
      // execute todos os testes no diretório "browser" em um navegador real
      ['**/tests/browser/**', 'browser'],
      // todos os outros testes serão executados com base nas opções "browser.enabled" e "threads", se você não especificou outros globs
      // ...
    ],
  },
});

update*

Tipo: boolean
Padrão: false
CLI: -u, --update, --update=false

Atualiza os arquivos de snapshot. Isso atualizará todos os snapshots alterados e excluirá os obsoletos.

watch*

Tipo: boolean
Padrão: true
CLI: -w, --watch, --watch=false

Habilita o modo de observação (watch mode).

root

Tipo: string
CLI: -r <path>, --root=<path>

Diretório raiz do projeto.

reporters*

Tipo: Reporter | Reporter[]
Padrão: 'default'
CLI: --reporter=<name>, --reporter=<name1> --reporter=<name2>

Repórteres personalizados para a saída. Os repórteres podem ser uma instância de Reporter ou uma string para selecionar repórteres built-in (embutidos):

'default' - Agrupa as suites quando elas passam.
'basic' - Fornece um repórter similar ao repórter padrão na CI.
'verbose' - Mantém a árvore de tarefas completa visível.
'dot' - Mostra cada tarefa como um único ponto.
'junit' - Repórter JUnit XML (você pode configurar o nome da tag testsuites com a variável de ambiente VITEST_JUNIT_SUITE_NAME, e a propriedade da tag classname com VITEST_JUNIT_CLASSNAME).
'json' - Fornece um resumo JSON simples.
'html' - Gera um relatório HTML baseado em @vitest/ui.
'hanging-process' - Exibe uma lista de processos travados (hanging processes), se o Vitest não conseguir sair do processo com segurança. Esta pode ser uma operação pesada, habilite-a apenas se o Vitest consistentemente não conseguir sair do processo.
Caminho para um repórter customizado (ex: './path/to/reporter.ts', '@scope/reporter').

outputFile*

Tipo: string | Record<string, string>
CLI: --outputFile=<path>, --outputFile.json=./path

Escreve os resultados dos testes em um arquivo quando a opção --reporter=json, --reporter=html ou --reporter=junit também é especificada. Ao fornecer um objeto em vez de uma string, você pode definir saídas individuais ao usar múltiplos repórteres.

experimentalVmThreads

Tipo: boolean
CLI: --experimentalVmThreads, --experimental-vm-threads
Versão: Desde Vitest 0.34.0

Executa os testes utilizando contexto VM (dentro de um ambiente isolado) em um pool de workers.

Isso pode acelerar a execução dos testes, mas o módulo VM é instável ao executar código ESM. Seus testes podem apresentar vazamento de memória - para evitar isso, considere editar manualmente o valor de experimentalVmWorkerMemoryLimit.

WARNING

Executar código em um sandbox tem algumas vantagens (testes mais rápidos), mas também apresenta desvantagens.

Os globais dentro dos módulos nativos, como (fs, path, etc), diferem dos globais presentes em seu ambiente de teste. Como resultado, qualquer erro lançado por estes módulos nativos fará referência a um construtor de Error diferente em comparação com o utilizado em seu código:

try {
  fs.writeFileSync('/doesnt exist');
} catch (err) {
  console.log(err instanceof Error); // false
}

A importação de módulos ES os armazena em cache indefinidamente, o que introduz vazamentos de memória se você tiver muitos contextos (arquivos de teste). Não há API no Node.js que limpe esse cache.
Acessar globais leva mais tempo em um ambiente sandbox.

Esteja ciente desses problemas ao utilizar esta opção. A equipe do Vitest não pode corrigir nenhum dos problemas do nosso lado.

experimentalVmWorkerMemoryLimit

Tipo: string | number
CLI: --experimentalVmWorkerMemoryLimit, --experimental-vm-worker-memory-limit
Padrão: 1 / Número de núcleos da CPU
Versão: Desde Vitest 0.34.0

Especifica o limite de memória para os workers antes que sejam reciclados. Este valor depende muito do seu ambiente, portanto, é recomendável especificá-lo manualmente em vez de confiar no valor padrão.

Esta opção afeta apenas os workers que executam testes em contexto VM.

TIP

A implementação é baseada no workerIdleMemoryLimit do Jest.

O limite pode ser especificado de diversas maneiras diferentes e, independentemente do resultado, Math.floor é utilizado para convertê-lo em um valor inteiro:

<= 1 - O valor é considerado uma porcentagem da memória do sistema. Portanto, 0.5 define o limite de memória do worker para metade da memória total do sistema.
\> 1 - Considerado um valor de byte fixo. Devido à regra anterior, se você quisesse um valor de 1 byte (por algum motivo) você poderia usar 1.1.
Com unidades
- 50% - Como acima, uma porcentagem da memória total do sistema.
- 100KB, 65MB, etc - Com unidades para denotar um limite de memória fixo.
  - K / KB - Kilobytes (x1000)
  - KiB - Kibibytes (x1024)
  - M / MB - Megabytes
  - MiB - Mebibytes
  - G / GB - Gigabytes
  - GiB - Gibibytes

WARNING

O limite de memória baseado em porcentagem não funciona no Linux CircleCI workers devido à memória incorreta do sistema sendo relatada.

threads

Tipo: boolean
Padrão: true
CLI: --threads, --threads=false

Habilita multi-threading utilizando tinypool (um fork leve de Piscina). Antes do Vitest 0.29.0, o Vitest executava testes dentro de worker threads, mesmo que esta opção estivesse desabilitada. A partir da versão 0.29.0, se esta opção estiver desabilitada, o Vitest utiliza child_process para gerar um processo para executar os testes, o que significa que você pode utilizar process.chdir e outras APIs que não estavam disponíveis dentro dos workers. Se você quiser reverter ao comportamento anterior, use a opção --single-thread em vez disso.

Desabilitar esta opção faz com que todos os testes sejam executados dentro de múltiplos child processes.

singleThread

Tipo: boolean
Padrão: false
Versão: Desde Vitest 0.29.0

Executa todos os testes com o mesmo ambiente dentro de uma única worker thread. Isto desabilitará o isolamento de módulo built-in (seu código fonte ou código inlined ainda será reavaliado para cada teste), mas pode melhorar o desempenho dos testes. Antes do Vitest 0.29.0, isso era equivalente a usar --no-threads.

WARNING

Mesmo que esta opção force os testes a serem executados um após o outro, ela é diferente de --runInBand do Jest. O Vitest utiliza workers não apenas para executar testes em paralelo, mas também para fornecer isolamento. Ao desabilitar esta opção, seus testes serão executados sequencialmente, mas no mesmo contexto global, então você deve fornecer isolamento você mesmo.

Isso pode causar problemas se você estiver confiando no estado global (frameworks de front-end geralmente fazem) ou se seu código depende do ambiente para ser definido separadamente para cada teste. No entanto, pode representar uma melhoria de desempenho para seus testes (até 3 vezes mais rápido) que não dependem necessariamente do estado global ou podem facilmente contorná-lo.

maxThreads*

Tipo: number
Padrão: CPUs disponíveis

Número máximo de threads. Você também pode usar a variável de ambiente VITEST_MAX_THREADS.

minThreads*

Tipo: number
Padrão: CPUs disponíveis

Número mínimo de threads. Você também pode usar a variável de ambiente VITEST_MIN_THREADS.

useAtomics*

Tipo: boolean
Padrão: false
Versão: Desde Vitest 0.28.3

Utiliza Atomics para sincronizar threads.

Isso pode melhorar o desempenho em alguns casos, mas pode causar segfaults em versões mais antigas do Node.

testTimeout

Tipo: number
Padrão: 5000
CLI: --test-timeout=5000

Tempo limite padrão de um teste em milissegundos.

hookTimeout

Tipo: number
Padrão: 10000

Tempo limite padrão de um hook em milissegundos.

teardownTimeout*

Tipo: number
Padrão: 10000

Tempo limite padrão para esperar o encerramento quando o Vitest é desligado, em milissegundos.

silent*

Tipo: boolean
Padrão: false
CLI: --silent, --silent=false

Silencia a saída do console dos testes.

setupFiles

Tipo: string | string[]

Caminho para os arquivos de setup. Eles serão executados antes de cada arquivo de teste.

INFO

Alterar os arquivos de setup irá disparar a reexecução de todos os testes.

Você pode usar process.env.VITEST_POOL_ID (string semelhante a um inteiro) dentro do arquivo para distinguir entre threads (sempre será '1', se executado com threads: false).

TIP

Se você estiver executando --threads=false, este arquivo de setup será executado no mesmo escopo global diversas vezes. Isso significa que você está acessando o mesmo objeto global antes de cada teste, então certifique-se de não executar a mesma operação mais de uma vez.

Por exemplo, você pode confiar em uma variável global:

import { config } from '@some-testing-lib';

if (!globalThis.defined) {
  config.plugins = [myCoolPlugin];
  computeHeavyThing();
  globalThis.defined = true;
}

// hooks são reiniciados antes de cada suite
afterEach(() => {
  cleanup();
});

globalThis.resetBeforeEachTest = true;

globalSetup

Tipo: string | string[]

Caminho para arquivos de setup global, relativo à raiz do projeto.

Um arquivo de setup global pode exportar funções nomeadas setup e teardown ou uma função default que retorna uma função de teardown (exemplo).

INFO

Múltiplos arquivos globalSetup são permitidos. As funções setup e teardown são executadas sequencialmente, com teardown em ordem inversa.

WARNING

O setup global é executado em um escopo global diferente, então seus testes não têm acesso às variáveis definidas aqui.

watchExclude*

Tipo: string[]
Padrão: ['**/node_modules/**', '**/dist/**']

Padrão glob de caminhos de arquivo a serem ignorados para evitar a reexecução do watch.

forceRerunTriggers*

Tipo: string[]
Padrão: ['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']

Padrão glob de caminhos de arquivo que irão acionar a reexecução de toda a suite. Quando combinado com o argumento --changed, executará toda a suite de testes se o gatilho for encontrado no diff do git.

Útil se você estiver testando a chamada de comandos CLI, porque o Vite não pode construir um gráfico de módulo:

test('execute a script', async () => {
  // Vitest não pode reexecutar este teste, se o conteúdo de `dist/index.js` mudar
  await execa('node', ['dist/index.js']);
});

TIP

Certifique-se de que seus arquivos não sejam excluídos por watchExclude.

isolate

Tipo: boolean
Padrão: true
CLI: --isolate, --isolate=false

Isola o ambiente para cada arquivo de teste. Não funciona se você desabilitar a opção --threads.

Esta opção não afeta a opção experimentalVmThreads.

coverage*

Você pode usar v8, istanbul ou uma solução de cobertura customizada para coletar dados de cobertura.

Você pode fornecer opções de cobertura para a CLI usando a notação de ponto:

npx vitest --coverage.enabled --coverage.provider=istanbul --coverage.all

WARNING

Se você estiver usando opções de cobertura com notação de ponto, certifique-se de especificar --coverage.enabled. Não forneça apenas a opção --coverage nesse caso.

coverage.provider

Tipo: 'v8' | 'istanbul' | 'custom'
Padrão: 'v8'
CLI: --coverage.provider=<provider>

Use provider para selecionar a ferramenta de coleta de cobertura.

coverage.enabled

Tipo: boolean
Padrão: false
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.enabled, --coverage.enabled=false

Habilita a coleta de cobertura. Pode ser sobrescrito usando a opção de CLI --coverage.

coverage.include

Tipo: string[]
Padrão: ['**']
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.include=<path>, --coverage.include=<path1> --coverage.include=<path2>

Lista de arquivos a serem incluídos na cobertura, especificados como padrões globais.

coverage.extension

Tipo: string | string[]
Padrão: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.cts', '.tsx', '.jsx', '.vue', '.svelte']
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

coverage.exclude

Tipo: string[]
Padrão:

[
  'coverage/**',
  'dist/**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec}.?(c|m)[jt]s?(x)',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build}.config.*',
  '**/vitest.{workspace,projects}.[jt]s?(on)',
  '**/.{eslint,mocha,prettier}rc.{?(c|m)js,yml}',
];

Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.exclude=<path>, --coverage.exclude=<path1> --coverage.exclude=<path2>

Lista de arquivos a serem excluídos da cobertura, especificados como padrões globais.

coverage.all

Tipo: boolean
Padrão: false
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.all, --coverage.all=false

Determina se todos os arquivos, incluindo os não testados, devem ser incluídos no relatório.

coverage.clean

Tipo: boolean
Padrão: true
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.clean, --coverage.clean=false

Remove os resultados de cobertura anteriores antes de executar os testes.

coverage.cleanOnRerun

Tipo: boolean
Padrão: true
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

Limpa o relatório de cobertura ao reexecutar no modo de observação.

coverage.reportsDirectory

Tipo: string
Padrão: './coverage'
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.reportsDirectory=<path>

Diretório onde o relatório de cobertura será gravado.

coverage.reporter

Tipo: string | string[] | [string, {}][]
Padrão: ['text', 'html', 'clover', 'json']
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.reporter=<reporter>, --coverage.reporter=<reporter1> --coverage.reporter=<reporter2>

Repórteres de cobertura a serem usados. Consulte a documentação do istanbul para obter uma lista detalhada de todos os repórteres. Consulte @types/istanbul-reporter para obter detalhes sobre opções específicas do repórter.

O repórter pode ser configurado de três maneiras diferentes:

Um único repórter: { reporter: 'html' }
Vários repórteres sem opções: { reporter: ['html', 'json'] }

Um ou mais repórteres com opções:

{
  reporter: [
    ['lcov', { projectRoot: './src' }],
    ['json', { file: 'coverage.json' }],
    ['text'],
  ];
}

A partir do Vitest 0.31.0, você pode verificar seu relatório de cobertura na interface do Vitest: consulte Cobertura da interface do Vitest para obter mais detalhes.

coverage.reportOnFailure

Tipo: boolean
Padrão: false (a partir do Vitest 0.34.0)
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false
Versão: A partir do Vitest 0.31.2

Gera o relatório de cobertura mesmo quando os testes falham.

coverage.allowExternal

Tipo: boolean
Padrão: false
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.allowExternal, --coverage.allowExternal=false

Coleta a cobertura de arquivos fora da root do projeto.

coverage.skipFull

Tipo: boolean
Padrão: false
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.skipFull, --coverage.skipFull=false

Não exibe arquivos com 100% de cobertura de statements, branches e funções.

coverage.perFile

Tipo: boolean
Padrão: false
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.perFile, --coverage.perFile=false

Verifica os limites por arquivo. Consulte lines (linhas), functions (funções), branches e statements para os limites reais.

coverage.thresholdAutoUpdate

Tipo: boolean
Padrão: false
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.thresholdAutoUpdate=<boolean>

Atualiza os valores de limite lines (linhas), functions (funções), branches e statements no arquivo de configuração quando a cobertura atual estiver acima dos limites configurados. Esta opção ajuda a manter os limites quando a cobertura é aprimorada.

coverage.lines

Tipo: number
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.lines=<number>

Limite para linhas. Consulte a documentação do istanbul para obter mais informações.

coverage.functions

Tipo: number
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.functions=<number>

Limite para funções. Consulte a documentação do istanbul para obter mais informações.

coverage.branches

Tipo: number
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.branches=<number>

Limite para branches. Consulte a documentação do istanbul para obter mais informações.

coverage.statements

Tipo: number
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.statements=<number>

Limite para statements. Consulte a documentação do istanbul para obter mais informações.

coverage.100

Tipo: boolean
Padrão: false
Disponível para provedores: 'v8' | 'istanbul'
CLI: --coverage.100, --coverage.100=false

Atalho para --coverage.lines 100 --coverage.functions 100 --coverage.branches 100 --coverage.statements 100.

coverage.ignoreClassMethods

Tipo: string[]
Padrão: []
Disponível para provedores: 'istanbul'
CLI: --coverage.ignoreClassMethods=<method>

Define um array de nomes de métodos de classe para ignorar na cobertura. Consulte a documentação do istanbul para obter mais informações.

coverage.watermarks

Tipo:

{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}

Padrão:

{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}

Disponível para provedores: 'v8' | 'istanbul'

Limites de cobertura (watermarks) para statements, linhas, branches e funções. Consulte a documentação do istanbul para obter mais informações.

coverage.customProviderModule

Tipo: string
Disponível para provedores: 'custom'
CLI: --coverage.customProviderModule=<path or module name>

Especifica o nome do módulo ou o caminho para o módulo do provedor de cobertura customizado. Consulte Guia - Provedor de Cobertura Customizado para obter mais informações.

testNamePattern*

Tipo string | RegExp
CLI: -t <pattern>, --testNamePattern=<pattern>, --test-name-pattern=<pattern>

Executa testes cujos nomes completos correspondem ao padrão especificado. Se você adicionar OnlyRunThis a esta propriedade, os testes que não incluírem a palavra OnlyRunThis no nome serão ignorados.

import { expect, test } from 'vitest';

// run
test('OnlyRunThis', () => {
  expect(true).toBe(true);
});

// skipped
test('doNotRun', () => {
  expect(true).toBe(true);
});

open*

Tipo: boolean
Padrão: false
CLI: --open, --open=false

Abre a interface do Vitest (WIP).

api

Tipo: boolean | number
Padrão: false
CLI: --api, --api.port, --api.host, --api.strictPort

Inicia um servidor na porta especificada para a API. Quando definido como true, a porta padrão é 51204.

browser

Tipo: { enabled?, name?, provider?, headless?, api?, slowHijackESM? }
Padrão: { enabled: false, headless: process.env.CI, api: 63315 }
Versão: A partir do Vitest 0.29.4
CLI: --browser, --browser=<name>, --browser.name=chrome --browser.headless

Executa os testes do Vitest em um navegador. Usamos WebdriverIO para executar os testes por padrão, mas ele pode ser configurado com a opção browser.provider.

NOTE

Leia mais sobre testes em um navegador real na página do guia.

WARNING

Este é um recurso experimental. Alterações incompatíveis podem ocorrer sem seguir o versionamento semântico (semver); fixe a versão do Vitest ao usá-lo.

browser.enabled

Tipo: boolean
Padrão: false
CLI: --browser, --browser.enabled=false

Executa todos os testes dentro de um navegador por padrão. Pode ser substituído com a opção poolMatchGlobs.

browser.name

Tipo: string
CLI: --browser=safari

Executa todos os testes em um navegador específico. Opções possíveis em diferentes provedores:

webdriverio: firefox, chrome, edge, safari
playwright: firefox, webkit, chromium
custom: qualquer string que será passada para o provedor

browser.headless

Tipo: boolean
Padrão: process.env.CI
CLI: --browser.headless, --brower.headless=false

Executa o navegador no modo headless. Se você estiver executando o Vitest em CI, ele será habilitado por padrão.

browser.api

Tipo: number | { port?, strictPort?, host? }
Padrão: 63315
CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

Configura as opções para o servidor Vite que serve o código no navegador. Não afeta a opção test.api.

browser.provider

Tipo: 'webdriverio' | 'playwright' | string
Padrão: 'webdriverio'
CLI: --browser.provider=playwright

Caminho para um provedor que será usado ao executar testes no navegador. O Vitest fornece dois provedores: webdriverio (padrão) e playwright. Provedores customizados devem ser exportados usando a exportação default e ter este formato:

export interface BrowserProvider {
  name: string;
  getSupportedBrowsers(): readonly string[];
  initialize(ctx: Vitest, options: { browser: string }): Awaitable<void>;
  openPage(url: string): Awaitable<void>;
  close(): Awaitable<void>;
}

WARNING

Esta é uma API avançada para autores de bibliotecas. Se você só precisa executar testes em um navegador, use a opção browser.

browser.slowHijackESM

Tipo: boolean
Padrão: true
Versão: Disponível desde o Vitest 0.31.0

Ao executar testes no Node.js, o Vitest pode usar sua própria resolução de módulo para simular módulos facilmente com a sintaxe vi.mock. No entanto, replicar a resolução de módulo ES no navegador não é tão simples, então precisamos transformar seus arquivos de origem antes que o navegador possa utilizá-los.

Esta opção não afeta testes executados no Node.js.

Esta opção está habilitada por padrão no navegador. Se você não depende de espionar módulos ES com vi.spyOn e não usa vi.mock, você pode desativá-la para obter uma pequena melhoria no desempenho.

clearMocks

Tipo: boolean
Padrão: false

Chama .mockClear() em todos os spies antes de cada teste. Isso limpa o histórico de mock, mas não redefine sua implementação para a implementação padrão.

mockReset

Tipo: boolean
Padrão: false

Chama .mockReset() em todos os spies antes de cada teste. Isso limpa o histórico de mock e redefine sua implementação para uma função vazia (retornará undefined).

restoreMocks

Tipo: boolean
Padrão: false

Chama .mockRestore() em todos os spies antes de cada teste. Isso limpa o histórico de mock e redefine sua implementação para a original.

unstubEnvs

Tipo: boolean
Padrão: false
Versão: Disponível desde o Vitest 0.26.0

Chama vi.unstubAllEnvs antes de cada teste.

unstubGlobals

Tipo: boolean
Padrão: false
Versão: Disponível desde o Vitest 0.26.0

Chama vi.unstubAllGlobals antes de cada teste.

testTransformMode

Tipo: { web?, ssr? }
Versão: Disponível desde o Vitest 0.34.0

Determina o método de transformação para todos os módulos importados dentro de um teste que corresponda ao padrão glob. Por padrão, a configuração depende do ambiente de execução. Por exemplo, testes com ambiente JSDOM processarão todos os arquivos com a flag ssr: false e testes com ambiente Node processam todos os módulos com ssr: true.

testTransformMode.ssr

Tipo: string[]
Padrão: []

Utiliza o pipeline de transformação SSR para todos os módulos nos testes especificados.
Os plugins Vite receberão a flag ssr: true ao processar esses arquivos.

testTransformMode.web

Tipo: string[]
Padrão: []

Primeiro, executa um pipeline de transformação normal (direcionado ao navegador) e, em seguida, faz uma reescrita SSR para executar o código no Node.
Os plugins Vite receberão a flag ssr: false ao processar esses arquivos.

snapshotFormat*

Tipo: PrettyFormatOptions

Opções de formatação para testes de snapshot. Essas opções são passadas para pretty-format.

resolveSnapshotPath*

Tipo: (testPath: string, snapExtension: string) => string
Padrão: armazena arquivos de snapshot no diretório __snapshots__

Substitui o caminho padrão do snapshot. Por exemplo, para armazenar snapshots próximos aos arquivos de teste:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
  },
});

allowOnly

Tipo: boolean
Padrão: false
CLI: --allowOnly, --allowOnly=false

Permite testes e suites que são marcados como only.

dangerouslyIgnoreUnhandledErrors*

Tipo: boolean
Padrão: false
CLI: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

Ignora quaisquer erros não tratados que ocorram.

passWithNoTests*

Tipo: boolean
Padrão: false
CLI: --passWithNoTests, --passWithNoTests=false

O Vitest não falhará se não houver testes.

logHeapUsage

Tipo: boolean
Padrão: false
CLI: --logHeapUsage, --logHeapUsage=false

Mostra o uso de heap após cada teste. Útil para depurar vazamentos de memória.

css

Tipo: boolean | { include?, exclude?, modules? }

Define se o CSS deve ser processado. Quando excluídos, os arquivos CSS serão substituídos por strings vazias para evitar o processamento subsequente. Os Módulos CSS retornarão um proxy para não afetar o tempo de execução.

css.include

Tipo: RegExp | RegExp[]
Padrão: []

Padrão RegExp para arquivos que devem retornar CSS real e serão processados pelo pipeline Vite.

TIP

Para processar todos os arquivos CSS, use /.+/.

css.exclude

Tipo: RegExp | RegExp[]
Padrão: []

Padrão RegExp para arquivos que retornarão um arquivo CSS vazio.

css.modules

Tipo: { classNameStrategy? }
Padrão: {}

css.modules.classNameStrategy

Tipo: 'stable' | 'scoped' | 'non-scoped'
Padrão: 'stable'

Se você optar por processar arquivos CSS, poderá configurar se os nomes de classe dentro dos módulos CSS devem ter escopo. Você pode escolher uma das opções:

stable: os nomes de classe serão gerados como _${name}_${hashedFilename}, o que significa que a classe gerada permanecerá a mesma se o conteúdo CSS for alterado, mas mudará se o nome do arquivo for modificado ou o arquivo for movido para outra pasta. Esta configuração é útil se você usar o recurso de snapshot.
scoped: os nomes de classe serão gerados como de costume, respeitando o método css.modules.generateScopeName, se você tiver um e o processamento CSS estiver habilitado. Por padrão, o nome do arquivo será gerado como _${name}_${hash}, onde o hash inclui o nome do arquivo e o conteúdo do arquivo.
non-scoped: os nomes de classe não terão hash.

WARNING

Por padrão, o Vitest exporta um proxy, ignorando o processamento de Módulos CSS. Se você depende de propriedades CSS em suas classes, você deve habilitar o processamento CSS usando a opção include.

maxConcurrency

Tipo: number
Padrão: 5

O número de testes que podem ser executados simultaneamente e que estão marcados com test.concurrent.

Testes acima deste limite ficarão na fila até que haja disponibilidade.

cache*

Tipo: false | { dir? }

Opções para configurar a política de cache do Vitest. Atualmente, o Vitest armazena em cache os resultados dos testes para executar primeiro os testes mais longos e os que falharam.

cache.dir

Tipo: string
Padrão: node_modules/.vitest

Caminho para o diretório de cache.

sequence

Tipo: { sequencer?, shuffle?, seed?, hooks?, setupFiles? }

Opções para como os testes devem ser ordenados.

Você pode fornecer opções de sequência para a CLI com notação de ponto:

npx vitest --sequence.shuffle --sequence.seed=1000

sequence.sequencer*

Tipo: TestSequencerConstructor
Padrão: BaseSequencer

Uma classe personalizada que define métodos para particionamento (sharding) e ordenação. Você pode estender BaseSequencer de vitest/node, se você só precisa redefinir um dos métodos sort e shard, mas ambos devem existir.

O sharding acontece antes da ordenação, e somente se a opção --shard for fornecida.

sequence.shuffle

Tipo: boolean
Padrão: false
CLI: --sequence.shuffle, --sequence.shuffle=false

Se você deseja que os testes sejam executados aleatoriamente, pode habilitar essa opção ou usar o argumento CLI --sequence.shuffle.

O Vitest normalmente usa cache para ordenar os testes, fazendo com que os mais demorados sejam iniciados primeiro. Se seus testes forem executados em ordem aleatória, você perderá essa melhoria de desempenho, mas pode ser útil rastrear testes que dependem acidentalmente de outra execução anterior.

sequence.concurrent

Tipo: boolean
Padrão: false
CLI: --sequence.concurrent, --sequence.concurrent=false
Versão: Disponível desde o Vitest 0.32.2

Se você deseja que os testes sejam executados em paralelo, pode habilitar essa opção ou usar o argumento CLI --sequence.concurrent.

sequence.seed*

Tipo: number
Padrão: Date.now()
CLI: --sequence.seed=1000

Define a semente para randomização quando os testes são executados em ordem aleatória.

sequence.hooks

Tipo: 'stack' | 'list' | 'parallel'
Padrão: 'parallel'
CLI: --sequence.hooks=<value>

Altera a ordem de execução dos hooks.

stack irá ordenar os hooks "after" em ordem inversa, os hooks "before" serão executados na ordem em que foram definidos
list irá ordenar todos os hooks na ordem em que são definidos
parallel irá executar os hooks em um único grupo em paralelo (os hooks nas suites pai ainda serão executados antes dos hooks da suite atual)

sequence.setupFiles

Tipo: 'list' | 'parallel'
Padrão: 'parallel'
CLI: --sequence.setupFiles=<value>
Versão: Disponível desde o Vitest 0.29.3

Altera a ordem de execução dos arquivos de configuração.

list irá executar os arquivos de configuração na ordem em que são definidos
parallel irá executar os arquivos de configuração em paralelo

typecheck

Opções para configurar o ambiente de teste de verificação de tipo.

typecheck.checker

Tipo: 'tsc' | 'vue-tsc' | string
Padrão: tsc

Quais ferramentas usar para verificação de tipo. O Vitest irá gerar um processo com certos parâmetros para facilitar a análise, dependendo do tipo. O verificador (Checker) deve implementar o mesmo formato de saída que tsc.

Você precisa ter um pacote instalado para usar o typechecker:

tsc requer o pacote typescript
vue-tsc requer o pacote vue-tsc

Você também pode passar um caminho para um binário personalizado ou nome de comando que produz a mesma saída que tsc --noEmit --pretty false.

typecheck.include

Tipo: string[]
Padrão: ['**/*.{test,spec}-d.?(c|m)[jt]s?(x)']

Padrão glob para arquivos que devem ser tratados como arquivos de teste.

typecheck.exclude

Tipo: string[]
Padrão: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**']

Padrão glob para arquivos que não devem ser tratados como arquivos de teste.

typecheck.allowJs

Tipo: boolean
Padrão: false

Verifica arquivos JS que têm o comentário @ts-check. Se você o tiver habilitado no tsconfig, isso não o substituirá.

typecheck.ignoreSourceErrors

Tipo: boolean
Padrão: false

Não interrompe a execução se o Vitest encontrar erros fora dos arquivos de teste. Isso não mostrará erros que não estão relacionados aos testes.

Por padrão, se o Vitest encontrar um erro de origem, ele falhará na suíte de testes.

typecheck.tsconfig

Tipo: string
Padrão: tenta encontrar o tsconfig.json mais próximo da raiz do projeto

Caminho para o tsconfig personalizado, relativo à raiz do projeto.

slowTestThreshold*

Tipo: number
Padrão: 300

Tempo em milissegundos após o qual um teste é considerado lento e marcado nos resultados.

chaiConfig

Tipo: { includeStack?, showDiff?, truncateThreshold? }
Padrão: { includeStack: false, showDiff: true, truncateThreshold: 40 }
Versão: Disponível desde o Vitest 0.30.0

Equivalente à configuração do Chai.

chaiConfig.includeStack

Tipo: boolean
Padrão: false

Determina se o stack trace é incluído na mensagem de erro de Assertion. O padrão de false suprime o stack trace na mensagem de erro.

chaiConfig.showDiff

Tipo: boolean
Padrão: true

Determina se a flag showDiff deve ser incluída nos AssertionErrors lançados. false sempre será false; true será true quando a asserção tiver solicitado que uma diff seja mostrada.

chaiConfig.truncateThreshold

Tipo: number
Padrão: 40

Define o limite de comprimento para valores reais e esperados em erros de asserção. Se este limite for excedido, por exemplo, para grandes estruturas de dados, o valor é substituído por algo como [ Array(3) ] ou { Object (prop1, prop2) }. Defina-o como 0 se você quiser desativar o truncamento completamente.

Esta opção de configuração afeta o truncamento de valores em títulos test.each e dentro da mensagem de erro de asserção.

bail

Tipo: number
Padrão: 0
CLI: --bail=<value>
Versão: Disponível desde o Vitest 0.31.0

Interrompe a execução dos testes quando um determinado número de testes falhar.

Por padrão, o Vitest executará todos os seus casos de teste, mesmo que alguns deles falhem. Isso pode não ser desejado para builds de CI onde você está interessado apenas em builds 100% bem-sucedidos e gostaria de interromper a execução do teste o mais cedo possível quando ocorrerem falhas de teste. A opção bail pode ser usada para acelerar as execuções de CI, evitando a execução de mais testes quando ocorrerem falhas.

retry

Tipo: number
Padrão: 0
CLI: --retry=<value>
Versão: Disponível desde o Vitest 0.32.3

Repete o teste um número específico de vezes se ele falhar.

onConsoleLog

Tipo: (log: string, type: 'stdout' | 'stderr') => false | void

Handler personalizado para console.log nos testes. Se você retornar false, o Vitest não imprimirá o log no console.

Pode ser útil para filtrar as saídas de log de bibliotecas de terceiros.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
      if (log === 'message from third party library' && type === 'stdout')
        return false;
    },
  },
});

diff

Tipo: string
CLI: --diff=<value>
Versão: Disponível desde o Vitest 0.34.5

Caminho para um arquivo de configuração de diff que será usado para gerar a interface de diff. Útil se você quiser personalizar a exibição de diff.

vitest.diff.tsvitest.config.js

import type { DiffOptions } from 'vitest';
import c from 'picocolors';

export default {
  aIndicator: c.bold('--'),
  bIndicator: c.bold('++'),
  omitAnnotationLines: true,
} satisfies DiffOptions;

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    diff: './vitest.diff.ts',
  },
});

Configurando o Vitest ​

Configuração ​

Opções ​

include ​

exclude ​

includeSource ​

server ​

server.sourcemap ​

server.debug ​

server.debug.dumpModules ​

server.debug.loadDumppedModules ​

server.deps ​

server.deps.external ​

server.deps.inline ​

server.deps.fallbackCJS ​

server.deps.cacheDir ​

deps ​

deps.optimizer ​

deps.optimizer.{mode}.enabled ​

deps.web ​

deps.web.transformAssets ​

deps.web.transformCss ​

deps.web.transformGlobPattern ​

deps.registerNodeLoader* ​

deps.interopDefault ​

deps.moduleDirectories ​

runner ​

benchmark ​

benchmark.include ​

benchmark.exclude ​

benchmark.includeSource ​

benchmark.reporters ​

benchmark.outputFile ​

alias ​

globals ​

environment ​

environmentOptions ​

environmentMatchGlobs ​

poolMatchGlobs ​

update* ​

watch* ​

root ​

reporters* ​

outputFile* ​

experimentalVmThreads ​

experimentalVmWorkerMemoryLimit ​

threads ​

singleThread ​

maxThreads* ​

minThreads* ​

useAtomics* ​

testTimeout ​

hookTimeout ​

teardownTimeout* ​

silent* ​

setupFiles ​

globalSetup ​

watchExclude* ​

forceRerunTriggers* ​

isolate ​

coverage* ​

coverage.provider ​

coverage.enabled ​

coverage.include ​

coverage.extension ​

coverage.exclude ​

coverage.all ​

coverage.clean ​

coverage.cleanOnRerun ​

coverage.reportsDirectory ​

coverage.reporter ​

coverage.reportOnFailure ​

coverage.allowExternal ​

coverage.skipFull ​

coverage.perFile ​

coverage.thresholdAutoUpdate ​

coverage.lines ​

coverage.functions ​

coverage.branches ​

coverage.statements ​

Configurando o Vitest

Configuração

Opções

include

exclude

includeSource

server

server.sourcemap

server.debug

server.debug.dumpModules

server.debug.loadDumppedModules

server.deps

server.deps.external

server.deps.inline

server.deps.fallbackCJS

server.deps.cacheDir

deps

deps.optimizer

deps.optimizer.{mode}.enabled

deps.web

deps.web.transformAssets

deps.web.transformCss

deps.web.transformGlobPattern

deps.registerNodeLoader*

deps.interopDefault

deps.moduleDirectories

runner

benchmark

benchmark.include

benchmark.exclude

benchmark.includeSource

benchmark.reporters

benchmark.outputFile

alias

globals

environment

environmentOptions

environmentMatchGlobs

poolMatchGlobs

update*

watch*

root

reporters*

outputFile*

experimentalVmThreads

experimentalVmWorkerMemoryLimit

threads

singleThread

maxThreads*

minThreads*

useAtomics*

testTimeout

hookTimeout

teardownTimeout*

silent*

setupFiles

globalSetup

watchExclude*

forceRerunTriggers*

isolate

coverage*

coverage.provider

coverage.enabled

coverage.include

coverage.extension

coverage.exclude

coverage.all

coverage.clean

coverage.cleanOnRerun

coverage.reportsDirectory

coverage.reporter

coverage.reportOnFailure

coverage.allowExternal

coverage.skipFull

coverage.perFile

coverage.thresholdAutoUpdate

coverage.lines

coverage.functions

coverage.branches

coverage.statements