Migrationsleitfaden

Migration von Vitest 0.34.6

Mindestanforderungen

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

Alle @vitest/* Subpakete benötigen Vitest Version 1.0.

Snapshot-Aktualisierung #3961

In Snapshots werden Anführungszeichen nicht mehr maskiert (escaped). Alle Snapshots verwenden nun Backticks (`), auch wenn die Zeichenkette nur eine Zeile lang ist.

1. Anführungszeichen werden nicht mehr maskiert:

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

2. Einzeilige Snapshots verwenden nun "`"-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, sind keine Änderungen erforderlich.

• Die Erweiterung von SnapshotClient zur Überschreibung der equalityCheck-Methode ist nicht mehr notwendig: Übergeben Sie sie stattdessen als isEqual, wenn Sie eine Instanz erstellen.
• client.setTest wurde in client.startCurrentRun umbenannt.
• client.resetCurrent wurde in client.finishCurrentRun umbenannt.

Standardisierung der Pools #4172

Um die Anpassung des Runners zu vereinfachen, wurden zahlreiche Konfigurationsoptionen entfernt. Beachten Sie die Migrationsbeispiele, wenn Sie --threads oder andere zugehörige 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 der Codeabdeckung #4265, #4442

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

Die API-Struktur der Coverage-Schwellenwerte wurde geändert und unterstützt jetzt die Angabe von Schwellenwerten für einzelne 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,
+      }
    }
  }
})

Typen für Mocks #4400

Einige Typen wurden zugunsten der "Mock"-Benennung im Jest-Stil 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 weiterhin möglich, process.nextTick zu mocken, indem Sie es explizit mit vi.useFakeTimers({ toFake: ['nextTick'] }) angeben.

Das Mocken von process.nextTick ist jedoch nicht möglich, wenn --pool=forks verwendet wird. Verwenden Sie eine andere --pool-Option, falls Sie process.nextTick mocken müssen.

Migration von Jest

Vitest wurde mit einer Jest-kompatiblen API entwickelt, um die Migration von Jest so einfach wie möglich zu gestalten. Dennoch kann es zu folgenden Unterschieden kommen:

Globals als Standard

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

Wenn Sie sich entscheiden, Globals deaktiviert zu lassen, beachten Sie, dass gängige Bibliotheken wie testing-library keine automatische DOM-Cleanup durchführen.

Modul-Mocks

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

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

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

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 in Jest, 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'); 

Erweitern des Mockings auf externe Bibliotheken

Wenn Jest dies standardmäßig tut und Sie ein Modul mocken und dieses Mocking auf andere externe Bibliotheken ausweiten möchten, die dasselbe Modul verwenden, müssen Sie explizit angeben, welche Drittanbieterbibliothek gemockt werden soll, damit die externe Bibliothek Teil Ihres Quellcodes ist. Verwenden Sie dazu server.deps.inline.

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

Zugriff auf die Rückgabewerte eines gemockten Promise

Sowohl Jest als auch Vitest speichern die Ergebnisse aller Mock-Aufrufe im mock.results Array, wobei die Rückgabewerte jedes Aufrufs in der value-Eigenschaft gespeichert werden. Wenn Sie jedoch ein Promise mocken oder ausspionieren (z. B. mit mockResolvedValue), ist die value-Eigenschaft in Jest ein Promise, während sie in Vitest zu einem aufgelösten Wert wird, sobald das Promise aufgelöst wurde.

await expect(spy.mock.results[0].value).resolves.toBe(123); 
expect(spy.mock.results[0].value).toBe(123); 

Umgebungsvariablen

Wie Jest setzt Vitest NODE_ENV auf test, falls es zuvor nicht gesetzt war. Vitest bietet auch ein Pendant zu JEST_WORKER_ID namens VITEST_POOL_ID (immer kleiner oder gleich maxThreads). Vergessen Sie nicht, diese Variable umzubenennen, falls Sie sie verwenden. Vitest stellt außerdem VITEST_WORKER_ID bereit, eine eindeutige ID eines laufenden Workers. Diese Zahl wird nicht von maxThreads beeinflusst, sondern erhöht sich mit jedem erstellten Worker.

Eigenschaften ersetzen

Wenn Sie das Objekt ändern möchten, verwenden Sie die replaceProperty API in Jest. Sie können auch vi.stubEnv oder vi.spyOn verwenden, um dasselbe in Vitest zu tun.

Done Callback

Ab Vitest v0.10.0 ist die Deklaration von Tests im Callback-Stil veraltet. Sie können diese in async/await-Funktionen umschreiben oder Promises verwenden, um den Callback-Stil nachzubilden.

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

Hooks

beforeAll/beforeEach Hooks können in Vitest eine Teardown-Funktion zurückgeben. Daher müssen Sie Ihre Hook-Deklarationen möglicherweise anpassen, wenn diese andere Werte als undefined oder null zurückgeben:

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

In Jest werden Hooks nacheinander (einer nach dem anderen) aufgerufen. Standardmäßig führt Vitest Hooks parallel aus. Um das Verhalten von Jest 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 von vitest importieren:

let fn: jest.Mock<string, [string]>; 
import type { Mock } from 'vitest'; 
let fn: Mock<[string], string>; 

Darüber hinaus verwendet Vitest den Typ Args als erstes Argument anstelle von Returns, wie im Diff ersichtlich.

Timer

Vitest unterstützt die Legacy-Timer von Jest 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 jest-serializer-vue Paket 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 maskierte "-Zeichen.