Migrationsleitfaden

Migration auf Vitest 2.0

Standard-Pool ist forks

Vitest 2.0 ändert die Standardkonfiguration für pool zu 'forks', um die Stabilität zu verbessern. Eine detaillierte Begründung finden Sie im PR.

Wenn Sie poolOptions verwendet haben, ohne einen pool anzugeben, müssen Sie möglicherweise Ihre Konfiguration anpassen:

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

Hooks werden seriell ausgeführt

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

Um die parallele Ausführung von Hooks wiederherzustellen, setzen Sie sequence.hooks auf 'parallel':

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

suite.concurrent führt alle Tests gleichzeitig aus

Bisher führte die Angabe von concurrent in einer Suite dazu, dass gleichzeitige Tests nach Suiten gruppiert und sequenziell ausgeführt wurden. Nun, analog zum Verhalten von Jest, laufen alle Tests gleichzeitig (vorbehaltlich der maxConcurrency-Grenzen).

V8 Coverage: coverage.ignoreEmptyLines ist standardmäßig aktiviert

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

Entfernung der Option watchExclude

Vitest nutzt 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. Sollten Sie Segfault-Fehler feststellen, 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 einer leeren internen Suite, die anstelle einer Datei-Aufgabe verwendet wurde.

Dies macht .suite optional; ist die Aufgabe auf der obersten Ebene definiert, so hat sie keine Suite. Sie können auf die .file-Eigenschaft zurückgreifen, die jetzt in allen Aufgaben vorhanden ist (einschließlich der Datei-Aufgabe selbst; seien Sie also vorsichtig, um nicht in eine endlose Rekursion zu geraten).

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 für jedes Assertionsergebnis task.meta aus.

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

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

import { type Mock, vi } 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

Früher löste Vitest die mock.results-Werte auf, wenn die Funktion ein Promise zurückgab. Jetzt gibt es eine separate Eigenschaft mock.settledResults, die nur dann 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, die toHaveReturned ähnlich sind, 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 zum Browser-Modus können Sie auf der GitHub-Diskussionsseite nachlesen.

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

• Der none-Provider wurde in preview umbenannt #5842
• Der 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 auf Vitest 1.0

Mindestanforderungen

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

Alle @vitest/*-Unterpakete erfordern Vitest Version 1.0.

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 ist.

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 equalityCheck-Methode zu überschreiben; übergeben Sie sie einfach als isEqual bei der Initialisierung
• 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 Bedürfnisse anzupassen. Bitte schauen Sie sich die Migrationsbeispiele an, falls Sie sich auf --threads oder andere verwandte Flags verlassen.

• --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, auch wenn sie nicht ausgeführt werden.

Die Form der Coverage-Schwellenwerte-API wurde geändert und 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 mit 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 gestalten. Trotz dieser Bemühungen können Sie immer noch auf die folgenden Unterschiede stoßen:

Globals als Standard

Jest hat seine Globals API standardmäßig aktiviert, Vitest jedoch nicht. Sie können entweder Globals über die Konfigurationseinstellung globals aktivieren oder Ihren Code aktualisieren, um stattdessen Importe aus dem vitest-Modul zu nutzen.

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

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 mit jedem explizit definierten Export zurückgeben. 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__ nicht geladen, es sei denn, vi.mock() wird aufgerufen. 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 Jests 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'); 

Erweitern des Mockings auf externe Bibliotheken

Während Jest dies standardmäßig tut, sollten Sie beim Mocken eines Moduls und der Erweiterung dieses Mockings auf andere externe Bibliotheken, die dasselbe Modul verwenden, explizit angeben, welche Drittanbieterbibliothek gemockt werden soll. Dadurch wird die externe Bibliothek Teil Ihres Quellcodes, indem Sie server.deps.inline verwenden.

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

expect.getState().currentTestName

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

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

Umgebungen

Genau wie Jest setzt Vitest NODE_ENV auf test, falls es zuvor nicht gesetzt war. Vitest hat auch ein Gegenstück zu JEST_WORKER_ID namens VITEST_POOL_ID (immer kleiner oder gleich maxThreads). Wenn Sie sich darauf verlassen, vergessen Sie nicht, es umzubenennen. Vitest stellt auch VITEST_WORKER_ID zur Verfügung, 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 vi.stubEnv oder vi.spyOn verwenden, um dasselbe zu erreichen.

Done Callback

Ab Vitest v0.10.0 ist der Callback-Stil der Testdeklaration veraltet. Sie können sie umschreiben, um async/await-Funktionen zu verwenden, oder Promises verwenden, um den Callback-Stil nachzuahmen.

it('should work', (done) => {  // [!code --]
it('should work', () => new Promise(done => { // [!code ++]
  // ...
  done()
}) // [!code --]
})) // [!code ++]

Hooks

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

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

In Jest werden Hooks sequenziell (nacheinander) 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 hat 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 falls 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 enthalten Ihre Snapshots viele escaped "-Zeichen.