Migrationsleitfaden

Migration zu Vitest 3.0

Testoptionen als drittes Argument

Vitest 3.0 gibt eine Warnung aus, wenn Sie ein Objekt als drittes Argument an die Funktionen test oder describe übergeben:

test('validation works', () => {
  // ...
}, { retry: 3 }); 

test('validation works', { retry: 3 }, () => { 
  // ...
});

Die nächste Hauptversion wird einen Fehler auslösen, wenn das dritte Argument ein Objekt ist. Bitte beachten Sie, dass die Angabe eines Timeouts als Zahl nicht veraltet ist:

test('validation works', () => {
  // ...
}, 1000); // Ok ✅

browser.name und browser.providerOptions sind veraltet

Sowohl browser.name als auch browser.providerOptions werden in Vitest 4 entfernt. Verwenden Sie stattdessen die neue Option browser.instances:

export default defineConfig({
  test: {
    browser: {
      name: 'chromium', 
      providerOptions: { 
        launch: { devtools: true }, 
      }, 
      instances: [ 
        { 
          browser: 'chromium', 
          launch: { devtools: true }, 
        }, 
      ], 
    },
  },
})

Mit dem neuen Feld browser.instances können Sie auch mehrere Browserkonfigurationen gleichzeitig angeben.

spy.mockReset stellt jetzt die ursprüngliche Implementierung wieder her

Zuvor gab es keine einfache Möglichkeit, einen Spy auf seine ursprüngliche Implementierung zurückzusetzen, ohne ihn erneut anzuwenden. Jetzt setzt spy.mockReset die Implementierungsfunktion auf die ursprüngliche zurück, anstatt auf eine gefälschte No-Operation.

const foo = {
  bar: () => 'Hello, world!',
};

vi.spyOn(foo, 'bar').mockImplementation(() => 'Hello, mock!');

foo.bar(); // 'Hello, mock!'

foo.bar.mockReset();

foo.bar(); // undefined
foo.bar(); // 'Hello, world!'

vi.spyOn verwendet Mock wieder, wenn Methode bereits gemockt ist

Zuvor wies Vitest immer einen neuen Spy zu, wenn ein Objekt überwacht wurde. Dies führte zu Fehlern bei mockRestore, da es den Spy auf den vorherigen zurücksetzte, anstatt auf die ursprüngliche Funktion:

vi.spyOn(fooService, 'foo').mockImplementation(() => 'bar');
vi.spyOn(fooService, 'foo').mockImplementation(() => 'bar');
vi.restoreAllMocks();
vi.isMockFunction(fooService.foo); // true
vi.isMockFunction(fooService.foo); // false

Standardwerte für Fake-Timer

Vitest bietet keine Standardoptionen mehr für fakeTimers.toFake. Vitest mockt jetzt jede verfügbare Timer-API (außer nextTick). Insbesondere wird performance.now() jetzt gemockt, wenn vi.useFakeTimers aufgerufen wird.

vi.useFakeTimers();

performance.now(); // original
performance.now(); // fake

Sie können zum vorherigen Verhalten zurückkehren, indem Sie beim Aufruf von vi.useFakeTimers oder global in der Konfiguration spezifische Timer angeben:

export default defineConfig({
  test: {
    fakeTimers: {
      toFake: [ 
        'setTimeout', 
        'clearTimeout', 
        'setInterval', 
        'clearInterval', 
        'setImmediate', 
        'clearImmediate', 
        'Date', 
      ] 
    },
  },
})

Strengere Fehlergleichheit

Vitest prüft jetzt mehr Eigenschaften beim Vergleich von Fehlern über toEqual oder toThrowError. Vitest vergleicht jetzt name, message, cause und AggregateError.errors. Für Error.cause erfolgt der Vergleich asymmetrisch:

expect(new Error('hi', { cause: 'x' })).toEqual(new Error('hi')); // ✅
expect(new Error('hi')).toEqual(new Error('hi', { cause: 'x' })); // ❌

Zusätzlich zur Überprüfung weiterer Eigenschaften vergleicht Vitest jetzt auch die Fehlerprototypen. Wenn beispielsweise ein TypeError ausgelöst wurde, sollte der Gleichheitstest auf TypeError verweisen, nicht auf Error:

expect(() => {
  throw new TypeError('type error');
})
  .toThrowError(new Error('type error')) 
  .toThrowError(new TypeError('type error')); 

Weitere Details finden Sie im PR: #5876.

module-Bedingungsexport wird in Vite 6 standardmäßig nicht aufgelöst

Vite 6 ermöglicht flexiblere Optionen für resolve.conditions, und Vitest konfiguriert es so, dass der module-Bedingungsexport standardmäßig ausgeschlossen wird. Siehe auch den Vite 6 Migrationsleitfaden für Details zu den Änderungen auf Vite-Seite.

Custom-Typ ist veraltet API

Der Typ Custom ist jetzt ein Alias für den Typ Test. Beachten Sie, dass Vitest die öffentlichen Typen in 2.1 aktualisiert und die exportierten Namen in RunnerCustomCase und RunnerTestCase geändert hat:

import {
  RunnerCustomCase, 
  RunnerTestCase, 
} from 'vitest';

Wenn Sie getCurrentSuite().custom() verwenden, ist der type der zurückgegebenen Aufgabe nun 'test'. Der Typ Custom wird in Vitest 4 entfernt.

Der Typ WorkspaceSpec wird nicht mehr verwendet API

In der öffentlichen API wurde dieser Typ zuvor in benutzerdefinierten Sequencern verwendet. Bitte migrieren Sie stattdessen zu TestSpecification.

onTestFinished und onTestFailed erhalten jetzt einen Kontext

Die Hooks onTestFinished und onTestFailed erhielten zuvor ein Testergebnis als erstes Argument. Jetzt erhalten sie einen Testkontext, ähnlich wie beforeEach und afterEach.

Änderungen an der Snapshot-API API

Die öffentliche Snapshot-API in @vitest/snapshot wurde geändert, um mehrere Zustände innerhalb eines einzigen Laufs zu unterstützen. Weitere Details finden Sie im PR: #6817

Beachten Sie, dass diese Änderungen nur Entwickler betreffen, die die Snapshot-API direkt verwenden. Es gab keine Änderungen an der .toMatchSnapshot-API.

Änderungen an der Typensignatur von resolveConfig API

Die Funktion resolveConfig ist jetzt vielseitiger. Anstatt eine bereits aufgelöste Vite-Konfiguration entgegenzunehmen, akzeptiert sie jetzt eine Benutzerkonfiguration und gibt die aufgelöste Konfiguration zurück.

Diese Funktion wird intern nicht verwendet und wird ausschließlich als öffentliche API bereitgestellt.

Bereinigte vitest/reporters-Typen API

Der vitest/reporters-Einstiegspunkt exportiert jetzt nur noch Reporter-Implementierungen und Options-Typen. Wenn Sie Zugriff auf TestCase/TestSuite und andere aufgabenbezogene Typen benötigen, importieren Sie diese zusätzlich von vitest/node.

Coverage ignoriert Testdateien, auch wenn coverage.excludes überschrieben wird.

Es ist nicht mehr möglich, Testdateien in den Coverage-Bericht aufzunehmen, indem coverage.excludes überschrieben wird. Testdateien werden jetzt immer ausgeschlossen.

Migration zu Vitest 2.0

Standard-Pool ist forks

Vitest 2.0 ändert die Standardkonfiguration für pool auf 'forks' für bessere Stabilität. Die vollständige Motivation können Sie im PR nachlesen.

Wenn Sie poolOptions ohne Angabe eines pool verwendet haben, müssen Sie möglicherweise die Konfiguration aktualisieren:

export default defineConfig({
  test: {
    poolOptions: {
      threads: { 
        singleThread: true, 
      }, 
      forks: { 
        singleFork: true, 
      }, 
    }
  }
})

Hooks laufen in einem Stack

Vor Vitest 2.0 wurden alle Hooks parallel ausgeführt. In 2.0 laufen alle Hooks seriell. Zusätzlich laufen afterAll/afterEach-Hooks in umgekehrter Reihenfolge.

Um zur parallelen Ausführung von Hooks zurückzukehren, ändern Sie sequence.hooks auf 'parallel':

export default defineConfig({
  test: {
    sequence: { 
      hooks: 'parallel', 
    }, 
  },
})

suite.concurrent führt alle Tests gleichzeitig aus

Zuvor gruppierte die Angabe von concurrent in einer Suite gleichzeitige Tests nach Suiten und führte diese dann sequenziell aus. Jetzt, dem Verhalten von Jest folgend, laufen alle Tests gleichzeitig (vorbehaltlich der maxConcurrency-Grenzen).

V8 Coverage's coverage.ignoreEmptyLines ist standardmäßig aktiviert

Der Standardwert von coverage.ignoreEmptyLines ist jetzt true. Diese signifikante Änderung kann sich auf Code-Abdeckungsberichte auswirken und erfordert möglicherweise Anpassungen der Coverage-Schwellenwerte für einige Projekte. Diese Anpassung betrifft nur die Standardeinstellung, wenn coverage.provider 'v8' ist.

Entfernung der Option watchExclude

Vitest verwendet den Vite-Watcher. Schließen Sie Dateien oder Verzeichnisse aus, indem Sie sie zu server.watch.ignored hinzufügen:

export default defineConfig({
  server: { 
    watch: { 
      ignored: ['!node_modules/examplejs'] 
    } 
  } 
})

--segfault-retry entfernt

Aufgrund der Änderungen am Standard-Pool wird diese Option nicht mehr benötigt. Wenn Sie Segfault-Fehler erleben, versuchen Sie, zum 'forks'-Pool zu wechseln. Wenn das Problem weiterhin besteht, öffnen Sie bitte ein neues Issue mit einer Reproduktion.

Leere Aufgabe in Suite-Aufgaben entfernt

Dies ist eine Änderung an der erweiterten Task-API. Zuvor führte das Durchlaufen von .suite schließlich zu der leeren internen Suite, die anstelle einer Datei-Task verwendet wurde.

Dies macht .suite optional; wenn die Aufgabe auf der obersten Ebene definiert ist, wird sie keine Suite haben. Sie können auf die .file-Eigenschaft zurückgreifen, die jetzt in allen Aufgaben vorhanden ist (einschließlich der Datei-Task selbst, seien Sie also vorsichtig, um eine Endlosrekursion zu vermeiden).

Diese Änderung entfernt auch die Datei aus expect.getState().currentTestName und macht expect.getState().testPath erforderlich.

task.meta wird zum JSON-Reporter hinzugefügt

Der JSON-Reporter gibt jetzt task.meta für jedes Assertionsergebnis aus.

Vereinfachte generische Typen von Mock-Funktionen (z.B. vi.fn<T>, Mock<T>)

Zuvor akzeptierte vi.fn<TArgs, TReturn> zwei generische Typen separat für Argumente und Rückgabewert. Dies wurde geändert, um direkt einen Funktionstyp vi.fn<T> zu akzeptieren, um die Verwendung zu vereinfachen.

import { vi } from 'vitest';
import type { Mock } from 'vitest';

const add = (x: number, y: number): number => x + y;

// using vi.fn<T>
const mockAdd = vi.fn<Parameters<typeof add>, ReturnType<typeof add>>(); 
const mockAdd = vi.fn<typeof add>(); 

// using Mock<T>
const mockAdd: Mock<Parameters<typeof add>, ReturnType<typeof add>> = vi.fn(); 
const mockAdd: Mock<typeof add> = vi.fn(); 

Zugriff auf aufgelöste mock.results

Zuvor löste Vitest mock.results-Werte auf, wenn die Funktion ein Promise zurückgab. Jetzt gibt es eine separate Eigenschaft mock.settledResults, die nur gefüllt wird, wenn das zurückgegebene Promise aufgelöst oder abgelehnt wird.

const fn = vi.fn().mockResolvedValueOnce('result');
await fn();

const result = fn.mock.results[0]; // 'result'
const result = fn.mock.results[0]; // 'Promise<result>'

const settledResult = fn.mock.settledResults[0]; // 'result'

Mit dieser Änderung führen wir auch neue toHaveResolved*-Matcher ein, ähnlich wie toHaveReturned, um die Migration zu erleichtern, falls Sie zuvor toHaveReturned verwendet haben:

const fn = vi.fn().mockResolvedValueOnce('result');
await fn();

expect(fn).toHaveReturned('result'); 
expect(fn).toHaveResolved('result'); 

Browser-Modus

Der Vitest Browser-Modus hat während der Beta-Phase viele Änderungen erfahren. Unsere Philosophie bezüglich des Browser-Modus können Sie auf der GitHub-Diskussionsseite nachlesen.

Die meisten Änderungen waren additiv, aber es gab einige kleine Breaking Changes:

• Der none-Provider wurde in preview umbenannt #5842
• preview-Provider ist jetzt Standard #5842
• indexScripts wurde in orchestratorScripts umbenannt #5842

Veraltete Optionen entfernt

Einige veraltete Optionen wurden entfernt:

• vitest typecheck-Befehl – stattdessen vitest --typecheck verwenden
• VITEST_JUNIT_CLASSNAME und VITEST_JUNIT_SUITE_NAME Umgebungsvariablen (stattdessen Reporter-Optionen verwenden)
• Überprüfung auf c8-Coverage (stattdessen coverage-v8 verwenden)
• Export von SnapshotEnvironment aus vitest – stattdessen aus vitest/snapshot importieren
• SpyInstance wurde zugunsten von MockInstance entfernt

Migration zu Vitest 1.0

Mindestanforderungen

Vitest 1.0 erfordert Vite 5.0 und Node.js 18 oder höher.

Alle @vitest/*-Unterpakete setzen Vitest Version 1.0 voraus.

Snapshots-Update #3961

Anführungszeichen in Snapshots werden nicht mehr escaped, und alle Snapshots verwenden Backtick-Anführungszeichen (`) selbst wenn der String nur eine einzelne Zeile umfasst.

1. Anführungszeichen werden nicht mehr escaped:

expect({ foo: 'bar' }).toMatchInlineSnapshot(`
  Object {
-    \\"foo\\": \\"bar\\",
+    "foo": "bar",
  }
`)

2. Einzeilige Snapshots verwenden jetzt "`"-Anführungszeichen anstelle von ':

- expect('some string').toMatchInlineSnapshot('"some string"')
+ expect('some string').toMatchInlineSnapshot(`"some string"`)

Es gab auch Änderungen am @vitest/snapshot-Paket. Wenn Sie es nicht direkt verwenden, müssen Sie nichts ändern.

• Sie müssen SnapshotClient nicht mehr erweitern, nur um die Methode equalityCheck zu überschreiben: Übergeben Sie sie einfach als isEqual beim Initiieren einer Instanz
• client.setTest wurde in client.startCurrentRun umbenannt
• client.resetCurrent wurde in client.finishCurrentRun umbenannt

Pools sind standardisiert #4172

Wir haben viele Konfigurationsoptionen entfernt, um die Konfiguration des Runners an Ihre Anforderungen anzupassen. Bitte schauen Sie sich die Migrationsbeispiele an, wenn Sie --threads oder andere verwandte Flags verwenden.

• --threads ist jetzt --pool=threads
• --no-threads ist jetzt --pool=forks
• --single-thread ist jetzt --poolOptions.threads.singleThread
• --experimental-vm-threads ist jetzt --pool=vmThreads
• --experimental-vm-worker-memory-limit ist jetzt --poolOptions.vmThreads.memoryLimit
• --isolate ist jetzt --poolOptions.<pool-name>.isolate und browser.isolate
• test.maxThreads ist jetzt test.poolOptions.<pool-name>.maxThreads
• test.minThreads ist jetzt test.poolOptions.<pool-name>.minThreads
• test.useAtomics ist jetzt test.poolOptions.<pool-name>.useAtomics
• test.poolMatchGlobs.child_process ist jetzt test.poolMatchGlobs.forks
• test.poolMatchGlobs.experimentalVmThreads ist jetzt test.poolMatchGlobs.vmThreads

{
  scripts: {
-    "test": "vitest --no-threads"
     // For identical behaviour:
+    "test": "vitest --pool forks --poolOptions.forks.singleFork"
     // Or multi parallel forks:
+    "test": "vitest --pool forks"

  }
}

{
  scripts: {
-    "test": "vitest --experimental-vm-threads"
+    "test": "vitest --pool vmThreads"
  }
}

{
  scripts: {
-    "test": "vitest --isolate false"
+    "test": "vitest --poolOptions.threads.isolate false"
  }
}

{
  scripts: {
-    "test": "vitest --no-threads --isolate false"
+    "test": "vitest --pool forks --poolOptions.forks.isolate false"
  }
}

Änderungen an Coverage #4265, #4442

Die Option coverage.all ist jetzt standardmäßig aktiviert. Das bedeutet, dass alle Projektdateien, die dem coverage.include-Muster entsprechen, verarbeitet werden, selbst wenn sie nicht ausgeführt werden.

Die Form der Coverage-Schwellenwerte-API wurde geändert, und sie unterstützt jetzt die Angabe von Schwellenwerten für bestimmte Dateien mithilfe von Glob-Mustern:

export default defineConfig({
  test: {
    coverage: {
-      perFile: true,
-      thresholdAutoUpdate: true,
-      100: true,
-      lines: 100,
-      functions: 100,
-      branches: 100,
-      statements: 100,
+      thresholds: {
+        perFile: true,
+        autoUpdate: true,
+        100: true,
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      }
    }
  }
})

Mock-Typen #4400

Einige Typen wurden zugunsten der Jest-ähnlichen "Mock"-Benennung entfernt.

- import { EnhancedSpy, SpyInstance } from 'vitest'
+ import { MockInstance } from 'vitest'

WARNING

SpyInstance ist zugunsten von MockInstance veraltet und wird in der nächsten Hauptversion entfernt.

Timer-Mocks #3925

vi.useFakeTimers() mockt process.nextTick nicht mehr automatisch. Es ist immer noch möglich, process.nextTick zu mocken, indem man es explizit über vi.useFakeTimers({ toFake: ['nextTick'] }) angibt.

Das Mocken von process.nextTick ist jedoch nicht möglich, wenn --pool=forks verwendet wird. Verwenden Sie eine andere --pool-Option, wenn Sie process.nextTick-Mocking benötigen.

Migration von Jest

Vitest wurde mit einer Jest-kompatiblen API entwickelt, um die Migration von Jest so einfach wie möglich zu machen. Trotz dieser Bemühungen können jedoch noch folgende Unterschiede auftreten:

Globals als Standard

Jest hat seine Globals API standardmäßig aktiviert, Vitest hingegen nicht. Sie können entweder Globals über die globals-Konfigurationseinstellung aktivieren oder Ihren Code so anpassen, dass stattdessen Importe aus dem vitest-Modul verwendet werden.

Wenn Sie sich entscheiden, Globals deaktiviert zu lassen, beachten Sie, dass gängige Bibliotheken wie testing-library keine automatische DOM-Bereinigung vornehmen werden.

spy.mockReset

Jests mockReset ersetzt die Mock-Implementierung durch eine leere Funktion, die undefined zurückgibt.

Vitests mockReset setzt die Mock-Implementierung auf ihren ursprünglichen Zustand zurück. Das heißt, wenn ein Mock, der mit vi.fn(impl) erstellt wurde, zurückgesetzt wird, wird die Mock-Implementierung auf impl zurückgesetzt.

Modul-Mocks

Beim Mocken eines Moduls in Jest ist der Rückgabewert des Factory-Arguments der Standardexport. In Vitest muss das Factory-Argument ein Objekt zurückgeben, in dem jeder Export explizit definiert ist. Zum Beispiel müsste das folgende jest.mock wie folgt aktualisiert werden:

jest.mock('./some-path', () => 'hello') 
vi.mock('./some-path', () => ({ 
  default: 'hello', 
})) 

Weitere Details finden Sie im Abschnitt vi.mock-API.

Auto-Mocking-Verhalten

Im Gegensatz zu Jest werden gemockte Module in <root>/__mocks__ nur geladen, wenn vi.mock() aufgerufen wird. Wenn Sie möchten, dass sie in jedem Test gemockt werden, wie es in Jest der Fall ist, können Sie sie in setupFiles mocken.

Importieren des Originals eines gemockten Pakets

Wenn Sie ein Paket nur teilweise mocken, haben Sie möglicherweise zuvor die Jest-Funktion requireActual verwendet. In Vitest sollten Sie diese Aufrufe durch vi.importActual ersetzen.

const { cloneDeep } = jest.requireActual('lodash/cloneDeep'); 
const { cloneDeep } = await vi.importActual('lodash/cloneDeep'); 

Mocking auf externe Bibliotheken erweitern

Im Gegensatz zu Jest, wo dies standardmäßig geschieht, müssen Sie in Vitest beim Mocken eines Moduls und der gewünschten Erweiterung dieses Mockings auf andere externe Bibliotheken, die dasselbe Modul verwenden, explizit angeben, welche Drittanbieterbibliothek gemockt werden soll. Dies geschieht, indem Sie server.deps.inline verwenden, damit die externe Bibliothek als Teil Ihres Quellcodes behandelt wird.

server.deps.inline: ["lib-name"]

expect.getState().currentTestName

Vitests test-Namen werden mit einem >-Symbol verbunden, um Tests und Suiten leichter voneinander abzugrenzen, während Jest ein Leerzeichen () verwendet.

- `${describeTitle} ${testTitle}`
+ `${describeTitle} > ${testTitle}`

Umgebungen

Genau wie Jest setzt Vitest NODE_ENV auf test, sofern es zuvor nicht gesetzt wurde. Vitest hat auch ein Gegenstück zu JEST_WORKER_ID, nämlich VITEST_POOL_ID (immer kleiner oder gleich maxThreads). Wenn Sie sich darauf verlassen, vergessen Sie nicht, es umzubenennen. Vitest exponiert auch VITEST_WORKER_ID, eine eindeutige ID eines laufenden Workers. Diese Zahl wird nicht von maxThreads beeinflusst und erhöht sich mit jedem erstellten Worker.

Eigenschaft ersetzen

Wenn Sie das Objekt ändern möchten, verwenden Sie in Jest die replaceProperty API. In Vitest können Sie dasselbe mit vi.stubEnv oder vi.spyOn erreichen.

Done Callback

Ab Vitest v0.10.0 ist der Callback-Stil zur Deklaration von Tests veraltet. Sie können sie umschreiben, um async/await-Funktionen zu verwenden, oder Promises nutzen, um den Callback-Stil zu emulieren.

it('should work', (done) => {  
it('should work', () => new Promise(done => { 
  // ...
  done()
}) 
})) 

Hooks

beforeAll/beforeEach-Hooks können in Vitest eine Teardown-Funktion zurückgeben. Aus diesem Grund müssen Sie möglicherweise Ihre Hook-Deklarationen umschreiben, wenn sie etwas anderes als undefined oder null zurückgeben:

beforeEach(() => setActivePinia(createTestingPinia())) 
beforeEach(() => { setActivePinia(createTestingPinia()) }) 

In Jest werden Hooks sequenziell (einer nach dem anderen) aufgerufen. Standardmäßig führt Vitest Hooks parallel aus. Um das Jest-Verhalten zu verwenden, aktualisieren Sie die Option sequence.hooks:

export default defineConfig({
  test: {
    sequence: { 
      hooks: 'list', 
    } 
  }
})

Typen

Vitest verfügt über kein Äquivalent zum jest-Namespace, daher müssen Sie Typen direkt aus vitest importieren:

let fn: jest.Mock<(name: string) => number>; 
import type { Mock } from 'vitest'; 
let fn: Mock<(name: string) => number>; 

Timer

Vitest unterstützt Jests Legacy-Timer nicht.

Timeout

Wenn Sie jest.setTimeout verwendet haben, müssen Sie zu vi.setConfig migrieren:

jest.setTimeout(5_000); 
vi.setConfig({ testTimeout: 5_000 }); 

Vue Snapshots

Dies ist keine Jest-spezifische Funktion, aber wenn Sie zuvor Jest mit dem vue-cli-Preset verwendet haben, müssen Sie das Paket jest-serializer-vue installieren und es in setupFiles verwenden:

vite.config.js

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    setupFiles: ['./tests/unit/setup.js'],
  },
});

tests/unit/setup.js

import vueSnapshotSerializer from 'jest-serializer-vue';

expect.addSnapshotSerializer(vueSnapshotSerializer);

Andernfalls werden Ihre Snapshots viele maskierte "-Zeichen enthalten.