TestSuite

La classe TestSuite rappresenta una singola suite di test. Questa classe è disponibile esclusivamente nel thread principale. Per interagire con i task in fase di runtime, si prega di consultare la "Runner API".

L'istanza TestSuite possiede sempre una proprietà type con il valore suite. Questa proprietà può essere utilizzata per distinguere tra i vari tipi di task:

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

project

Questo campo fa riferimento al TestProject a cui la suite di test appartiene.

module

Questo è un riferimento diretto al TestModule in cui la suite di test è definita.

name

Questo è il nome della suite, come passato alla funzione describe.

import { describe } from 'vitest';

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

fullName

Il nome completo della suite, che include tutti i nomi delle suite genitrici, separati dal simbolo >. Ad esempio, questa suite avrà il nome completo "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

Questo è l'identificatore univoco della suite. Questo ID è deterministico e rimarrà invariato per la stessa suite attraverso esecuzioni multiple. L'ID è generato in base al nome del progetto, all'ID del modulo e all'ordine della suite.

L'ID si presenta nel seguente formato:

1223128da3_0_0_0
^^^^^^^^^^ hash del file
           ^ indice della suite
             ^ indice della suite annidata
               ^ indice del test

TIP

È possibile generare l'hash del file utilizzando la funzione generateFileHash da vitest/node, disponibile a partire da Vitest 3:

import { generateFileHash } from 'vitest/node';

const hash = generateFileHash(
  '/file/path.js', // percorso relativo
  undefined // il nome del progetto o `undefined` se non è impostato
);

DANGER

Non tentare di analizzare l'ID. Potrebbe iniziare con un segno meno: -1223128da3_0_0_0.

location

La posizione all'interno del modulo in cui la suite è stata definita. Le posizioni vengono raccolte solo se l'opzione includeTaskLocation è abilitata nella configurazione. Si noti che questa opzione è automaticamente abilitata se vengono utilizzati i flag --reporter=html, --ui o --browser.

La posizione di questa suite sarà { line: 3, column: 1 }:

import { describe } from 'vitest'

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

parent

La suite genitore. Se la suite è stata invocata direttamente nel modulo, il genitore sarà il modulo stesso.

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';
}

Le opzioni con cui la suite è stata configurata.

children

Questa è una collezione di tutte le suite e i test contenuti all'interno della suite corrente.

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

WARNING

Si noti che suite.children itera solo sul primo livello di annidamento e non scende più in profondità. Se è necessario iterare su tutti i test o le suite, utilizzare children.allTests() o children.allSuites(). Per iterare su tutti gli elementi, è consigliabile utilizzare una funzione ricorsiva:

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

ok

function ok(): boolean;

Verifica se la suite contiene test falliti. Questo metodo restituirà false anche se la suite è fallita durante la fase di raccolta. In quest'ultimo caso, si prega di controllare il metodo errors() per gli errori generati.

state

function state(): TestSuiteState;

Restituisce lo stato di esecuzione della suite. I possibili valori restituiti sono:

• pending: i test all'interno di questa suite non hanno ancora completato l'esecuzione.
• failed: questa suite contiene test falliti o non è stato possibile raccoglierli. Se il metodo errors() non è vuoto, significa che la suite non è riuscita a raccogliere i test.
• passed: tutti i test all'interno di questa suite sono stati eseguiti con successo.
• skipped: questa suite è stata saltata durante la fase di raccolta.

WARNING

Si noti che anche il modulo di test dispone di un metodo state che restituisce gli stessi valori, ma può anche restituire uno stato aggiuntivo queued se il modulo non è ancora stato eseguito.

errors

function errors(): TestError[];

Errori verificatisi al di fuori dell'esecuzione del test durante la fase di raccolta, come errori di sintassi.

import { describe } from 'vitest';

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

WARNING

Si noti che gli errori vengono serializzati in semplici oggetti: instanceof Error restituirà sempre false.

meta 3.1.0+

function meta(): TaskMeta;

Metadati personalizzati associati alla suite durante la sua esecuzione o raccolta. I metadati possono essere associati assegnando una proprietà all'oggetto task.meta durante l'esecuzione di un test:

import { test } from 'vitest';

describe('the validation works correctly', task => {
  // assegna "decorated" durante la raccolta
  task.meta.decorated = false;

  test('some test', ({ task }) => {
    // assegna "decorated" durante l'esecuzione del test; sarà disponibile
    // solo nell'hook onTestCaseReady
    task.suite.meta.decorated = false;
  });
});

TIP

Se i metadati sono stati associati durante la fase di raccolta (al di fuori della funzione test), saranno disponibili nell'hook onTestModuleCollected all'interno del reporter personalizzato.