TestSuite

La clase TestSuite representa una única suite de pruebas. Esta clase solo está disponible en el hilo principal. Para trabajar con tareas en tiempo de ejecución, consulta la "API del corredor".

La instancia de TestSuite siempre tiene una propiedad type con el valor suite. Puedes usarla para distinguir entre diferentes tipos de tareas:

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

project

Se refiere al TestProject al que pertenece esta suite de pruebas.

module

Es una referencia directa al TestModule donde se define esta suite.

name

Es el nombre de la suite que se le pasó a la función describe.

import { describe } from 'vitest';

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

fullName

El nombre completo de la suite, incluyendo todas las suites padre, separadas por el símbolo >. Por ejemplo, el nombre completo de esta suite es "the validation logic > validating cities":

import { describe, test } from 'vitest';

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

id

Es el identificador único de la suite. Este ID es determinista y será el mismo para la misma suite en múltiples ejecuciones. El ID se basa en el nombre del proyecto, el ID del módulo y el orden de la suite.

El formato del ID es el siguiente:

1223128da3_0_0_0
^^^^^^^^^^ hash del archivo
           ^ índice de la suite
             ^ índice de la suite anidada
               ^ índice de la prueba

TIP

Puedes generar el hash del archivo con la función generateFileHash de vitest/node, disponible a partir de Vitest 3:

import { generateFileHash } from 'vitest/node';

const hash = generateFileHash(
  '/file/path.js', // ruta relativa
  undefined // el nombre del proyecto o `undefined` si no está configurado
);

DANGER

No intentes analizar el ID. Puede comenzar con un signo menos: -1223128da3_0_0_0.

location

La ubicación en el módulo donde se definió la suite. Las ubicaciones solo se recopilan si includeTaskLocation está habilitado en la configuración. Ten en cuenta que esta opción se habilita automáticamente si se utilizan las banderas --reporter=html, --ui o --browser.

La ubicación de esta suite será { line: 3, column: 1 }:

import { describe } from 'vitest'

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

parent

La suite principal. Si la suite fue llamada directamente dentro del módulo, su padre será el propio 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';
}

Las opciones con las que se recopiló la suite.

children

Esta es una colección de todas las suites y pruebas que están anidadas dentro de la suite actual.

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

WARNING

Ten en cuenta que suite.children solo iterará el primer nivel de anidamiento, sin profundizar. Si necesitas iterar sobre todas las pruebas o suites anidadas, usa children.allTests() o children.allSuites(). Si necesitas iterar sobre todos los elementos, usa una función recursiva:

function visit(collection: TestCollection) {
  for (const task of collection) {
    if (task.type === 'suite') {
      // reportar una suite
      visit(task.children);
    } else {
      // reportar una prueba
    }
  }
}

ok

function ok(): boolean;

Comprueba si la suite contiene alguna prueba fallida. También devolverá false si la suite falló durante la recopilación. En ese caso, verifica errors() para ver los errores lanzados.

state

function state(): TestSuiteState;

Verifica el estado de ejecución de la suite. Posibles valores de retorno:

• pending: las pruebas en esta suite aún no han finalizado su ejecución.
• failed: esta suite tiene pruebas fallidas o no pudieron ser recopiladas. Si errors() no está vacío, significa que la suite falló al recopilar las pruebas.
• passed: todas las pruebas dentro de esta suite han pasado.
• skipped: esta suite fue omitida durante la recopilación.

WARNING

Ten en cuenta que el módulo de prueba también tiene un método state que devuelve los mismos valores, pero puede devolver un estado queued adicional si el módulo aún no se ha ejecutado.

errors

function errors(): TestError[];

Errores ocurridos fuera de la ejecución de la prueba durante la fase de recopilación, como errores de sintaxis.

import { describe } from 'vitest';

describe('collection failed', () => {
  throw new Error('a custom error');
});

WARNING

Ten en cuenta que los errores se serializan como objetos simples: instanceof Error siempre devolverá false.

meta 3.1.0+

function meta(): TaskMeta;

Metadatos personalizados que se adjuntaron a la suite durante su ejecución o recopilación. Los metadatos se pueden adjuntar asignando una propiedad al objeto task.meta durante la ejecución de una prueba:

import { test } from 'vitest';

describe('the validation works correctly', task => {
  // asignar 'decorated' durante la recopilación
  task.meta.decorated = false;

  test('some test', ({ task }) => {
    // asignar 'decorated' durante la ejecución de la prueba; estará disponible
    // solo en el hook onTestCaseReady
    task.suite.meta.decorated = false;
  });
});

TIP

Si los metadatos se adjuntaron durante la recopilación (fuera de la función test), estarán disponibles en el hook onTestModuleCollected del reporter personalizado.