TestCase

A classe TestCase representa um único teste. Esta classe está disponível apenas no thread principal. Para trabalhar com tarefas em tempo de execução, consulte a "API do Executor".

A instância de TestCase sempre possui uma propriedade type cujo valor é test. Você pode usá-la para distinguir entre diferentes tipos de tarefas:

if (task.type === 'test') {
  task; // TestCase
}

project

Refere-se ao TestProject ao qual o teste pertence.

module

Esta é uma referência direta ao TestModule no qual o teste é definido.

name

Este é o nome do teste passado para a função test.

import { test } from 'vitest';

// [!code word:'the validation works correctly']
test('the validation works correctly', () => {
  // ...
});

fullName

O nome completo do teste, incluindo todas as suítes pai, é separado pelo símbolo >. Por exemplo, este teste tem o nome completo "the validation logic > the validation works correctly":

import { describe, test } from 'vitest';

// [!code word:'the validation works correctly']
// [!code word:'the validation logic']
describe('the validation logic', () => {
  test('the validation works correctly', () => {
    // ...
  });
});

id

Este é o identificador único do teste. Este ID é determinístico e permanecerá o mesmo para o mesmo teste em várias execuções. O ID é baseado no nome do projeto, ID do módulo e ordem do teste.

O ID tem o seguinte formato:

1223128da3_0_0
^^^^^^^^^^ o hash do arquivo
           ^ o índice da suíte
             ^ o índice do teste

TIP

Você pode gerar o hash do arquivo com a função generateFileHash do vitest/node, que está 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 fazer o parse do ID. Ele pode ter um sinal de menos no início: -1223128da3_0_0_0.

location

A localização no módulo onde o teste foi definido. A localização é coletada apenas se includeTaskLocation estiver ativado na configuração. Observe que esta opção é automaticamente habilitada se as flags --reporter=html, --ui ou --browser forem usadas.

A localização deste teste será igual a { line: 3, column: 1 }:

import { test } from 'vitest'

test('the validation works correctly', () => {
  // ...
})

parent

Suíte pai. Se o teste foi 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 teste foi coletado.

ok

function ok(): boolean;

Verifica se o teste não falhou na suíte. Se o teste ainda não terminou ou foi pulado, ele retornará true.

meta

function meta(): TaskMeta;

Metadados personalizados que foram anexados ao teste durante sua execução. Metadados podem ser anexados atribuindo uma propriedade ao objeto ctx.task.meta durante a execução de um teste:

import { test } from 'vitest';

test('the validation works correctly', ({ task }) => {
  // ...

  task.meta.decorated = false;
});

Se o teste ainda não terminou de ser executado, os metadados serão um objeto vazio.

result

function result(): TestResult;

Os resultados do teste. Se o teste ainda não terminou ou foi apenas coletado, será TestResultPending:

export interface TestResultPending {
  /**
   * O teste foi coletado, mas ainda não terminou de ser executado.
   */
  readonly state: 'pending';
  /**
   * Testes pendentes não têm erros.
   */
  readonly errors: undefined;
}

Se o teste foi ignorado, o retorno será TestResultSkipped:

interface TestResultSkipped {
  /**
   * O teste foi ignorado com a *flag* `skip` ou `todo`.
   * Você pode ver qual foi usada na opção `options.mode`.
   */
  readonly state: 'skipped';
  /**
   * Testes ignorados não têm erros.
   */
  readonly errors: undefined;
  /**
   * Uma nota personalizada passada para `ctx.skip(note)`.
   */
  readonly note: string | undefined;
}

TIP

Se o teste foi ignorado porque outro teste tem a flag only, o options.mode será skip.

Se o teste falhou, o valor de retorno será TestResultFailed:

interface TestResultFailed {
  /**
   * O teste falhou ao executar.
   */
  readonly state: 'failed';
  /**
   * Erros que foram lançados durante a execução do teste.
   */
  readonly errors: ReadonlyArray<TestError>;
}

Se o teste passou, o retorno será TestResultPassed:

interface TestResultPassed {
  /**
   * O teste passou com sucesso.
   */
  readonly state: 'passed';
  /**
   * Erros que foram lançados durante a execução do teste.
   */
  readonly errors: ReadonlyArray<TestError> | undefined;
}

WARNING

Observe que o teste com estado passed ainda pode ter erros anexados - isso pode acontecer se retry foi acionado pelo menos uma vez.

diagnostic

function diagnostic(): TestDiagnostic | undefined;

Informações úteis sobre o teste, como duração, uso de memória, etc:

interface TestDiagnostic {
  /**
   * Se a duração do teste exceder `slowTestThreshold`.
   */
  readonly slow: boolean;
  /**
   * A quantidade de memória usada pelo teste em bytes.
   * Este valor está disponível apenas se o teste foi executado com a *flag* `logHeapUsage`.
   */
  readonly heap: number | undefined;
  /**
   * O tempo que leva para executar o teste em ms.
   */
  readonly duration: number;
  /**
   * O tempo em ms quando o teste começou.
   */
  readonly startTime: number;
  /**
   * A quantidade de vezes que o teste foi retentado.
   */
  readonly retryCount: number;
  /**
   * A quantidade de vezes que o teste foi repetido conforme configurado pela opção `repeats`.
   * Este valor pode ser menor se o teste falhou durante a repetição e nenhum `retry` estiver configurado.
   */
  readonly repeatCount: number;
  /**
   * Se o teste passou em uma segunda tentativa.
   */
  readonly flaky: boolean;
}

INFO

diagnostic() retornará undefined se o teste ainda não foi agendado para execução.