Executor de Teste

WARNING

Esta é uma API avançada. Se você está apenas executando testes, provavelmente não precisa disso. É utilizada principalmente por autores de bibliotecas.

Você pode especificar o caminho para seu executor de testes com a opção runner no seu arquivo de configuração. Este arquivo deve ter uma exportação padrão com uma classe que implementa estes métodos:

export interface VitestRunner {
  /**
   * Primeira ação a ser executada antes de coletar e executar os testes.
   */
  onBeforeCollect?: (paths: string[]) => unknown;
  /**
   * Chamado após coletar os testes e antes de "onBeforeRun".
   */
  onCollected?: (files: File[]) => unknown;

  /**
   * Chamado quando o executor de testes deve cancelar as próximas execuções de teste.
   * O executor deve responder a este método e marcar os testes e suítes como ignorados em
   * "onBeforeRunSuite" e "onBeforeRunTask" quando for chamado.
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * Chamado antes de executar um único teste. Ainda não possui "result".
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Chamado antes de realmente executar a função de teste. Já possui "result" com "state" e "startTime".
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * Chamado após o resultado e o estado serem definidos.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Chamado logo após executar a função de teste. Ainda não tem novo estado. Não será chamado se a função de teste gerar uma exceção.
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

  /**
   * Chamado antes de executar uma única suíte. Ainda não possui "result".
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * Chamado após executar uma única suíte. Tem estado e resultado.
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * Se definido, será chamado em vez da partição e tratamento usual da suíte do Vitest.
   * Os hooks "before" e "after" não serão ignorados.
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * Se definido, será chamado em vez do tratamento usual do Vitest para testes. Útil se você tiver sua função de teste personalizada.
   * Os hooks "before" e "after" não serão ignorados.
   */
  runTask?: (test: TaskPopulated) => Promise<void>;

  /**
   * Chamado quando uma tarefa é atualizada. O mesmo que "onTaskUpdate" em um notificador, mas isso está sendo executado na mesma thread que os testes.
   */
  onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>;

  /**
   * Chamado antes de executar todos os testes nos caminhos coletados.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * Chamado logo após executar todos os testes nos caminhos coletados.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * Chamado quando um novo contexto para um teste é definido. Útil se você deseja apenas adicionar propriedades personalizadas ao contexto.
   * Se você deseja apenas definir um contexto personalizado com um executor, considere usar "beforeAll" em "setupFiles" em vez disso.
   *
   * Este método é chamado para os manipuladores "test" e "custom".
   *
   * @see https://www.getbook.com/pt-br/book/vitest-1/advanced/runner#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(
    context: TaskContext<T>
  ) => TaskContext<T>;
  /**
   * Chamado quando certos arquivos são importados. Pode ser chamado em duas situações: ao coletar testes e ao importar arquivos de setup.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * Configuração disponível publicamente.
   */
  config: VitestRunnerConfig;
}

Ao instanciar esta classe, o Vitest passa a configuração do Vitest. Você deve expô-la como uma propriedade config.

WARNING

O Vitest também injeta uma instância de ViteNodeRunner como a propriedade __vitest_executor. Você pode usá-la para processar arquivos no método importFile (este é o comportamento padrão de TestRunner e BenchmarkRunner).

ViteNodeRunner expõe o método executeId, que é usado para importar arquivos de teste em um ambiente amigável ao Vite. Isso significa que ele resolverá as importações e transformará o conteúdo do arquivo em tempo de execução para que o Node possa executá-lo.

TIP

O suporte a Snapshots e alguns outros recursos dependem do executor. Caso não queira perdê-los, você pode estender seu executor de VitestTestRunner importado de vitest/runners. Ele também expõe BenchmarkNodeRunner se você quiser estender a funcionalidade de benchmark.

Sua Função de Tarefa

Você pode expandir o sistema de tarefas do Vitest com suas próprias tarefas. Uma tarefa é um objeto que faz parte de uma suíte. Ela é adicionada automaticamente à suíte atual através do método suite.task:

// ./utils/custom.js
import { createTaskCollector, getCurrentSuite, setFn } from 'vitest/suite';

export { describe, beforeAll, afterAll } from 'vitest';

// esta função será chamada durante a fase de coleta:
// não chame o manipulador de função aqui, adicione-o às tarefas do conjunto de testes
// com o método "getCurrentSuite().task()"
// nota: createTaskCollector fornece suporte para "todo"/"each"/...
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
  getCurrentSuite().task(name, {
    ...this, // so "todo"/"skip"/... is tracked correctly
    meta: {
      customPropertyToDifferentiateTask: true,
    },
    handler: fn,
    timeout,
  });
});

// ./garden/tasks.test.js
import { afterAll, beforeAll, describe, myCustomTask } from '../custom.js';
import { gardener } from './gardener.js';

describe('take care of the garden', () => {
  beforeAll(() => {
    gardener.putWorkingClothes();
  });

  myCustomTask('weed the grass', () => {
    gardener.weedTheGrass();
  });
  myCustomTask.todo('mow the lawn', () => {
    gardener.mowerTheLawn();
  });
  myCustomTask('water flowers', () => {
    gardener.waterFlowers();
  });

  afterAll(() => {
    gardener.goHome();
  });
});

vitest ./garden/tasks.test.js

WARNING

Caso não tenha um executor personalizado ou não tenha definido o método runTest, o Vitest tentará recuperar uma tarefa automaticamente. Se você não adicionou uma função com setFn, ele falhará.

TIP

O sistema de tarefas personalizadas suporta hooks e contextos. Para suportar o encadeamento de propriedades (como only, skip e as suas personalizadas), importe createChainable de vitest/suite e envolva sua função com ele. Nesse caso, você precisará chamar custom como custom.call(this).