Vitest 3.2 ist da!

2. Juni 2025

Vitest 3.2 konzentriert sich auf Verbesserungen des Browser-Modus und der TypeScript-Unterstützung. Diese Version enthält auch einige neue nützliche Methoden, Konfigurationsoptionen und markiert die workspace-Konfiguration zugunsten von projects als veraltet.

workspace ist veraltet

Um die Konfiguration zu vereinfachen, hat das Team beschlossen, die separate Datei vitest.workspace als veraltet zu kennzeichnen und die Verwendung der Option projects in der Root-Konfiguration zu empfehlen. Dies vereinfacht auch die Konfiguration globaler Optionen (da Sie nicht mehr herausfinden müssen, wie Sie Reporter hinzufügen, wenn Sie keine Root-Konfiguration haben).

Wir haben uns auch entschieden, den Namen workspace als veraltet zu kennzeichnen, da er mit anderen Tools wie PNPM kollidiert, die Monorepo-Unterstützung über diese Option bieten. Vitest führt diese Projekte nicht mit separaten CWDs aus und behandelt sie eher wie Sub-Vitests. Es gibt uns auch mehr Raum, um eine bessere Lösung für Monorepos zu finden, ohne Inkompatibilitäten mit anderen zu verursachen.

Diese Option wird in einer zukünftigen Hauptversion vollständig entfernt und durch projects ersetzt. Bis dahin wird Vitest eine Warnung ausgeben, wenn die Workspace-Funktion verwendet wird.

import { defineConfig } from "vitest/config";
export default defineConfig({
  test: {
    // "test.workspace" wurde zu "test.projects" umbenannt.
    workspace: [ 
    projects: [ 
      { test: { name: "Unit" } },
      { test: { name: "Integration" } },
    ],
  },
});

Annotation API

Die neue Annotation API ermöglicht es Ihnen, jeden Test mit einer benutzerdefinierten Nachricht und einem Anhang zu versehen. Diese Anmerkungen sind in den UI-, HTML-, JUnit-, TAP- und GitHub Actions-Reportern sichtbar. Vitest wird auch die zugehörige Anmerkung in der CLI ausgeben, wenn der Test fehlschlägt.

Scoped Fixtures

Die test.extend-Fixtures können jetzt die Option scope angeben: entweder file oder worker.

const test = baseTest.extend({
  db: [
    async ({}, use) => {
      // ...setup
      await use(db);
      await db.close();
    },
    { scope: 'worker' },
  ],
});

Die file-Fixture ähnelt der Verwendung von beforeAll und afterAll auf der obersten Ebene der Datei, wird aber nicht aufgerufen, wenn die Fixture in keinem Test verwendet wird.

Die worker-Fixture wird einmal pro Worker initialisiert, aber beachten Sie, dass Vitest standardmäßig einen Worker für jeden Test erstellt, daher müssen Sie die Isolation deaktivieren, um diese Funktion zu nutzen.

Benutzerdefinierte Projektname-Farben

Sie können jetzt eine benutzerdefinierte Farbe festlegen, wenn Sie projects verwenden:

Konfigurationsbeispiel

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: {
            label: 'unit',
            color: 'red',
          },
        },
      },
      {
        test: {
          name: {
            label: 'browser',
            color: 'green',
          },
          browser: {
            enabled: true,
            provider: 'playwright',
            instances: [{ browser: 'chromium' }],
          },
        },
      },
    ],
  },
})

Benutzerdefinierte Browser Locators API

Die integrierten Locator-Methoden reichen möglicherweise nicht aus, um die Anforderungen Ihrer Anwendung auszudrücken. Anstatt auf CSS zurückzugreifen und den Schutz durch Wiederholbarkeit zu verlieren, den Vitest über seine Locator-API bietet, empfehlen wir jetzt, Locators mithilfe der neuen locators.extend-API zu erweitern.

import { locators } from '@vitest/browser/context';

locators.extend({
  getByCommentsCount(count: number) {
    return `.comments :text("${count} comments")`;
  },
});

Es sollte ein Playwright Locator-String zurückgegeben werden, um einen neuen Locator zu erstellen. Beachten Sie, dass der von dieser Methode zurückgegebene String, falls vorhanden, auf den übergeordneten Locator bezogen sein wird.

Jetzt können Sie getByCommentsCount direkt auf der page oder einem anderen Locator aufrufen:

await expect.element(page.getByCommentsCount(1)).toBeVisible();
await expect
  .element(
    page.getByRole('article', { name: 'Hello World' }).getByCommentsCount(1)
  )
  .toBeVisible();

Wenn diese Methode einen String zurückgibt, wird der Rückgabewert zu einem Locator umgewandelt, sodass Sie ihn weiter verketten können:

page
  .getByRole('article', { name: 'Hello World' })
  .getByCommentsCount(1)
  .getByText('comments');

Diese Methode hat Zugriff auf den aktuellen Locator-Kontext, falls vorhanden (wenn die Methode auf der page aufgerufen wird, ist der Kontext die page), sodass Sie alle Locator-Methoden darin verketten können:

import { locators } from '@vitest/browser/context';
import type { Locator } from '@vitest/browser/context';

locators.extend({
  getByCommentsCount(this: Locator, count: number) {
    return this.getByRole('comment').and(this.getByText(`${count} comments`));
  },
});

Durch den Zugriff auf den Kontext können Sie auch übliche Methoden des Locators aufrufen, um ein benutzerdefiniertes Benutzerereignis zu definieren:

import { locators, page } from '@vitest/browser/context';
import type { Locator } from '@vitest/browser/context';

locators.extend({
  clickAndFill(this: Locator, text: string) {
    await this.click();
    await this.fill(text);
  },
});

await page.getByRole('textbox').clickAndFill('Hello World');

Weitere Informationen finden Sie in der locators.extend-API.

Explizite Ressourcenverwaltung in vi.spyOn und vi.fn

In Umgebungen, die Explizite Ressourcenverwaltung unterstützen, können Sie using anstelle von const verwenden, um mockRestore automatisch für jede gemockte Funktion aufzurufen, wenn der umgebende Block verlassen wird. Dies ist besonders nützlich für Methoden, die mit vi.spyOn überwacht wurden:

it('calls console.log', () => {
  using spy = vi.spyOn(console, 'log').mockImplementation(() => {})
  debug('message')
  expect(spy).toHaveBeenCalled()
})

// console.log wird hier wiederhergestellt

Test signal API

Vitest stellt jetzt ein AbortSignal-Objekt für den Testkörper bereit. Sie können es verwenden, um jede Ressource zu stoppen, die diese Web-API unterstützt.

Das Signal wird abgebrochen, wenn der Test ein Timeout erreicht, ein anderer Test fehlschlägt und das --bail-Flag auf einen Wert ungleich Null gesetzt ist, oder der Benutzer Strg+C im Terminal drückt.

Sie können beispielsweise eine fetch-Anfrage stoppen, wenn Tests unterbrochen werden:

it('stop request when test times out', async ({ signal }) => {
  await fetch('/heavy-resource', { signal });
}, 2000);

Coverage V8 AST-aware remapping

Vitest verwendet jetzt das Paket ast-v8-to-istanbul, das von einem der Vitest-Maintainer, AriPerkkio, entwickelt wurde. Dies bringt den v8-Coverage-Bericht in Einklang mit Istanbul und bietet gleichzeitig eine bessere Leistung! Aktivieren Sie diese Funktion, indem Sie coverage.experimentalAstAwareRemapping auf true setzen.

Wir planen, dies in der nächsten Hauptversion zum Standard-Remapping-Modus zu machen. Das alte v8-to-istanbul wird vollständig entfernt. Wir laden Sie ein, an der Diskussion unter https://github.com/vitest-dev/vitest/issues/7928 teilzunehmen.

watchTriggerPatterns Option

Wenn Sie eine Datei bearbeiten, ist Vitest intelligent genug, um nur Tests erneut auszuführen, die diese Datei importieren. Leider berücksichtigt die statische Analyse von Vitest nur statische und dynamische import-Anweisungen. Wenn Sie eine Datei lesen oder einen separaten Prozess starten, ignoriert Vitest Änderungen an verwandten Dateien.

Mit der Option watchTriggerPatterns lässt sich festlegen, welche Tests je nach der geänderten Datei erneut ausgeführt werden sollen. Um beispielsweise mailers-Tests immer erneut auszuführen, wenn eine Vorlage geändert wird, können Sie ein Trigger-Muster hinzufügen:

export default defineConfig({
  test: {
    watchTriggerPatterns: [
      {
        pattern: /^src\/templates\/(.*)\.(ts|html|txt)$/,
        testsToRun: (file, match) => {
          return `api/tests/mailers/${match[2]}.test.ts`;
        },
      },
    ],
  },
});

Der neue Mehrzweck-Typ Matchers

Vitest verfügt jetzt über einen Matchers-Typ, den Sie erweitern können, um die Typunterstützung für alle Ihre benutzerdefinierten Matcher zentral hinzuzufügen. Dieser Typ gilt für alle diese Anwendungsfälle:

• expect().to*
• expect.to*
• expect.extend({ to* })

Um beispielsweise einen typsicheren toBeFoo-Matcher zu haben, können Sie so etwas schreiben:

import { expect } from 'vitest';

interface CustomMatchers<R = unknown> {
  toBeFoo: (arg: string) => R;
}

declare module 'vitest' {
  interface Matchers<T = any> extends CustomMatchers<T> {}
}

expect.extend({
  toBeFoo(actual, arg) {
    //            ^?
    // ... Implementierung
    return {
      pass: true,
      message: () => '',
    };
  },
});

expect('foo').toBeFoo('foo');
expect.toBeFoo('foo');

sequence.groupOrder

Die neue Option sequence.groupOrder steuert die Reihenfolge, in der das Projekt seine Tests ausführt, wenn mehrere Projekte verwendet werden.

• Projekte mit der gleichen Gruppenordnungsnummer werden zusammen gestartet, und Gruppen werden von der niedrigsten zur höchsten Nummer verarbeitet.
• Wenn Sie diese Option nicht konfigurieren, werden alle Projekte parallel ausgeführt.
• Wenn mehrere Projekte die gleiche Gruppenordnung verwenden, werden sie gleichzeitig gestartet.

Beispiel

Betrachten Sie dieses Beispiel:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'slow',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'fast',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'flaky',
          sequence: {
            groupOrder: 1,
          },
        },
      },
    ],
  },
});

Die Tests in diesen Projekten werden in folgender Reihenfolge ausgeführt:

 0. slow  |
          |> werden zusammen ausgeführt
 0. fast  |

 1. flaky |> wird nach slow und fast separat ausgeführt

---

Die vollständige Liste der Änderungen finden Sie im Vitest 3.2 Changelog.