TestSuite

A classe TestSuite representa um único conjunto de testes. Esta classe está disponível apenas na thread principal. Para interagir com tarefas em tempo de execução, consulte a "API do Runner".

A instância de TestSuite sempre possui uma propriedade type com o valor suite. Você pode utilizá-la para diferenciar entre os tipos de tarefas:

if (task.type === 'suite') {
  task; // TestSuite
}

project

Faz referência ao TestProject ao qual o conjunto de testes pertence.

module

Esta é uma referência direta ao TestModule onde o conjunto de testes é definido.

name

Este é o nome do conjunto de testes que foi passado para a função describe.

import { describe } from 'vitest';

// [!code word:'a lógica de validação']
describe('a lógica de validação', () => {
  // ...
});

fullName

O nome completo do conjunto de testes, incluindo todos os conjuntos de testes pai, separados pelo símbolo >. Por exemplo, este conjunto de testes tem o nome completo "a lógica de validação > validando cidades":

import { describe, test } from 'vitest';

// [!code word:'a lógica de validação']
// [!code word:'validando cidades']
describe('a lógica de validação', () => {
  describe('validando cidades', () => {
    // ...
  });
});

id

Este é o identificador único do conjunto de testes. Este ID é determinístico e permanecerá o mesmo para o mesmo conjunto de testes em múltiplas execuções. O ID é gerado com base no nome do projeto, ID do módulo e ordem do conjunto de testes.

O ID tem o seguinte formato:

1223128da3_0_0_0
^^^^^^^^^^ hash do arquivo
           ^ índice do conjunto de testes
             ^ índice do conjunto de testes aninhado
               ^ índice do teste

TIP

Você pode gerar a hash do arquivo com a função generateFileHash de vitest/node, disponível a partir do Vitest 3:

import { generateFileHash } from 'vitest/node';

const hash = generateFileHash(
  '/file/path.js', // caminho relativo
  undefined // o nome do projeto ou `undefined`, caso não esteja definido
);

DANGER

Não tente interpretar o ID. Ele pode começar com um sinal de menos: -1223128da3_0_0_0.

location

A localização no módulo onde o conjunto de testes foi definido. As localizações são coletadas apenas se includeTaskLocation estiver habilitado na configuração. Observe que esta opção é automaticamente habilitada se as flags --reporter=html, --ui ou --browser forem utilizadas.

A localização deste conjunto de testes será { line: 3, column: 1 }:

import { describe } from 'vitest'

describe('a validação funciona corretamente', () => {
  // ...
})

parent

O conjunto de testes pai. Se o conjunto de testes for chamado diretamente dentro do módulo, o pai será o próprio módulo.

options

interface TaskOptions {
  readonly each: boolean | undefined;
  readonly fails: boolean | undefined;
  readonly concurrent: boolean | undefined;
  readonly shuffle: boolean | undefined;
  readonly retry: number | undefined;
  readonly repeats: number | undefined;
  readonly mode: 'run' | 'only' | 'skip' | 'todo';
}

As opções com as quais o conjunto de testes foi coletado.

children

Esta é uma coleção de todos os conjuntos de testes e testes dentro do conjunto de testes atual.

for (const task of suite.children) {
  if (task.type === 'test') {
    console.log('teste', task.fullName);
  } else {
    // task é TestSuite
    console.log('conjunto de testes', task.name);
  }
}

WARNING

Observe que suite.children iterará apenas o primeiro nível de aninhamento, não se aprofundando. Se você precisar iterar sobre todos os testes ou conjuntos de testes, utilize children.allTests() ou children.allSuites(). Se você precisar iterar sobre tudo, utilize uma função recursiva:

function visit(collection: TestCollection) {
  for (const task of collection) {
    if (task.type === 'suite') {
      // processar um conjunto de testes
      visit(task.children);
    } else {
      // processar um teste
    }
  }
}

ok

function ok(): boolean;

Verifica se o conjunto de testes possui algum teste falho. Isso também retornará false se o conjunto de testes falhar durante a coleta. Nesse caso, verifique os errors() para erros lançados.

state

function state(): TestSuiteState;

Verifica o estado de execução do conjunto de testes. Possíveis valores de retorno:

• pending: os testes neste conjunto de testes ainda não foram concluídos.
• failed: este conjunto de testes possui testes que falharam ou que não puderam ser coletados. Se errors() não estiver vazio, significa que o conjunto de testes falhou na coleta dos testes.
• passed: todos os testes dentro deste conjunto de testes foram aprovados.
• skipped: este conjunto de testes foi ignorado durante a coleta.

WARNING

Observe que o módulo de teste também possui um método state que retorna os mesmos valores, mas pode retornar um estado queued adicional caso o módulo ainda não tenha sido executado.

errors

function errors(): TestError[];

Erros que ocorreram fora da execução do teste durante a coleta, como erros de sintaxe.

import { describe } from 'vitest';

describe('falha na coleta', () => {
  throw new Error('um erro customizado');
});

WARNING

Observe que os erros são serializados em objetos simples: instanceof Error sempre retornará false.

meta 3.1.0+

function meta(): TaskMeta;

Metadados personalizados que foram anexados ao conjunto de testes durante sua execução ou coleta. Os metadados podem ser anexados atribuindo uma propriedade ao objeto task.meta durante uma execução de teste:

import { test } from 'vitest';

describe('a validação funciona corretamente', task => {
  // atribuir "decorated" durante a coleta
  task.meta.decorated = false;

  test('algum teste', ({ task }) => {
    // atribuir "decorated" durante a execução do teste; estará disponível
    // apenas no hook onTestCaseReady
    task.suite.meta.decorated = false;
  });
});

TIP

Se os metadados forem anexados durante a coleta (fora da função test), eles estarão disponíveis no hook onTestModuleCollected no relatório personalizado.