Configurando o Vitest

Se você estiver usando o Vite e tiver um arquivo vite.config, o Vitest o lerá para utilizar os mesmos plugins e configurações do seu aplicativo Vite. Se você quiser ter uma configuração diferente para testes ou se seu aplicativo principal não depender especificamente do Vite, você pode optar por:

• Criar vitest.config.ts, que terá a maior prioridade e substituirá a configuração de vite.config.ts (o Vitest suporta todas as extensões JS e TS convencionais, mas não suporta json). Isso significa que todas as opções em seu vite.config serão desconsideradas.
• Fornecer 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 (será definido como test/benchmark se não for substituído com --mode) para aplicar condicionalmente uma configuração diferente em vite.config.ts.

Para configurar o vitest em si, adicione a propriedade test à sua configuração do Vite. Você também precisará adicionar uma referência aos tipos do Vitest usando um comando de barra tripla no início do seu arquivo de configuração, caso esteja importando defineConfig do próprio vite.

Abrir Exemplos de Configuração

Ao usar defineConfig do vite, você deve seguir o seguinte:

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

export default defineConfig({
  test: {
    // ... Especifique as opções aqui.
  },
});

O <reference types="vitest" /> deixará de funcionar no Vitest 4, mas você já pode começar a migrar para vitest/config agora:

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

export default defineConfig({
  test: {
    // ... Especifique as opções aqui.
  },
});

Ao usar defineConfig de vitest/config, você deve seguir o seguinte:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ... Especifique as opções aqui.
  },
});

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

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

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

Ao usar um 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/*'],
    },
  })
);

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

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

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

WARNING

Todas as opções listadas nesta página estão localizadas dentro de uma propriedade test na configuração:

export default defineConfig({
  test: {
    exclude: [],
  },
});

Como o Vitest utiliza a configuração do Vite, 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 - essas opções devem ser definidas no nível superior, não dentro de uma propriedade test.

As opções de configuração que não são suportadas dentro de uma configuração de projeto têm o sinal * ao lado delas. Isso significa que elas só podem ser definidas na configuração raiz do Vitest.

include

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

Uma lista de padrões glob que correspondem aos seus arquivos de teste.

NOTA

Ao usar cobertura, o Vitest adiciona automaticamente padrões include de arquivos de teste aos padrões exclude padrão da cobertura. Veja coverage.exclude.

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,eslint,prettier}.config.*']
• CLI: vitest --exclude "**/excluded-file"

Uma lista de padrões glob que devem ser excluídos dos seus arquivos de teste.

WARNING

Esta opção não afeta a cobertura. Se você precisar remover certos arquivos do relatório de cobertura, use coverage.exclude.

Esta é a única opção que não substitui sua configuração se você a fornecer com uma flag CLI. Todos os padrões glob adicionados via flag --exclude serão adicionados ao exclude da configuração.

includeSource

• Tipo: string[]
• Padrão: []

Inclui globs para arquivos de teste in-source.

Quando definido, o Vitest executará todos os arquivos correspondentes com import.meta.vitest dentro.

name

• Tipo: string | { label: string, color?: LabelColor }

Atribui um nome personalizado ao projeto de teste ou ao processo Vitest. O nome será visível na CLI e na UI, e disponível na API Node.js via project.name.

A cor usada pela CLI e UI pode ser alterada fornecendo um objeto com a propriedade color.

server

• Tipo: { sourcemap?, deps?, ... }

Opções do servidor Vite-Node.

server.sourcemap

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

Injeta o mapa de origem inline nos módulos.

server.debug

• Tipo: { dumpModules?, loadDumppedModules? }

Opções do depurador Vite-Node.

server.debug.dumpModules

• Tipo: boolean | string

Despeja o módulo transformado no sistema de arquivos. Passar uma string despejará para o caminho especificado.

server.debug.loadDumppedModules

• Tipo: boolean

Lê o módulo despejado do sistema de arquivos sempre que existir. Útil para depuração, modificando o resultado do despejo do sistema de arquivos.

server.deps

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

Tratamento para a resolução de dependências.

server.deps.external

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

Externalizar significa que o Vite ignorará o pacote para o Node nativo. Dependências externalizadas não serão aplicadas aos transformadores e resolvedores do Vite, então elas não suportam HMR na recarga. Por padrão, todos os pacotes dentro de node_modules são externalizados.

Essas opções suportam nomes de pacotes como estão escritos em node_modules ou especificados dentro de 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 usada, o Vitest a aplica no caminho do arquivo, não no nome do pacote.

server.deps.inline

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

O Vite processará módulos embutidos. Isso pode ser útil para lidar com pacotes que enviam .js no formato ESM (que o Node não consegue lidar).

Se true, cada dependência será embutida. Todas as dependências, especificadas em ssr.noExternal serão embutidas por padrão.

server.deps.fallbackCJS

• Tipo boolean
• Padrão: false

Quando uma dependência é um pacote ESM válido, tenta adivinhar a versão cjs com base no caminho. Isso pode ser útil se uma dependência tiver o arquivo ESM errado.

Isso pode potencialmente causar inconsistências se um pacote tiver lógica diferente nos modos ESM e CJS.

server.deps.cacheDir

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

Diretório para salvar arquivos de cache.

deps

• Tipo: { optimizer?, ... }

Tratamento para a resolução de dependências.

deps.optimizer

• Tipo: { ssr?, web? }
• Veja também: Opções de Otimização de Dependências

Habilita a otimização de dependências. Se você tiver muitos testes, isso pode melhorar o desempenho deles.

Quando o Vitest encontra a biblioteca externa listada em include, ela será empacotada em um único arquivo usando esbuild e importada como um módulo completo. Isso é bom por várias razões:

• Importar pacotes com muitas importações é custoso. Ao empacotá-los em um único arquivo, podemos economizar muito tempo.
• Importar bibliotecas de UI demanda muitos recursos porque elas não foram feitas para rodar dentro do Node.js.
• Sua configuração de alias agora é respeitada dentro dos pacotes empacotados.
• O código em seus testes está rodando mais próximo de como ele roda no navegador.

Esteja ciente de que apenas os pacotes na opção deps.optimizer?.[mode].include são empacotados (alguns plugins preenchem isso automaticamente, como o Svelte). Você pode ler mais sobre as opções disponíveis na documentação do Vite (o Vitest não suporta as opções disable e noDiscovery). Por padrão, o Vitest utiliza optimizer.web para ambientes jsdom e happy-dom, e optimizer.ssr para ambientes node e edge, mas isso é configurável por transformMode.

Esta opção também herda sua configuração de optimizeDeps (para web o Vitest estenderá optimizeDeps, para ssr - ssr.optimizeDeps). Se você redefinir a opção include/exclude em deps.optimizer, ela estenderá seu optimizeDeps ao executar os testes. O Vitest remove automaticamente as mesmas opções de include, se elas estiverem listadas em exclude.

TIP

Você não poderá editar o código do seu node_modules para depuração, pois o código está realmente localizado em seu diretório cacheDir ou test.cache.dir. Se você quiser depurar com instruções console.log, edite-o diretamente ou force o reempacotamento com a opção deps.optimizer?.[mode].force.

deps.optimizer.{mode}.enabled

• Tipo: boolean
• Padrão: false

Habilita a otimização de dependências.

deps.web

• Tipo: { transformAssets?, ... }

Opções que são aplicadas a arquivos externos quando o modo de transformação é definido como web. Por padrão, os ambientes jsdom e happy-dom usam o modo web, enquanto os ambientes node e edge usam o modo de transformação ssr, então essas opções não terão efeito em arquivos dentro desses ambientes.

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

deps.web.transformAssets

• Tipo: boolean
• Padrão: true

O Vitest deve processar arquivos de ativos (.png, .svg, .jpg, etc.) e resolvê-los como o Vite faz no navegador.

Este módulo terá uma exportação padrão que corresponde ao caminho para o ativo, se nenhuma consulta for especificada.

WARNING

No momento, esta opção só funciona com os pools vmThreads e vmForks.

deps.web.transformCss

• Tipo: boolean
• Padrão: true

O Vitest deve processar arquivos CSS (.css, .scss, .sass, etc.) e resolvê-los como o Vite faz no navegador.

Se os arquivos CSS estiverem desabilitados com as opções css, esta opção apenas silenciará os erros ERR_UNKNOWN_FILE_EXTENSION.

WARNING

No momento, esta opção só funciona com os pools vmThreads e vmForks.

deps.web.transformGlobPattern

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

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

Por padrão, os arquivos dentro de node_modules são externalizados e não transformados, a menos que seja CSS ou um ativo, e a opção correspondente não esteja desabilitada.

WARNING

No momento, esta opção só funciona com os pools vmThreads e vmForks.

deps.interopDefault

• Tipo: boolean
• Padrão: true

Interpretar a exportação padrão de módulos 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 usando a sintaxe import em vez de require. Ao importar tais dependências em um ambiente Node usando exportações nomeadas, você verá este 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 faz análise estática e não consegue detectar falhas antes da execução do seu código, então você provavelmente verá este erro ao executar testes, se este recurso estiver desabilitado:

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

Por padrão, o Vitest assume que você está usando um bundler para contornar isso e não causará falhas, mas você pode desabilitar esse comportamento manualmente, se seu código não estiver sendo processado.

deps.moduleDirectories

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

Uma lista de diretórios que devem ser tratados como diretórios de módulo. Esta opção de configuração afeta o comportamento de vi.mock: quando nenhuma factory é fornecida e o caminho do módulo que você está simulando corresponde a um dos valores de moduleDirectories, o Vitest tentará resolver a simulação procurando por uma pasta __mocks__ na raiz do projeto.

Esta opção também afetará a forma como um arquivo é tratado como módulo ao externalizar dependências. Por padrão, o Vitest importa módulos externos diretamente com o Node.js nativo, ignorando a etapa de transformação do Vite.

Definir esta opção substituirá o padrão. Se você ainda quiser procurar pacotes em node_modules, certifique-se de incluí-lo junto com quaisquer 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 teste personalizado. Este é um recurso avançado e destina-se ao uso com executores de biblioteca personalizados. Você pode ler mais sobre isso na documentação.

benchmark

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

Opções usadas ao executar vitest bench.

benchmark.include

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

Inclui globs para arquivos de teste de benchmark.

benchmark.exclude

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

Exclui globs para arquivos de teste de benchmark.

benchmark.includeSource

• Tipo: string[]
• Padrão: []

Inclui globs para arquivos de teste de benchmark in-source. Esta opção é semelhante a includeSource.

Quando definido, o Vitest executará todos os arquivos correspondentes com import.meta.vitest dentro.

benchmark.reporters

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

Gerador de relatórios personalizado para saída. Pode conter um ou mais nomes de relatórios embutidos, instâncias de relatórios e/ou caminhos para relatórios personalizados.

benchmark.outputFile

Obsoleto em favor de benchmark.outputJson.

benchmark.outputJson

• Tipo: string | undefined
• Padrão: undefined

O caminho de um arquivo para armazenar o resultado do benchmark, que pode ser usado para a opção --compare posteriormente.

Por exemplo:

# salva o resultado do branch principal
git checkout main
vitest bench --outputJson main.json

# muda um branch e compara com o principal
git checkout feature
vitest bench --compare main.json

benchmark.compare

• Tipo: string | undefined
• Padrão: undefined

Um caminho de arquivo para um resultado de benchmark anterior para comparar com as execuções atuais.

alias

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

Define aliases personalizados ao executar dentro dos testes. Eles serão mesclados com os aliases de resolve.alias.

WARNING

O Vitest usa primitivas Vite SSR para executar testes que têm certas armadilhas.

1. Aliases afetam apenas módulos importados diretamente com uma palavra-chave import por meio de um módulo embutido (todo o código-fonte é embutido por padrão).
2. O Vitest não suporta aliases para chamadas require.
3. Se você estiver usando um alias para uma dependência externa (por exemplo, react -> preact), talvez queira criar um alias para os próprios pacotes node_modules para que funcione para dependências externalizadas. Tanto o Yarn quanto o pnpm suportam aliases através do prefixo npm:.

globals

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

Por padrão, o vitest não fornece APIs globais a fim de promover a explicitação. Se você preferir usar as APIs globalmente como o Jest, pode fornecer a opção --globals para a CLI ou adicionar globals: true na configuração.

import { defineConfig } from 'vitest/config';

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

Para habilitar o funcionamento do TypeScript com as APIs globais, adicione vitest/globals ao campo types em seu tsconfig.json

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Se você redefiniu seu typeRoots para incluir mais tipos em sua compilação, você terá que reincluir o node_modules para tornar vitest/globals detectável.

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types", "./node_modules"],
    "types": ["vitest/globals"]
  }
}

Se você já estiver usando unplugin-auto-import em seu projeto, você também pode usá-lo diretamente a fim de importar automaticamente essas APIs.

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

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

environment

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

O ambiente que será usado para testes. O ambiente padrão no Vitest é o Node.js. Se você estiver construindo um aplicativo web, pode usar um ambiente semelhante a um navegador por meio de jsdom ou happy-dom.

Se você estiver construindo edge functions (funções de borda), pode usar o ambiente edge-runtime.

TIP

Você também pode usar o Modo Navegador para executar testes de integração ou unidade no navegador sem simular o ambiente.

Ao adicionar um docblock ou comentário @vitest-environment no topo do arquivo, você pode especificar outro ambiente para ser utilizado em todos os testes nesse arquivo:

Estilo Docblock:

/**
 * @vitest-environment jsdom
 */

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

Estilo de 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 o Jest, também existe um @jest-environment:

/**
 * @jest-environment jsdom
 */

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

Se você estiver executando o Vitest com a flag --isolate=false, seus testes serão executados nesta ordem: node, jsdom, happy-dom, ambientes personalizados. Isso significa que cada teste com o mesmo ambiente é agrupado, mas ainda é executado sequencialmente.

A partir da versão 0.23.0, você também pode definir um ambiente personalizado. Quando um ambiente personalizado é usado, o Vitest tentará carregar o pacote vitest-environment-${name}. Esse pacote deve exportar um objeto com o formato de Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // configuração personalizada
    return {
      teardown() {
        // chamado depois que todos os testes com este ambiente foram executados
      },
    };
  },
};

O Vitest também expõe builtinEnvironments pelo ponto de entrada vitest/environments, caso você queira apenas estendê-lo. Você pode ler mais sobre como estender ambientes em nosso guia.

TIP

O ambiente jsdom expõe a variável global jsdom igual à instância atual do JSDOM. Se você quiser que o TypeScript a reconheça, você pode adicionar vitest/jsdom ao seu tsconfig.json quando usar este ambiente:

{
  "compilerOptions": {
    "types": ["vitest/jsdom"]
  }
}

environmentOptions

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

Essas opções são repassadas ao método setup do environment atual. Por padrão, você pode configurar apenas as opções do JSDOM, se estiver usando-o como ambiente de teste.

environmentMatchGlobs

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

DEPRECATED

Esta API foi descontinuada no Vitest 3. Use projetos para definir configurações diferentes.

export default defineConfig({
  test: {
    environmentMatchGlobs: [ 
      ['./*.jsdom.test.ts', 'jsdom'], 
    ], 
    projects: [ 
      { 
        extends: true, 
        test: { 
          environment: 'jsdom', 
        }, 
      }, 
    ], 
  },
})

Atribui automaticamente o ambiente com base em globs. A primeira correspondência será aplicada.

Por exemplo:

import { defineConfig } from 'vitest/config';

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

poolMatchGlobs

• Tipo: [string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]
• Padrão: []

DEPRECATED

Esta API foi descontinuada no Vitest 3. Use projetos para definir configurações diferentes:

export default defineConfig({
  test: {
    poolMatchGlobs: [ 
      ['./*.threads.test.ts', 'threads'], 
    ], 
    projects: [ 
      { 
        test: { 
          extends: true, 
          pool: 'threads', 
        }, 
      }, 
    ], 
  },
})

Atribui automaticamente o pool no qual os testes serão executados com base em globs. A primeira correspondência será usada.

Por 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 `--pool=threads` para eles,
      ['**/tests/worker-specific/**', 'threads'],
      // executa 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 arquivos de instantâneo. Isso atualizará todos os instantâneos alterados e excluirá os obsoletos.

watch*

• Tipo: boolean
• Padrão: !process.env.CI && process.stdin.isTTY
• CLI: -w, --watch, --watch=false

Habilita o modo de observação.

Em ambientes interativos, esta é a configuração padrão, a menos que --run seja especificado explicitamente.

Em CI, ou quando executado a partir de um shell não interativo, o modo "watch" não é a configuração padrão, mas pode ser habilitado explicitamente com esta flag.

watchTriggerPatterns 3.2.0+ *

• Tipo: WatcherTriggerPattern[]

O Vitest reexecuta os testes com base no grafo de módulos que é construído a partir de instruções import estáticas e dinâmicas. No entanto, se você estiver lendo do sistema de arquivos ou obtendo dados de um proxy, o Vitest não poderá detectar essas dependências.

Para reexecutar corretamente esses testes, você pode definir um padrão de regex e uma função que retorne a lista de arquivos de teste a serem executados.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    watchTriggerPatterns: [
      {
        pattern: /^src\/(mailers|templates)\/(.*)\.(ts|html|txt)$/,
        testToRun: (id, match) => {
          // relativo ao valor raiz
          return `./api/tests/mailers/${match[2]}.test.ts`;
        },
      },
    ],
  },
});

WARNING

Os arquivos retornados podem ser absolutos ou relativos à raiz. Observe que esta é uma opção global e não pode ser usada dentro de configurações de projeto.

root

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

Raiz do projeto

dir

• Tipo: string
• CLI: --dir=<path>
• Padrão: o mesmo que root

Diretório base para procurar por arquivos de teste. Você pode especificar esta opção para acelerar a descoberta de testes se sua raiz abrange todo o projeto.

reporters*

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

Relatores personalizados para saída. Os relatores podem ser uma instância de Reporter, uma string que representa um relator embutido, ou um caminho para uma implementação personalizada (por exemplo, './path/to/reporter.ts', '@scope/reporter').

outputFile*

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

Escreve os resultados do teste 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 caminhos de saída individuais ao usar vários relatores.

pool*

• Tipo: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
• Padrão: 'forks'
• CLI: --pool=threads

Pool usado para executar testes.

threads*

Habilita multi-threading usando tinypool (um fork leve de Piscina). Ao usar threads, você não consegue usar APIs relacionadas a processos, como process.chdir(). Algumas bibliotecas escritas em linguagens nativas, como Prisma, bcrypt e canvas, têm problemas ao serem executadas em vários threads e encontram falhas de segmentação. Nesses casos, é aconselhável usar o pool forks em vez disso.

forks*

Semelhante ao pool threads, mas usa child_process em vez de worker_threads via tinypool. A comunicação entre os testes e o processo principal é mais lenta do que com o pool threads. APIs relacionadas a processos, como process.chdir(), podem ser usadas no pool forks.

vmThreads*

Executa testes usando contexto VM (dentro de um ambiente sandbox) em um pool de threads.

Isso faz com que os testes sejam executados mais rapidamente, mas o módulo VM apresenta instabilidade ao executar código ESM. Seus testes podem vazar memória - para mitigar isso, considere editar manualmente o valor de poolOptions.vmThreads.memoryLimit.

WARNING

Executar código em um sandbox tem algumas vantagens (testes mais rápidos), mas também vem com uma série de desvantagens.

• As variáveis globais dentro de módulos nativos, como (fs, path, etc), diferem das globais presentes em seu ambiente de teste. Como resultado, qualquer erro lançado por esses módulos nativos apontará para um construtor de Erro diferente em comparação com o usado 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 causa vazamentos de memória se você tiver muitos contextos (arquivos de teste). Não há API no Node.js para limpar esse cache.
• O acesso a variáveis globais leva mais tempo em um ambiente sandbox.

Por favor, esteja ciente desses problemas ao usar esta opção. A equipe do Vitest não pode corrigir nenhum dos problemas internamente.

vmForks*

Semelhante ao pool vmThreads, mas usa child_process em vez de worker_threads via tinypool. A comunicação entre os testes e o processo principal não é tão rápida quanto com o pool vmThreads. APIs relacionadas a processos, como process.chdir(), estão disponíveis no pool vmForks. Esteja ciente de que este pool tem as mesmas armadilhas listadas em vmThreads.

poolOptions*

• Tipo: Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>
• Padrão: {}

poolOptions.threads

Opções para o pool threads.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // Opções relacionadas a threads aqui
      },
    },
  },
});

poolOptions.threads.maxThreads*

• Tipo: number | string
• Padrão: CPUs disponíveis

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

poolOptions.threads.minThreads*

• Tipo: number | string
• Padrão: CPUs disponíveis

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

poolOptions.threads.singleThread

• Tipo: boolean
• Padrão: false

Executa todos os testes com o mesmo ambiente em um único thread de worker. Isso desabilitará o isolamento de módulo integrado (seu código-fonte ou código embutido ainda será reavaliado para cada teste), mas pode melhorar o desempenho do teste.

WARNING

Embora esta opção force a execução sequencial dos testes, ela é diferente do --runInBand do Jest. O Vitest usa workers não apenas para executar testes em paralelo, mas também para garantir isolamento. Ao desabilitar esta opção, seus testes serão executados sequencialmente, mas no mesmo contexto global, então você precisará garantir o isolamento por conta própria.

Isso pode causar diversos problemas, se você estiver dependendo do estado global (frameworks frontend geralmente dependem) ou se seu código depender do ambiente para ser definido separadamente para cada teste. No entanto, pode acelerar significativamente seus testes (até 3 vezes mais rápido), especialmente aqueles que não dependem necessariamente do estado global ou que podem facilmente contornar essa dependência.

poolOptions.threads.useAtomics*

• Tipo: boolean
• Padrão: false

Usa Atomics para sincronizar threads.

Isso pode melhorar o desempenho em alguns casos, mas pode causar falha de segmentação em versões mais antigas do Node.

poolOptions.threads.isolate

• Type: boolean
• Default: true

Isola o ambiente para cada arquivo de teste.

poolOptions.threads.execArgv*

• Tipo: string[]
• Padrão: []

Passar argumentos adicionais para o node nos threads. Veja Command-line API | Node.js para mais informações.

WARNING

Tenha cuidado ao usar, pois algumas opções podem travar o worker, por exemplo, --prof, --title. Veja https://github.com/nodejs/node/issues/41103.

poolOptions.forks

Opções para o pool forks.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // Opções relacionadas a forks aqui
      },
    },
  },
});

poolOptions.forks.maxForks*

• Tipo: number | string
• Padrão: CPUs disponíveis

Número máximo ou porcentagem de forks. Você também pode usar a variável de ambiente VITEST_MAX_FORKS.

poolOptions.forks.minForks*

• Tipo: number | string
• Padrão: CPUs disponíveis

Número mínimo ou porcentagem de forks. Você também pode usar a variável de ambiente VITEST_MIN_FORKS.

poolOptions.forks.isolate

• Tipo: boolean
• Padrão: true

Isola o ambiente para cada arquivo de teste.

poolOptions.forks.singleFork

• Tipo: boolean
• Padrão: false

Executa todos os testes com o mesmo ambiente em um único processo filho. Isso desabilitará o isolamento de módulo integrado (seu código-source ou código embutido ainda será reavaliado para cada teste), mas pode melhorar o desempenho do teste.

WARNING

Embora esta opção force a execução sequencial dos testes, ela é diferente do --runInBand do Jest. O Vitest usa processos filhos não apenas para executar testes em paralelo, mas também para garantir isolamento. Ao desabilitar esta opção, seus testes serão executados sequencialmente, mas no mesmo contexto global, então você precisará garantir o isolamento por conta própria.

Isso pode causar diversos problemas, se você estiver dependendo do estado global (frameworks frontend geralmente dependem) ou se seu código depender do ambiente para ser definido separadamente para cada teste. No entanto, pode acelerar significativamente seus testes (até 3 vezes mais rápido), especialmente aqueles que não dependem necessariamente do estado global ou que podem facilmente contornar essa dependência.

poolOptions.forks.execArgv*

• Tipo: string[]
• Padrão: []

Passar argumentos adicionais para o processo node nos processos filhos. Veja Command-line API | Node.js para mais informações.

WARNING

Tenha cuidado ao usar, pois algumas opções podem travar o worker, por exemplo, --prof, --title. Veja https://github.com/nodejs/node/issues/41103.

poolOptions.vmThreads

Opções para o pool vmThreads.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // Opções relacionadas a threads VM aqui
      },
    },
  },
});

poolOptions.vmThreads.maxThreads*

• Tipo: number | string
• Padrão: CPUs disponíveis

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

poolOptions.vmThreads.minThreads*

• Tipo: number | string
• Padrão: CPUs disponíveis

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

poolOptions.vmThreads.memoryLimit*

• Tipo: string | number
• Padrão: 1 / CPU Cores

Especificar o limite de memória para os workers antes de serem reciclados. Este valor depende muito do seu ambiente, então é recomendável especificá-lo manualmente em vez de depender do padrão.

TIP

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

O limite pode ser especificado de várias maneiras e, independentemente do resultado, Math.floor é usado para transformá-lo em um valor inteiro:

• <= 1 - O valor é assumido como uma porcentagem da memória do sistema. Então, 0.5 define o limite de memória do worker como metade da memória total do sistema.
• \> 1 - Assumido como um valor fixo em bytes. Devido à regra anterior, se você quisesse um valor de 1 byte (por exemplo), 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 devido a relatos imprecisos da memória do sistema.

poolOptions.vmThreads.useAtomics*

• Tipo: boolean
• Padrão: false

Usa Atomics para sincronizar threads.

Isso pode melhorar o desempenho em alguns casos, mas pode causar falha de segmentação em versões mais antigas do Node.

poolOptions.vmThreads.execArgv*

• Tipo: string[]
• Padrão: []

Passar argumentos adicionais para o processo node no contexto da VM. Veja Command-line API | Node.js para mais informações.

WARNING

Tenha cuidado ao usar, pois algumas opções podem travar o worker, por exemplo, --prof, --title. Veja https://github.com/nodejs/node/issues/41103.

poolOptions.vmForks*

Opções para o pool vmForks.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // Opções relacionadas a forks VM aqui
      },
    },
  },
});

poolOptions.vmForks.maxForks*

• Tipo: number | string
• Padrão: CPUs disponíveis

Número máximo ou porcentagem de forks. Você também pode usar a variável de ambiente VITEST_MAX_FORKS.

poolOptions.vmForks.minForks*

• Tipo: number | string
• Padrão: CPUs disponíveis

Número mínimo ou porcentagem de forks. Você também pode usar a variável de ambiente VITEST_MIN_FORKS.

poolOptions.vmForks.memoryLimit*

• Tipo: string | number
• Padrão: 1 / CPU Cores

Especificar o limite de memória para os workers antes de serem reciclados. Este valor depende muito do seu ambiente, então é recomendável especificá-lo manualmente em vez de depender do padrão. Como o valor é calculado está descrito em poolOptions.vmThreads.memoryLimit.

poolOptions.vmForks.execArgv*

• Tipo: string[]
• Padrão: []

Passar argumentos adicionais para o processo node no contexto da VM. Veja Command-line API | Node.js para mais informações.

WARNING

Tenha cuidado ao usar, pois algumas opções podem travar o worker, por exemplo, --prof, --title. Veja https://github.com/nodejs/node/issues/41103.

fileParallelism*

• Tipo: boolean
• Padrão: true
• CLI: --no-file-parallelism, --fileParallelism=false

Define se todos os arquivos de teste devem ser executados em paralelo. Definir isso como false substituirá as opções maxWorkers e minWorkers para o valor 1.

TIP

Esta opção não afeta os testes que estão no mesmo arquivo. Se você quiser executá-los em paralelo, use a opção concurrent em describe ou através de uma configuração.

maxWorkers*

• Tipo: number | string

Número máximo ou porcentagem de workers para a execução de testes. poolOptions.{threads,vmThreads}.maxThreads/poolOptions.forks.maxForks tem prioridade maior.

minWorkers*

• Tipo: number | string

Número mínimo ou porcentagem de workers para a execução de testes. poolOptions.{threads,vmThreads}.minThreads/poolOptions.forks.minForks tem prioridade maior.

testTimeout

• Tipo: number
• Padrão: 5_000 no Node.js, 15_000 se browser.enabled for true
• CLI: --test-timeout=5000, --testTimeout=5000

Tempo limite padrão de um teste em milissegundos. Use 0 para desabilitar o tempo limite completamente.

hookTimeout

• Tipo: number
• Padrão: 10_000 no Node.js, 30_000 se browser.enabled for true
• CLI: --hook-timeout=10000, --hookTimeout=10000

Tempo limite padrão de um gancho em milissegundos. Use 0 para desabilitar o tempo limite completamente.

teardownTimeout*

• Tipo: number
• Padrão: 10000
• CLI: --teardown-timeout=5000, --teardownTimeout=5000

Tempo limite padrão de espera para o encerramento do Vitest, em milissegundos.

silent*

• Tipo: boolean | 'passed-only'
• Padrão: false
• CLI: --silent, --silent=false

Suprime a saída do console dos testes.

Use 'passed-only' para ver os logs apenas dos testes que falharam. Os logs dos testes que falharam são impressos ao final de cada teste.

setupFiles

• Tipo: string | string[]

Caminho para arquivos de configuração. Eles serão executados antes de cada arquivo de teste.

INFO

Editar um arquivo de configuração acionará automaticamente a reexecução de todos os testes.

Você pode usar process.env.VITEST_POOL_ID (string semelhante a um inteiro) para distinguir entre threads.

TIP

Observe que, se você estiver executando --isolate=false, este arquivo de configuração será executado múltiplas vezes no mesmo escopo global. Isso significa que você está acessando o mesmo objeto global antes de cada teste, então certifique-se de não executar operações redundantes.

Por exemplo, você pode depender de uma variável global:

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

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

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

globalThis.resetBeforeEachTest = true;

provide 2.1.0+

• Tipo: Partial<ProvidedContext>

Define valores que podem ser acessados dentro de seus testes usando o método inject.

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    provide: {
      API_KEY: '123',
    },
  },
});

api.test.js

import { expect, inject, test } from 'vitest';

test('api key is defined', () => {
  expect(inject('API_KEY')).toBe('123');
});

WARNING

As propriedades devem ser strings e os valores precisam ser serializáveis porque este objeto será transferido entre diferentes processos.

TIP

Se você estiver usando TypeScript, precisará aumentar o tipo ProvidedContext para acesso seguro ao tipo:

declare module 'vitest' {
  export interface ProvidedContext {
    API_KEY: string;
  }
}

// marca este arquivo como um módulo para que a ampliação funcione corretamente
export {};

globalSetup

• Tipo: string | string[]

Caminho para arquivos de configuração global, relativo à raiz do projeto.

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

INFO

Vários arquivos globalSetup são possíveis. setup e teardown são executados sequencialmente, sendo que o teardown é executado em ordem inversa.

WARNING

A configuração global só é executada se houver pelo menos um teste em execução. Isso significa que a configuração global pode começar a ser executada durante o modo de observação após a alteração de um arquivo de teste (o arquivo de teste aguardará a conclusão da configuração global antes de ser executado).

Atenção: a configuração global está sendo executada em um escopo global diferente, então seus testes não têm acesso às variáveis definidas aqui. No entanto, você pode disponibilizar dados serializáveis para os testes via método provide:

example.test.js

import { inject } from 'vitest';

inject('wsPort') === 3000;

globalSetup.ts 3.0.0+

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

export default function setup(project: TestProject) {
  project.provide('wsPort', 3000);
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

globalSetup.ts 2.0.0+

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

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

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

A partir do Vitest 3, você pode definir uma função de callback personalizada que será chamada quando o Vitest reexecutar os testes. Se a função for assíncrona, o Vitest aguardará sua conclusão antes de executar os testes. Observe que você não pode desestruturar a propriedade project como { onTestsRerun } porque ela depende do contexto.

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

export default function setup(project: TestProject) {
  project.onTestsRerun(async () => {
    await restartDb();
  });
}

forceRerunTriggers*

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

Padrão glob para caminhos de arquivo que acionarão a reexecução de toda a suíte. Quando combinado com o argumento --changed, executará toda a suíte de testes se o gatilho estiver presente no diff do git.

Útil se você estiver testando a execução de comandos CLI, porque o Vite não consegue construir um grafo de módulos:

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 server.watch.ignored.

coverage*

Você pode usar v8, istanbul ou uma solução de cobertura personalizada para coleta de cobertura.

Você pode fornecer opções de cobertura para a CLI usando 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, lembre-se de especificar --coverage.enabled. Evite fornecer uma única opção --coverage nesse caso.

coverage.provider

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

Use provider para selecionar a ferramenta para 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 substituído usando a opção 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 incluídos na cobertura como padrões glob.

coverage.extension

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

coverage.exclude

• Tipo: string[]
• Padrão:

[
  'coverage/**',
  'dist/**',
  '**/node_modules/**',
  '**/[.]**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec,bench,benchmark}?(-d).?(c|m)[jt]s?(x)',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.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 excluídos da cobertura definidos por padrões glob.

Esta opção substitui todas as opções padrão. Para adicionar novos padrões a serem ignorados, estenda as opções padrão:

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

export default defineConfig({
  test: {
    coverage: {
      exclude: ['**/custom-pattern/**', ...coverageConfigDefaults.exclude],
    },
  },
});

NOTA

O Vitest adiciona automaticamente os padrões include dos arquivos de teste ao coverage.exclude. A cobertura de arquivos de teste não pode ser exibida.

coverage.all

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

Define 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

Limpar os resultados da cobertura antes de executar os testes.

coverage.cleanOnRerun

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

Limpar o relatório de cobertura na reexecução do modo de observação. Defina como false para preservar os resultados de cobertura da execução anterior no modo de observação.

coverage.reportsDirectory

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

WARNING

O Vitest excluirá este diretório antes de executar os testes se coverage.clean estiver habilitado (valor padrão).

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

Para visualizar o relatório de cobertura na saída do relatório HTML, esta opção deve ser definida como um subdiretório do diretório do relatório HTML (por exemplo, ./html/coverage).

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>

Formatos de relatório de cobertura a serem usados. Veja a documentação do istanbul para uma lista detalhada de todos os relatores. Veja @types/istanbul-reporter para detalhes sobre opções específicas do relator.

O formato de relatório tem três tipos diferentes:

• Um único relator: { reporter: 'html' }
• Múltiplos relatores sem opções: { reporter: ['html', 'json'] }
• Um único ou múltiplos relatores com opções de relator:

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

Você também pode passar relatores de cobertura personalizados. Veja Guia - Relator de Cobertura Personalizado para mais informações.

{
  reporter: [
    // Especifica o relator usando o nome do pacote NPM
    '@vitest/custom-coverage-reporter',
    ['@vitest/custom-coverage-reporter', { someOption: true }],

    // Especifica o relator usando o caminho local
    '/absolute/path/to/custom-reporter.cjs',
    ['/absolute/path/to/custom-reporter.cjs', { someOption: true }],
  ];
}

Você pode verificar seu relatório de cobertura na UI do Vitest: consulte Cobertura da UI do Vitest para mais detalhes.

coverage.reportOnFailure

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

Gerar 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

Coletar cobertura de arquivos fora da raiz do projeto.

coverage.excludeAfterRemap 2.1.0+

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

Aplicar exclusões novamente depois que a cobertura foi remapeada para as fontes originais. Isso é útil quando seus arquivos de origem são transpilados e podem conter mapas de origem de arquivos que não são o código-fonte original.

Use esta opção quando arquivos aparecerem no relatório mesmo que correspondam aos seus padrões coverage.exclude.

coverage.skipFull

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

Não exibir arquivos com 100% de cobertura de declaração, branch e função.

coverage.thresholds

Opções para limites de cobertura.

Se um limite for definido como um número positivo, ele será interpretado como a porcentagem mínima de cobertura exigida. Por exemplo, definir o limite de linhas para 90 significa que 90% das linhas devem ser cobertas.

Se um limite for definido como um número negativo, ele será tratado como o número máximo de itens descobertos permitidos. Por exemplo, definir o limite de linhas para -10 significa que não mais de 10 linhas podem estar descobertas.

{
  coverage: {
    thresholds: {
      // Requer 90% de cobertura de função
      functions: 90,

      // Requer que não mais de 10 linhas estejam descobertas
      lines: -10,
    }
  }
}

coverage.thresholds.lines

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

Limite global de linhas.

coverage.thresholds.functions

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

Limite global de funções.

coverage.thresholds.branches

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

Limite global de branches.

coverage.thresholds.statements

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

Limite global de declarações.

coverage.thresholds.perFile

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

Verificar os limites por arquivo.

coverage.thresholds.autoUpdate

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

Atualizar todos os valores de limite lines, functions, branches e statements no arquivo de configuração quando a cobertura atual for melhor do que os limites configurados. Esta opção ajuda a manter os limites à medida que a cobertura é melhorada.

coverage.thresholds.100

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

Definir os limites globais para 100. Atalho para --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100.

coverage.thresholds[glob-pattern]

• Tipo: { statements?: number functions?: number branches?: number lines?: number }
• Padrão: undefined
• Disponível para provedores: 'v8' | 'istanbul'

Definir limites para arquivos que correspondem ao padrão glob.

NOTA

O Vitest conta todos os arquivos, incluindo aqueles cobertos por padrões glob, para os limites de cobertura globais. Isso difere do comportamento do Jest.

{
  coverage: {
    thresholds: {
      // Limites para todos os arquivos
      functions: 95,
      branches: 70,

      // Limites para o padrão glob correspondente
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // Arquivos que correspondem a este padrão terão apenas limites de linhas definidos.
      // Os limites globais não são herdados.
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

coverage.thresholds[glob-pattern].100 2.1.0+

• Tipo: boolean
• Padrão: false
• Disponível para provedores: 'v8' | 'istanbul'

Define os limites para 100 para arquivos que correspondem ao padrão glob.

{
  coverage: {
    thresholds: {
      // Limites para todos os arquivos
      functions: 95,
      branches: 70,

      // Limites para o padrão glob correspondente
      'src/utils/**.ts': { 100: true },
      '**/math.ts': { 100: true }
    }
  }
}

coverage.ignoreEmptyLines

• Tipo: boolean
• Padrão: true (false na v1)
• Disponível para provedores: 'v8'
• CLI: --coverage.ignoreEmptyLines=<boolean>

Ignorar linhas vazias, comentários e outros códigos não-runtime, por exemplo, tipos Typescript. Requer experimentalAstAwareRemapping: false.

Esta opção funciona apenas se o compilador usado remover os comentários e outros códigos não-runtime do código transpilado. Por padrão, o Vite usa o ESBuild que remove comentários e tipos Typescript de arquivos .ts, .tsx e .jsx.

Se você quiser aplicar o ESBuild a outros arquivos também, defina-os nas opções do esbuild:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  esbuild: {
    // Transpila todos os arquivos com ESBuild para remover comentários da cobertura de código.
    // Necessário para que `test.coverage.ignoreEmptyLines` funcione:
    include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      ignoreEmptyLines: true,
    },
  },
});

coverage.experimentalAstAwareRemapping

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

Remapear a cobertura com análise experimental baseada em AST. Fornece resultados mais precisos em comparação com o modo padrão.

coverage.ignoreClassMethods

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

Definir um array de nomes de métodos de classe a serem ignorados para cobertura. Veja a documentação do istanbul para 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'
• CLI: --coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80

Marcas d'água de declarações, linhas, branches e funções. Veja a documentação do istanbul para mais informações.

coverage.processingConcurrency

• Tipo: boolean
• Padrão: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
• Disponível para provedores: 'v8' | 'istanbul'
• CLI: --coverage.processingConcurrency=<number>

Limite de concorrência aplicado ao processar os resultados da cobertura.

coverage.customProviderModule

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

Especificar o nome do módulo ou caminho para o módulo do provedor de cobertura personalizado. Veja Guia - Provedor de Cobertura Personalizado para mais informações.

testNamePattern*

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

Executar testes com nomes completos que correspondem ao padrão. Se você adicionar OnlyRunThis a esta propriedade, os testes que não contiverem a palavra OnlyRunThis no nome do teste serão ignorados.

import { expect, test } from 'vitest';

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

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

open*

• Tipo: boolean
• Padrão: !process.env.CI
• CLI: --open, --open=false

Abrir a UI do Vitest (WIP)

api

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

Escuta a porta e disponibiliza a API. Quando definido como true, a porta padrão é 51204.

browser experimental

• Padrão: { enabled: false }
• CLI: --browser=<name>, --browser.name=chrome --browser.headless

Configura a execução de testes de navegador. Por favor, consulte o artigo "Referência de Configuração do Navegador".

WARNING

Este é um recurso experimental. Quebras de compatibilidade podem não seguir o SemVer, por favor, trave a versão do Vitest ao usá-lo.

clearMocks

• Tipo: boolean
• Padrão: false

Invoca .mockClear() em todos os espiões antes de cada teste. Isso limpará o histórico de simulações sem alterar as implementações de simulações.

mockReset

• Tipo: boolean
• Padrão: false

Invoca .mockReset() em todos os espiões antes de cada teste. Isso limpará o histórico de simulações e redefinirá cada implementação para sua original.

restoreMocks

• Tipo: boolean
• Padrão: false

Invoca .mockRestore() em todos os espiões antes de cada teste. Isso limpará o histórico de simulações, restaurará cada implementação para sua original e restaurará os descritores originais dos objetos espiados.

unstubEnvs

• Tipo: boolean
• Padrão: false

Invoca vi.unstubAllEnvs antes de cada teste.

unstubGlobals

• Tipo: boolean
• Padrão: false

Invoca vi.unstubAllGlobals antes de cada teste.

testTransformMode

• Tipo: { web?, ssr? }

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

testTransformMode.ssr

• Tipo: string[]
• Padrão: []

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

testTransformMode.web

• Tipo: string[]
• Padrão: []

Primeiramente, executa um pipeline de transformação normal (visando o navegador), depois executa uma reescrita SSR para executar o código no Node.
Os plugins do Vite receberão a flag ssr: false ao processar esses arquivos.

snapshotFormat*

• Tipo: PrettyFormatOptions

Opções de formato para os testes de instantâneo. Essas opções são passadas para pretty-format.

TIP

Atenção: o campo plugins neste objeto será ignorado.

Se você precisar estender o serializador de instantâneo via plugins pretty-format, por favor, use a API expect.addSnapshotSerializer ou a opção snapshotSerializers.

snapshotSerializers*

• Tipo: string[]
• Padrão: []

Uma lista de caminhos para módulos serializadores de instantâneo para teste de instantâneo, útil para adicionar serializadores de instantâneo personalizados. Veja Serializador Personalizado para mais informações.

resolveSnapshotPath*

• Tipo: (testPath: string, snapExtension: string, context: { config: SerializedConfig }) => string
• Padrão: armazena arquivos de instantâneo no diretório __snapshots__

Sobrescreve o caminho padrão do instantâneo. Por exemplo, para armazenar instantâneos ao lado dos arquivos de teste:

import { defineConfig } from 'vitest/config';

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

allowOnly

• Tipo: boolean
• Padrão: !process.env.CI
• CLI: --allowOnly, --allowOnly=false

Permitir testes e suítes que são marcados como "only".

dangerouslyIgnoreUnhandledErrors*

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

Ignorar quaisquer erros não tratados que ocorram.

passWithNoTests*

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

O Vitest não falhará caso nenhum teste seja encontrado.

logHeapUsage

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

Exibir o uso da heap após cada teste. Útil para depuração.

css

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

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

css.include

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

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

TIP

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

css.exclude

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

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

css.modules

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

css.modules.classNameStrategy

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

Se você decidir processar arquivos CSS, pode configurar a escopagem dos nomes de classe dentro dos módulos CSS. 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. Essa configuração é útil ao usar o recurso de instantâneo.
• scoped: os nomes de classe serão gerados como de costume, respeitando o método css.modules.generateScopedName, caso configurado e o processamento de CSS esteja 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 serão hashados.

WARNING

Por padrão, o Vitest exporta um proxy, que desabilita o processamento de Módulos CSS. Se você depende de propriedades CSS em suas classes, é necessário habilitar o processamento de CSS usando a opção include.

maxConcurrency

• Tipo: number
• Padrão: 5
• CLI: --max-concurrency=10, --maxConcurrency=10

O número de testes que podem ser executados simultaneamente, marcados com test.concurrent.

Testes acima deste limite serão enfileirados para serem executados quando houver um slot disponível.

cache*

• Tipo: false
• CLI: --no-cache, --cache=false

Use esta opção para desabilitar o recurso de cache. No momento, o Vitest armazena o cache dos resultados dos testes a fim de priorizar a execução dos testes mais demorados e dos que falharam.

O diretório de cache é controlado pela opção cacheDir do Vite:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: 'custom-folder/.vitest',
});

Você pode limitar o diretório apenas para o Vitest usando process.env.VITEST:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: process.env.VITEST ? 'custom-folder/.vitest' : undefined,
});

sequence

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

Opções para a ordenação dos testes.

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 fragmentação (sharding) e ordenação. Você pode estender BaseSequencer de vitest/node, se precisar apenas redefinir um dos métodos sort e shard, mas ambos devem existir.

A fragmentação (sharding) ocorre antes da ordenação, e somente se a opção --shard for fornecida.

Se sequencer.groupOrder for especificado, o sequenciador será invocado uma vez para cada grupo e pool.

groupOrder 3.2.0+

• Tipo: number
• Padrão: 0

Controla a ordem em que este projeto executa seus testes ao usar vários projetos.

• Projetos com o mesmo número de ordem de grupo serão executados simultaneamente, e os grupos são executados do menor para o maior.
• Se você não definir esta opção, todos os projetos executam em paralelo.
• Se vários projetos usarem a mesma ordem de grupo, eles serão executados simultaneamente.

Esta configuração afeta apenas a ordem de execução dos projetos, não a ordem dos testes dentro de um projeto. Para controlar o isolamento de testes ou a ordem dos testes dentro de um projeto, utilize as opções isolate e sequence.sequencer.

Exemplo

Considere este exemplo:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'slow',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'fast',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'flaky',
          sequence: {
            groupOrder: 1,
          },
        },
      },
    ],
  },
});

Os testes nesses projetos serão executados nesta ordem:

 0. lento  |
           |> executando juntos
 0. rápido |

 1. instável |> executa depois de lento e rápido, sozinho

sequence.shuffle

• Tipo: boolean | { files?, tests? }
• Padrão: false
• CLI: --sequence.shuffle, --sequence.shuffle=false

Se você quiser que arquivos e testes sejam executados aleatoriamente, você pode habilitar isso através desta opção ou do argumento CLI --sequence.shuffle.

O Vitest geralmente usa cache para ordenar os testes, permitindo que testes mais demorados iniciem antes - isso faz com que os testes sejam executados mais rapidamente. Se seus arquivos e testes forem executados em ordem aleatória, você perderá essa melhoria de desempenho, mas pode ser útil para rastrear testes que acidentalmente dependem de testes executados anteriormente.

sequence.shuffle.files

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

Define se os arquivos devem ser randomizados. Observe que testes de longa duração não começarão mais cedo se você habilitar esta opção.

sequence.shuffle.tests

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

Define se os testes devem ser randomizados.

sequence.concurrent

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

Se você quiser que os testes sejam executados em paralelo, você pode habilitar isso através desta opção ou do argumento CLI --sequence.concurrent.

sequence.seed*

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

Definir a semente de randomização, se os testes estiverem sendo executados em ordem aleatória.

sequence.hooks

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

Alterar a ordem em que os ganchos são executados.

• stack executará os ganchos "after" em ordem inversa, os ganchos "before" serão executados na ordem em que foram definidos
• list executará todos os ganchos na ordem em que são definidos
• parallel executa os ganchos em um único grupo em paralelo (os ganchos em suítes pai ainda serão executados antes dos ganchos da suíte atual)

TIP

Esta opção não afeta onTestFinished. Ela é sempre chamada em ordem inversa.

sequence.setupFiles

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

Alterar a ordem em que os arquivos de configuração são executados.

• list executa os arquivos de configuração na ordem em que são definidos
• parallel executa os arquivos de configuração em paralelo

typecheck

Opções para configurar o ambiente de teste de checagem de tipos.

typecheck.enabled

• Tipo: boolean
• Padrão: false
• CLI: --typecheck, --typecheck.enabled

Habilitar a verificação de tipo junto com seus testes regulares.

typecheck.only

• Tipo: boolean
• Padrão: false
• CLI: --typecheck.only

Executar apenas testes de verificação de tipo, quando a verificação de tipo está habilitada. Ao usar a CLI, esta opção habilitará automaticamente a verificação de tipo.

typecheck.checker

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

Ferramentas a serem usadas para verificação de tipo. O Vitest irá iniciar um processo com certos parâmetros para facilitar a análise, dependendo do tipo. O verificador deve seguir o mesmo formato de saída que tsc.

É necessário ter um pacote instalado para usar o verificador de tipo:

• 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 produza 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 serão considerados 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 serão considerados arquivos de teste.

typecheck.allowJs

• Tipo: boolean
• Padrão: false

Verificar arquivos JS que possuem o comentário @ts-check. Se você tiver isso habilitado no tsconfig, esta opção não o sobrescreverá.

typecheck.ignoreSourceErrors

• Tipo: boolean
• Padrão: false

Não falhar se o Vitest encontrar erros fora dos arquivos de teste. Isso não exibirá nenhum erro não relacionado a testes.

Por padrão, se o Vitest encontrar um erro de origem, ele causará a falha da suíte de testes.

typecheck.tsconfig

• Tipo: string
• Padrão: tenta encontrar o tsconfig.json mais próximo

O caminho para um tsconfig personalizado, relativo à raiz do projeto.

typecheck.spawnTimeout

• Tipo: number
• Padrão: 10_000

Tempo mínimo em milissegundos necessário para iniciar o verificador de tipo.

slowTestThreshold*

• Tipo: number
• Padrão: 300
• CLI: --slow-test-threshold=<number>, --slowTestThreshold=<number>

O número de milissegundos após o qual um teste ou suíte é considerado lento e assim reportado nos resultados.

chaiConfig

• Tipo: { includeStack?, showDiff?, truncateThreshold? }
• Padrão: { includeStack: false, showDiff: true, truncateThreshold: 40 }

Equivalente a Chai config.

chaiConfig.includeStack

• Tipo: boolean
• Padrão: false

Determina se o rastreamento de pilha é incluído na mensagem de erro de Asserção. O padrão false suprime o rastreamento de pilha 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 a exibição de um diff.

chaiConfig.truncateThreshold

• Tipo: number
• Padrão: 40

Definir o limite de comprimento para valores reais e esperados em erros de asserção. Se esse limite for excedido, por exemplo, em grandes estruturas de dados, o valor é substituído por algo como [ Array(3) ] ou { Object (prop1, prop2) }. Defina-o como 0 para desabilitar 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>

Interromper a execução do teste quando um determinado número de testes falhou.

Por padrão, o Vitest executa todos os seus casos de teste, mesmo que alguns deles falhem. Isso pode não ser desejado para builds de CI, onde o foco é em builds 100% bem-sucedidos e se deseja 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 que mais testes sejam executados quando falhas tiverem ocorrido.

retry

• Tipo: number
• Padrão: 0
• CLI: --retry=<value>

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

onConsoleLog*

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

Função de tratamento personalizada para console.log em testes. Se você retornar false, o Vitest não exibirá o log no console.

Pode ser útil para filtrar logs de bibliotecas de terceiros.

import { defineConfig } from 'vitest/config';

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

onStackTrace*

• Tipo: (error: Error, frame: ParsedStack) => boolean | void

Aplicar uma função de filtragem a cada quadro de cada rastreamento de pilha ao lidar com erros. O primeiro argumento, error, é um objeto com as mesmas propriedades de um Error padrão, mas não se trata de uma instância real.

Pode ser útil para filtrar frames de rastreamento de pilha de bibliotecas de terceiros.

import type { ParsedStack } from 'vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onStackTrace(error: Error, { file }: ParsedStack): boolean | void {
      // Se for encontrado um ReferenceError, exibir toda a pilha.
      if (error.name === 'ReferenceError') {
        return;
      }

      // Rejeitar todos os quadros de bibliotecas de terceiros.
      if (file.includes('node_modules')) {
        return false;
      }
    },
  },
});

diff

• Tipo: string
• CLI: --diff=<path>

Objeto DiffOptions ou um caminho para um módulo que exporte DiffOptions. Útil para personalizar a exibição do diff.

Por exemplo, como um objeto de configuração:

import { defineConfig } from 'vitest/config';
import c from 'picocolors';

export default defineConfig({
  test: {
    diff: {
      aIndicator: c.bold('--'),
      bIndicator: c.bold('++'),
      omitAnnotationLines: true,
    },
  },
});

Ou como um módulo:

vitest.config.js

import { defineConfig } from 'vitest/config';

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

vitest.diff.ts

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

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

diff.expand

• Tipo: boolean
• Padrão: true
• CLI: --diff.expand=false

Expandir todas as linhas comuns.

diff.truncateThreshold

• Tipo: number
• Padrão: 0
• CLI: --diff.truncateThreshold=<path>

O comprimento máximo do resultado do diff para exibição. Diffs acima deste limite serão encurtados. O truncamento não será aplicado com o valor padrão 0.

diff.truncateAnnotation

• Tipo: string
• Padrão: '... O resultado do diff foi truncado'
• CLI: --diff.truncateAnnotation=<annotation>

Anotação exibida no final do resultado do diff se ele for truncado.

diff.truncateAnnotationColor

• Tipo: DiffOptionsColor = (arg: string) => string
• Padrão: noColor = (string: string): string => string

Cor da anotação de truncamento; por padrão, a saída não terá cor.

diff.printBasicPrototype

• Tipo: boolean
• Padrão: false

Imprimir o protótipo básico Object e Array na saída do diff.

diff.maxDepth

• Tipo: number
• Padrão: 20 (ou 8 ao comparar tipos diferentes)

Limitar a profundidade de recursão ao imprimir objetos aninhados.

fakeTimers

• Tipo: FakeTimerInstallOpts

Opções que o Vitest repassará para @sinon/fake-timers ao usar vi.useFakeTimers().

fakeTimers.now

• Tipo: number | Date
• Padrão: Date.now()

Instalar temporizadores falsos com a época Unix especificada.

fakeTimers.toFake

• Tipo: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]
• Padrão: tudo disponível globalmente, exceto nextTick e queueMicrotask

Um array com nomes de métodos e APIs globais a serem simulados.

Para simular apenas setTimeout() e nextTick(), especifique esta propriedade como ['setTimeout', 'nextTick'].

Não há suporte para a simulação de nextTick ao executar o Vitest dentro de node:child_process usando --pool=forks. O NodeJS usa process.nextTick internamente em node:child_process e pode travar quando é simulado. A simulação de nextTick é suportada ao executar o Vitest com --pool=threads.

fakeTimers.loopLimit

• Tipo: number
• Padrão: 10_000

O número máximo de temporizadores a serem executados ao chamar vi.runAllTimers().

fakeTimers.shouldAdvanceTime

• Tipo: boolean
• Padrão: false

Instrui o @sinonjs/fake-timers a incrementar o tempo simulado automaticamente com base na variação do tempo real do sistema (por exemplo, o tempo simulado será incrementado em 20ms para cada mudança de 20ms no tempo real do sistema).

fakeTimers.advanceTimeDelta

• Tipo: number
• Padrão: 20

Relevante apenas quando usado com shouldAdvanceTime: true. Incrementar o tempo simulado em advanceTimeDelta ms a cada advanceTimeDelta ms de mudança no tempo real do sistema.

fakeTimers.shouldClearNativeTimers

• Tipo: boolean
• Padrão: true

Instrui os temporizadores falsos a limpar os temporizadores "nativos" (ou seja, não falsos) delegando aos seus respectivos manipuladores. Quando desabilitado, pode levar a um comportamento potencialmente inesperado se os temporizadores já existiam antes de iniciar a sessão de temporizadores falsos.

workspace*

DEPRECATED

Esta opção está obsoleta e será removida na próxima versão principal. Por favor, use projects em vez disso.

• Tipo: string | TestProjectConfiguration[]
• CLI: --workspace=./file.js
• Padrão: vitest.{workspace,projects}.{js,ts,json} próximo ao arquivo de configuração ou raiz

O caminho para um arquivo de configuração de workspace relativo à raiz.

A partir do Vitest 3, você também pode definir o array de workspace na configuração raiz. Se o workspace for definido na configuração manualmente, o Vitest desconsiderará o arquivo vitest.workspace na raiz.

projects*

• Tipo: TestProjectConfiguration[]
• Padrão: []

Um array de projetos.

isolate

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

Executar testes em um ambiente isolado. Esta opção não afeta os pools vmThreads e vmForks.

Desabilitar esta opção pode melhorar o desempenho se seu código não depender de efeitos colaterais (o que geralmente é verdade para projetos com ambiente node).

TIP

Você pode desabilitar o isolamento para pools específicos usando a propriedade poolOptions.

includeTaskLocation

• Tipo: boolean
• Padrão: false

Define se a propriedade location deve ser incluída quando a API do Vitest processa tarefas nos reporters. Se você tiver muitos testes, isso pode resultar em uma pequena regressão de desempenho.

A propriedade location possui valores column e line que correspondem à posição do test ou describe no arquivo original.

Esta opção será ativada automaticamente se você não a desabilitar explicitamente e estiver executando o Vitest com:

• Vitest UI
• ou usando o Modo Navegador sem o modo headless
• ou usando o HTML Reporter

TIP

Esta opção não tem efeito se você não usar código personalizado que dependa disso.

snapshotEnvironment

• Tipo: string

O caminho para uma implementação de ambiente de instantâneo personalizada. Isso é útil se você estiver executando seus testes em um ambiente que não oferece suporte a APIs Node.js. Esta opção não tem nenhum efeito em um executor de navegador.

Este objeto deve seguir o formato de SnapshotEnvironment e é usado para resolver e ler/escrever arquivos de instantâneo:

export interface SnapshotEnvironment {
  getVersion: () => string;
  getHeader: () => string;
  resolvePath: (filepath: string) => Promise<string>;
  resolveRawPath: (testPath: string, rawPath: string) => Promise<string>;
  saveSnapshotFile: (filepath: string, snapshot: string) => Promise<void>;
  readSnapshotFile: (filepath: string) => Promise<string | null>;
  removeSnapshotFile: (filepath: string) => Promise<void>;
}

Você pode estender o VitestSnapshotEnvironment padrão do ponto de entrada vitest/snapshot se precisar modificar apenas uma parte da API.

WARNING

Esta é uma opção de baixo nível e destina-se apenas a casos avançados onde você não tem acesso às APIs padrão do Node.js.

Se você precisar apenas configurar o recurso de instantâneos, use as opções snapshotFormat ou resolveSnapshotPath.

env

• Tipo: Partial<NodeJS.ProcessEnv>

Variáveis de ambiente acessíveis via process.env e import.meta.env durante os testes. Essas variáveis não serão acessíveis no processo principal (em globalSetup, por exemplo).

expect

• Tipo: ExpectOptions

expect.requireAssertions

• Tipo: boolean
• Padrão: false

O mesmo que chamar expect.hasAssertions() no início de cada teste. Isso garante que nenhum teste seja aprovado acidentalmente.

TIP

Isso só funciona com o expect do Vitest. Se você usar asserções assert ou .should, elas não serão consideradas, e seu teste falhará devido à falta de asserções expect.

Você pode alterar o valor disso chamando vi.setConfig({ expect: { requireAssertions: false } }). A configuração será aplicada a cada chamada expect subsequente até que vi.resetConfig seja invocado manualmente.

expect.poll

Opções de configuração global de expect.poll. Estas são as mesmas opções que você pode fornecer a expect.poll(condition, options).

expect.poll.interval

• Tipo: number
• Padrão: 50

Intervalo de sondagem em milissegundos.

expect.poll.timeout

• Tipo: number
• Padrão: 1000

Tempo limite de sondagem em milissegundos.

printConsoleTrace

• Tipo: boolean
• Padrão: false

Sempre imprimir rastreamentos do console ao chamar qualquer método console. Útil para depuração.

attachmentsDir 3.2.0+

• Tipo: string
• Padrão: '.vitest-attachments'

O caminho do diretório onde serão armazenados os anexos criados por context.annotate relativo à raiz do projeto.