TestSuite

Die Klasse TestSuite repräsentiert eine einzelne Test-Suite. Diese Klasse ist ausschließlich im Haupt-Thread verfügbar. Für die Arbeit mit Laufzeit-Tasks beachten Sie bitte die "Runner API".

Eine TestSuite-Instanz besitzt immer eine type-Eigenschaft mit dem Wert suite. Dies ermöglicht die Unterscheidung zwischen verschiedenen Task-Typen:

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

project

Dies ist ein Verweis auf das TestProject, zu dem die Test-Suite gehört.

module

Dies ist eine direkte Referenz auf das TestModule, in dem die Test-Suite definiert ist.

name

Dies ist der Name der Suite, der der describe-Funktion übergeben wurde.

import { describe } from 'vitest';

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

fullName

Der vollständige Name der Suite, einschließlich aller übergeordneten Suiten, getrennt durch das Zeichen >. Diese Suite trägt den vollständigen Namen "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

Dies ist die eindeutige ID der Suite. Diese ID ist deterministisch und bleibt für dieselbe Suite über mehrere Testläufe hinweg konstant. Die ID basiert auf dem Namen des Projekts, der Modul-ID und der Reihenfolge der Suite.

Die ID hat folgendes Format:

1223128da3_0_0_0
^^^^^^^^^^ Dateihash
           ^ Suitenindex
             ^ Verschachtelter Suitenindex
               ^ Testindex

TIP

Sie können den Dateihash mit der Funktion generateFileHash aus vitest/node generieren, die seit Vitest 3 verfügbar ist:

import { generateFileHash } from 'vitest/node';

const hash = generateFileHash(
  '/file/path.js', // relativer Pfad
  undefined // der Projektname oder `undefined`, falls nicht gesetzt
);

DANGER

Versuchen Sie nicht, die ID zu parsen. Sie kann ein Minuszeichen am Anfang haben: -1223128da3_0_0_0.

location

Die Position im Modul, an der die Suite definiert wurde. Positionen werden nur erfasst, wenn includeTaskLocation in der Konfiguration aktiviert ist. Beachten Sie, dass diese Option automatisch aktiviert wird, wenn die Flags --reporter=html, --ui oder --browser verwendet werden.

Die Position dieser Suite entspricht { line: 3, column: 1 }:

import { describe } from 'vitest'

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

parent

Die übergeordnete Suite. Wenn die Suite direkt innerhalb des Moduls aufgerufen wurde, ist die übergeordnete Suite das Modul selbst.

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

Die Optionen, mit denen die Suite erfasst wurde.

children

Dies ist eine Sammlung aller Suiten und Tests innerhalb der aktuellen Suite.

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

WARNING

Beachten Sie, dass suite.children nur die erste Verschachtelungsebene durchläuft; es wird nicht tiefer gehen. Wenn Sie alle Tests oder Suiten durchlaufen müssen, verwenden Sie children.allTests() oder children.allSuites(). Wenn Sie alle Elemente durchlaufen müssen, verwenden Sie eine rekursive Funktion:

function visit(collection: TestCollection) {
  for (const task of collection) {
    if (task.type === 'suite') {
      // eine Suite verarbeiten
      visit(task.children);
    } else {
      // einen Test verarbeiten
    }
  }
}

ok

function ok(): boolean;

Überprüft, ob die Suite fehlgeschlagene Tests enthält. Dies gibt auch false zurück, wenn die Suite während der Erfassung fehlgeschlagen ist. In diesem Fall prüfen Sie die errors() auf aufgetretene Fehler.

state

function state(): TestSuiteState;

Ermittelt den Ausführungsstatus der Suite. Mögliche Rückgabewerte:

• pending: Die Tests in dieser Suite wurden noch nicht vollständig ausgeführt.
• failed: Diese Suite enthält fehlgeschlagene Tests oder konnte nicht erfasst werden. Wenn errors() nicht leer ist, bedeutet dies, dass die Suite Tests nicht erfassen konnte.
• passed: Jeder Test innerhalb dieser Suite wurde erfolgreich bestanden.
• skipped: Diese Suite wurde während der Erfassung übersprungen.

WARNING

Beachten Sie, dass das Testmodul ebenfalls eine state-Methode besitzt, die dieselben Werte zurückgibt, aber zusätzlich einen queued-Status zurückgeben kann, wenn das Modul noch nicht ausgeführt wurde.

errors

function errors(): TestError[];

Fehler, die während der Erfassung außerhalb des Testlaufs aufgetreten sind, wie z.B. Syntaxfehler.

import { describe } from 'vitest';

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

WARNING

Beachten Sie, dass Fehler in einfache Objekte serialisiert werden: instanceof Error gibt immer false zurück.

meta 3.1.0+

function meta(): TaskMeta;

Benutzerdefinierte Metadaten, die der Suite während ihrer Ausführung oder Erfassung zugewiesen wurden. Die Metadaten können durch Zuweisung einer Eigenschaft zum task.meta-Objekt während eines Testlaufs angehängt werden:

import { test } from 'vitest';

describe('the validation works correctly', task => {
  // "decorated" während der Sammlung zuweisen
  task.meta.decorated = false;

  test('some test', ({ task }) => {
    // "decorated" während des Testlaufs zuweisen; es wird
    // nur im onTestCaseReady-Hook verfügbar sein
    task.suite.meta.decorated = false;
  });
});

TIP

Wenn Metadaten während der Erfassung (außerhalb der test-Funktion) angehängt wurden, sind sie im onTestModuleCollected-Hook im eigenen Reporter verfügbar.