Executando Testes

WARNING

Este guia detalha o uso da API avançada para executar testes via script Node.js. Se seu objetivo é apenas executar testes, esta seção provavelmente não é necessária. Ela é destinada principalmente a autores de bibliotecas.

Alterações que quebram a compatibilidade podem não seguir o SemVer; por favor, fixe a versão do Vitest ao utilizar esta API experimental.

O Vitest oferece dois métodos para iniciar sua execução:

• startVitest inicia o Vitest, verifica a instalação dos pacotes e executa os testes imediatamente.
• createVitest apenas inicializa o Vitest, sem iniciar a execução dos testes.

startVitest

import { startVitest } from 'vitest/node';

const vitest = await startVitest(
  'test',
  [], // Filtros da CLI
  {}, // Sobrescrita da configuração de teste
  {}, // Sobrescrita da configuração do Vite
  {} // Opções personalizadas do Vitest
);
const testModules = vitest.state.getTestModules();
for (const testModule of testModules) {
  console.log(testModule.moduleId, testModule.ok() ? 'passed' : 'failed');
}

TIP

As APIs TestModule, TestSuite e TestCase não são experimentais e seguem o SemVer desde o Vitest 2.1.

createVitest

Cria uma instância do Vitest sem executar testes.

O método createVitest não verifica a instalação dos pacotes necessários. Além disso, ele não considera as configurações config.standalone ou config.mergeReports. O Vitest não será encerrado automaticamente, mesmo que watch esteja desabilitado.

import { createVitest } from 'vitest/node';

const vitest = await createVitest(
  'test',
  {}, // Sobrescrita da configuração de teste
  {}, // Sobrescrita da configuração do Vite
  {} // Opções personalizadas do Vitest
);

// Chamado quando `vitest.cancelCurrentRun()` é invocado
vitest.onCancel(() => {});
// Chamado durante a execução de `vitest.close()`
vitest.onClose(() => {});
// Chamado quando o Vitest reexecuta arquivos de teste
vitest.onTestsRerun(files => {});

try {
  // Isso definirá process.exitCode como 1 se os testes falharem,
  // e não fechará o processo automaticamente.
  await vitest.start(['my-filter']);
} catch (err) {
  // Isso pode lançar:
  // "FilesNotFoundError" caso nenhum arquivo seja encontrado.
  // "GitNotFoundError" com `--changed` e o repositório não estiver inicializado.
} finally {
  await vitest.close();
}

Se você pretende manter a instância do Vitest ativa, certifique-se de chamar pelo menos init. Isso inicializará os reporters e o provedor de cobertura, mas não executará nenhum teste. Também é recomendado habilitar o modo watch, mesmo que você não pretenda usar o watcher do Vitest, mas queira manter a instância em execução. O Vitest depende dessa flag para que alguns de seus recursos funcionem corretamente em um processo contínuo.

Após a inicialização dos reporters, utilize runTestSpecifications ou rerunTestSpecifications para executar testes, caso uma execução manual seja necessária:

watcher.on('change', async file => {
  const specifications = vitest.getModuleSpecifications(file);
  if (specifications.length) {
    vitest.invalidateFile(file);
    // Você pode usar runTestSpecifications se os hooks "reporter.onWatcher*"
    // não devem ser chamados.
    await vitest.rerunTestSpecifications(specifications);
  }
});

WARNING

O exemplo acima ilustra um caso de uso para quando você desabilita o comportamento padrão do watcher. Por padrão, o Vitest reexecuta automaticamente os testes se os arquivos forem alterados.

Além disso, observe que getModuleSpecifications não resolverá arquivos de teste a menos que já tenham sido processados por globTestSpecifications. Se o arquivo foi recém-criado, use project.matchesGlobPattern em vez disso:

watcher.on('add', async file => {
  const specifications = [];
  for (const project of vitest.projects) {
    if (project.matchesGlobPattern(file)) {
      specifications.push(project.createSpecification(file));
    }
  }

  if (specifications.length) {
    await vitest.rerunTestSpecifications(specifications);
  }
});

Se você precisar desabilitar o watcher, pode passar server.watch: null a partir do Vite 5.3 ou server.watch: { ignored: ['*/*'] } em uma configuração do Vite:

await createVitest(
  'test',
  {},
  {
    plugins: [
      {
        name: 'stop-watcher',
        async configureServer(server) {
          await server.watcher.close();
        },
      },
    ],
    server: {
      watch: null,
    },
  }
);