Metadados da Tarefa

WARNING

O Vitest expõe uma API privada experimental. Alterações que quebram a compatibilidade podem não seguir o SemVer. Por favor, fixe a versão do Vitest ao usá-la.

Se você estiver desenvolvendo um reporter personalizado ou utilizando a API Node.js do Vitest, pode ser útil transmitir dados de testes que estão sendo executados em diferentes contextos para o seu reporter ou manipulador personalizado do Vitest.

Para conseguir isso, depender do contexto de teste não é viável, já que ele não pode ser serializado. No entanto, com o Vitest, você pode utilizar a propriedade meta disponível em cada tarefa (suíte ou teste) para compartilhar dados entre seus testes e o processo Node.js. É importante notar que essa comunicação é apenas unidirecional, pois a propriedade meta só pode ser modificada de dentro do contexto de teste. Quaisquer alterações feitas no contexto Node.js não serão visíveis em seus testes.

Você pode preencher a propriedade meta no contexto de teste ou nos hooks beforeAll e afterAll para tarefas de suíte.

afterAll(suite => {
  suite.meta.done = true;
});

test('custom', ({ task }) => {
  task.meta.custom = 'some-custom-handler';
});

Assim que um teste é concluído, o Vitest enviará uma tarefa, incluindo o resultado e meta, para o processo Node.js usando RPC, e então a reportará em onTestCaseResult e em outros hooks que têm acesso às tarefas. Para processar este caso de teste, você pode utilizar o método onTestCaseResult disponível na sua implementação de reporter:

import type { Reporter, TestCase, TestModule } from 'vitest/node';

export default {
  onTestCaseResult(testCase: TestCase) {
    // custom === 'some-custom-handler' ✅
    const { custom } = testCase.meta();
  },
  onTestRunEnd(testModule: TestModule) {
    testModule.meta().done === true;
    testModule.children.at(0).meta().custom === 'some-custom-handler';
  },
} satisfies Reporter;

CUIDADO

O Vitest utiliza métodos diferentes para se comunicar com o processo Node.js.

• Se o Vitest executar testes em worker threads, ele enviará dados via message port.
• Se o Vitest usar um processo filho, os dados serão enviados como um Buffer serializado via API process.send.
• Se o Vitest executar testes no navegador, os dados serão convertidos em string usando o pacote flatted.

Esta propriedade também está presente em cada teste no reporter json, portanto, certifique-se de que os dados possam ser serializados em JSON.

Além disso, certifique-se de serializar as propriedades de Erro antes de as definir.

Você também pode obter essas informações do estado do Vitest quando os testes terminarem a execução:

const vitest = await createVitest('test');
const { testModules } = await vitest.start();

const testModule = testModules[0];
testModule.meta().done === true;
testModule.children.at(0).meta().custom === 'some-custom-handler';

É possível também estender as definições de tipo ao utilizar TypeScript:

declare module 'vitest' {
  interface TaskMeta {
    done?: boolean;
    custom?: string;
  }
}