Zum Hauptinhalt springen
Version: Nächste

Von v29 zu v30

Inoffizielle Beta-Übersetzung

Diese Seite wurde von PageTurner AI übersetzt (Beta). Nicht offiziell vom Projekt unterstützt. Fehler gefunden? Problem melden →

Aktualisieren Sie Jest von v29 auf v30? Dieser Leitfaden hilft bei der Anpassung Ihrer Konfiguration und Tests.

Hinweis

Den vollständigen Änderungsumfang finden Sie im Changelog.

Hinweis

Aktualisieren Sie von einer älteren Version? Den Upgrade-Leitfaden von v28 zu v29 finden Sie hier.

Kompatibilität​

  • Jest 30 beendet den Support für Node 14, 16, 19 und 21. Die minimal unterstützte Node-Version ist nun 18.x. Stellen Sie vor dem Upgrade sicher, dass Ihre Umgebung eine kompatible Node-Version verwendet.

  • Die minimale TypeScript-Version ist nun 5.4. Aktualisieren Sie TypeScript, falls Sie Typdefinitionen von Jest (oder seinen Paketen) verwenden.

  • Das Paket jest-environment-jsdom nutzt jetzt JSDOM v26. Dies kann Verhaltensänderungen in der DOM-Umgebung verursachen. Bei Unterschieden in DOM-Verhalten oder neuen Warnungen konsultieren Sie die JSDOM-Release-Notes für v21–26.

Jest Expect & Matcher​

Entfernung von Alias-Matcher-Funktionen​

Alle Alias-Matcher-Namen wurden zugunsten ihrer Hauptnamen entfernt. Falls Sie veraltete Matcher-Namen verwenden, müssen Sie Ihre Tests anpassen:

  • Entfernte Aliase und ihre Ersetzungen:
    • expect(fn).toBeCalled() → expect(fn).toHaveBeenCalled()
    • expect(fn).toBeCalledTimes(n) → expect(fn).toHaveBeenCalledTimes(n)
    • expect(fn).toBeCalledWith(arg) → expect(fn).toHaveBeenCalledWith(arg)
    • expect(fn).lastCalledWith(arg) → expect(fn).toHaveBeenLastCalledWith(arg)
    • expect(fn).nthCalledWith(n, arg) → expect(fn).toHaveBeenNthCalledWith(n, arg)
    • expect(fn).toReturn() → expect(fn).toHaveReturned()
    • expect(fn).toReturnTimes(n) → expect(fn).toHaveReturnedTimes(n)
    • expect(fn).toReturnWith(val) → expect(fn).toHaveReturnedWith(val)
    • expect(fn).lastReturnedWith(val) → expect(fn).toHaveLastReturnedWith(val)
    • expect(fn).nthReturnedWith(n, val) → expect(fn).toHaveNthReturnedWith(n, val)
    • expect(func).toThrowError(message) → expect(func).toThrow(message)
Hinweis

Diese Alias-Methoden waren seit Jest 26 veraltet und werden in Jest 30 vollständig entfernt. Führen Sie eine globale Suche-und-Ersetze-Operation in Ihrem Codebase durch, um die kanonischen Matcher-Namen zu verwenden. Die Funktionalität ist identisch – nur die Methodennamen haben sich geändert. (Bei Verwendung von ESLint mit eslint-plugin-jest kann die Regel no-alias-methods diese Anpassung automatisieren.)

Nicht aufzählbare Eigenschaften​

Nicht aufzählbare Objekteigenschaften werden standardmäßig nicht mehr von Objekt-Matchern berücksichtigt. Dies kann expect.objectContaining oder Gleichheitsprüfungen beeinflussen.

Verbesserte Typinferenz für CalledWith​

TypeScript-Nutzer: Die Typen der CalledWith-Matcher-Familie (z.B. toHaveBeenCalledWith) wurden verbessert, um Funktionsparametertypen abzuleiten. Dies erkennt Typinkonsistenzen in den meisten Fällen genauer. Es handelt sich um eine Compile-Time Breaking Change.

Falls Sie Aufrufe mit Argumenten getestet haben, die nicht mit den Parametertypen der eigentlichen Funktion übereinstimmen, könnte TypeScript jetzt Fehler in diesen Tests anzeigen. Beispielsweise wird bei einer Funktion, die als Typ number erwartet, der Aufruf expect(fn).toHaveBeenCalledWith("string") von TypeScript 5 in Kombination mit Jest 30-Typen beanstandet. Das Laufzeitverhalten des Matchers bleibt unverändert.

Um neue TypeScript-Fehler zu beheben, stellen Sie sicher, dass Ihre Testargumente mit den erwarteten Typen der Funktion übereinstimmen (oder verwenden Sie Typcasts, wenn Sie absichtlich abweichende Typen übergeben).

Diese Änderung wirkt sich nicht auf die Laufzeit aus, kann aber bisher unentdeckte Typfehler in Ihren Tests aufdecken – was Ihre Tests typsicherer macht.

Konfigurationsanpassungen​

Unterstützung für .mts- und .cts-Dateierweiterungen​

Jest 30 erweitert die Unterstützung für ESM- und TypeScript-Moduldateierweiterungen:

  • Die Standard-moduleFileExtensions enthalten nun zusätzlich zu den üblichen Erweiterungen auch .mts und .cts (TypeScript ESM- und CommonJS-Module).

  • Die Standardmuster für testMatch und testRegex wurden aktualisiert, um .mjs-, .cjs-, .mts- und .cts-Dateien als Testdateien zu erkennen.

Hinweis

Falls Ihr Projekt Dateien mit diesen Erweiterungen enthält, die nicht als Module oder Tests behandelt werden sollen, müssen Sie möglicherweise Ihre Konfiguration anpassen. Umgekehrt werden Testdateien mit diesen Erweiterungen jetzt standardmäßig erkannt (vorherige manuelle Konfigurationen können entfernt werden).

Umbenennung von --testPathPattern zu --testPathPatterns​

Beim Filtern von Tests nach Pfaden beachten: Das CLI-Flag --testPathPattern heißt nun --testPathPatterns. Mehrere Muster können durch Leerzeichen getrennt oder durch wiederholtes Setzen des Flags übergeben werden. Beispiel:

# Old (Jest 29)
jest --testPathPattern="unit/.*"

# New (Jest 30)
jest --testPathPatterns "unit/.*" "integration/.*"

Intern konsolidiert Jest diese Muster in ein TestPathPatterns-Objekt. Bei programmatischen Aufrufen von Jests Watch-Modus mit testPathPattern muss nun stattdessen eine TestPathPatterns-Instanz erstellt werden.

Entfernung von --init-Befehl​

Der interaktive Konfigurationsinitialisierungsbefehl jest --init wurde entfernt. Dieser veraltete Befehl diente zum Erstellen einer Jest-Konfigurationsdatei. Zum Anlegen einer Konfiguration können Sie ausführen:

npm init jest@latest
# Or for Yarn
yarn create jest
# Or for pnpm
pnpm create jest

Weitere CLI-Änderungen​

  • Jest validiert jetzt CLI-Flags mit erforderlichen Argumenten strenger. Bei Flags wie --maxWorkers oder --selectProjects muss ein Wert angegeben werden (z.B. --maxWorkers=50%). Früher wurden fehlende Werte oft stillschweigend mit Standardwerten belegt – jetzt wird ein Fehler ausgelöst. Stellen Sie sicher, dass Skripte oder npm-Befehle mit Jest-Flags die notwendigen Argumente enthalten.

  • Bei Verwendung der --filter-Option zum Filtern von Testdateien (fortgeschrittener Anwendungsfall mit Pfadangabe einer Filterimplementierung) hat sich die erwartete Schnittstelle geändert. Filterfunktionen müssen jetzt ein Objekt der Form {filtered: Array<string>} zurückgeben. Ältere Rückgabeformate (z.B. direkte Arrays) werden nicht mehr akzeptiert. Passen Sie benutzerdefinierte Testfilterfunktionen entsprechend an, um ein Objekt mit einer filtered-Eigenschaft zurückzugeben, wie dokumentiert.

Änderungen im Testrunner-Verhalten​

Unbehandelte Promise-Rejections in Tests​

Jest korrigiert nun die Behandlung von Promises, die abgelehnt und später abgefangen werden, um falsche Testfehler zu vermeiden. In Jest 29 konnte eine asynchron (nach dem Test-Tick) behandelte Promise-Rejection fälschlich zum Testabbruch führen. Jest 30 wartet jetzt einen zusätzlichen Event-Loop-Zyklus ab, bevor ein Test bei einer unbehandelten Rejection fehlschlägt.

Hinweis

Es sollten weniger falsch-positive Meldungen über nicht behandelte Promise-Ablehnungen auftreten. Tests, die zuvor aufgrund von asynchron behandelten Ablehnungen fehlschlugen, sollten jetzt erfolgreich sein. Diese Änderung kann jedoch die Testausführung leicht verlangsamen, insbesondere bei Tests, die bewusst Ablehnungen auslösen. Um Leistungseinbußen zu mildern, wurde ein neues Konfigurationsflag waitForUnhandledRejections eingeführt. Wenn dieses Flag deaktiviert wird, kann das vorherige Verhalten (kein Warten) wiederhergestellt werden, falls absolut nötig. Die meisten Nutzer müssen dies nicht ändern – die Standardeinstellung priorisiert nun Korrektheit, indem falsche Fehler verhindert werden.

Benutzerdefinierte Test-Sequenzer​

Falls du einen benutzerdefinierten Test-Sequenzer verwendest (eine Klasse, die von Jests TestSequencer erbt), musst du ihn für Jest 30 anpassen. Jest übergibt jetzt zusätzlichen Kontext an den Test-Sequenzer. Konkret wurde die TestSequencer-API erweitert, um globalConfig und contexts für deinen Sequenzer verfügbar zu machen.

Erforderliche globalConfig in Runtime​

Für Nutzer von Jests programmatischen APIs: Das Erstellen einer Runtime erfordert jetzt einen globalConfig-Parameter. Wenn du jest.runCLI oder ähnliche Hilfsmittel verwendest, stelle sicher, dass alle erforderlichen Optionen gemäß der aktualisierten API übergeben werden. (Die typische Nutzung über jest-CLI oder npm test ist von dieser Änderung nicht betroffen.)

Snapshots und Ausgabeänderungen​

Veraltete goo.gl-URLs wurden aus Snapshot-Tests entfernt. Diese Änderung aktualisiert bestehende Snapshots, um alle goo.gl-Links durch vollständige, ungekürzte URLs zu ersetzen.

Fehlerursachen in Snapshots​

Die Fehlerserialisierung in Snapshots hat sich geändert. Jests Snapshot-Serializer wird nun die cause-Eigenschaft eines Error (sofern vorhanden) in die Fehlerausgabe aufnehmen.

Leerstring-Darstellung in React​

Der React-spezifische Snapshot-Serializer rendert leere String-Kinder ("") nicht mehr in der Ausgabe. In Jest 29 erschien ein leeres String-Kind in einem React-Element als "" im Snapshot; in Jest 30 wird es weggelassen (als inhaltslos behandelt).

Verbesserte Objektausgabe in pretty-format​

ArrayBuffer und DataView werden jetzt menschenlesbar statt als Objekte mit internen Feldern dargestellt.

Änderungen an der Jest-Mock-API​

jest.genMockFromModule entfernt​

Die veraltete Funktion jest.genMockFromModule(moduleName) wurde entfernt. Sie war bereits durch jest.createMockFromModule(moduleName) ersetzt worden. Falls du noch genMockFromModule verwendest, wechsle zu createMockFromModule – das Verhalten ist identisch. Beispiel:

Alter Code (Jest 29):

const mockFs = jest.genMockFromModule('fs');

Neuer Code (Jest 30):

const mockFs = jest.createMockFromModule('fs');

Entfernte Mock-Funktionstypen​

Hinweis

Die Typänderungen betreffen nur Nutzer, die Jest-APIs explizit importieren:

import {expect, jest, test} from '@jest/globals';

Einige TypeScript-Typen für Mock-Funktionen wurden aus der öffentlichen API entfernt.

  • MockFunctionMetadata

  • MockFunctionMetadataType

  • SpyInstance

Falls du jest.SpyInstance verwendet hast (z.B. zur Annotation von jest.spyOn-Rückgaben), solltest du auf jest.Spied wechseln.

jest.mock funktioniert nur mit beachteter Groß-/Kleinschreibung im Modulpfad​

jest.mock() funktioniert ab sofort nur noch bei exakter Beachtung der Groß-/Kleinschreibung im Modulpfad. Dies betrifft maximal Randfälle, da die meisten Nutzer ohnehin dem Dateinamenverhalten ihres Betriebssystems folgen. Wir empfehlen, korrekt benannte Modulpfade zu verwenden, um ähnliche Probleme künftig zu vermeiden.

Alter Code (Jest 29):

jest.mock('./path/to/FILENAME.js'); // This works EVEN when you only have `filename.js`

Neuer Code (Jest 30):

jest.mock('./path/to/filename.js'); // This strictly works when you ONLY have `filename.js`

Modul- und Runtime-Änderungen​

ESM-Modulunterstützung und interne Umstrukturierung​

Jest hat signifikante Änderungen an der Bündelung und dem Export seiner Pakete vorgenommen:

  • Alle internen Module von Jest sind jetzt in einzelne Dateien gebündelt, um den Start zu beschleunigen. Das bedeutet, dass beim Installieren von Jest die Anzahl der geladenen Dateien stark reduziert wird (was die Leistung verbessert). Ein Nebeneffekt ist jedoch, dass nicht offizielle Deep Imports in Jest-Pakete wahrscheinlich brechen werden. Wenn Sie beispielsweise zuvor etwas wie require('jest-runner/build/testWorker') verwendet haben (was kein öffentliches API ist), existiert dieser Pfad nicht mehr. Lösung: Verwenden Sie nur öffentliche APIs oder dokumentierte Schnittstellen von Jest. Wenn Sie auf ein internes Modul angewiesen sind, das Ihrer Meinung nach Teil der öffentlichen API sein sollte, öffnen Sie bitte einen Pull Request, um es verfügbar zu machen.

  • Jest-Pakete bieten jetzt ESM-Wrapper. Dies ist Teil der laufenden Arbeit, um Jest in einem ESM-Kontext ausführen zu können. Alle offiziellen Jest-Pakete exportieren sich korrekt über das "exports"-Feld in package.json. Für die meisten Benutzer hat dies keine direkten Auswirkungen – Sie verwenden Jest weiterhin auf dieselbe Weise. Wenn Sie jedoch ein Tool oder Plugin warten, das Jest-Module importiert, stellen Sie sicher, dass Sie die Paketnamen als Imports verwenden (die über die Modulauflösung von Node aufgelöst werden).

Diese Änderungen gelten als Breaking Changes für alle, die in Jests Interna eingreifen, nicht jedoch für die typische Verwendung der Jest-CLI und Konfiguration. Führen Sie nach dem Upgrade Ihre Tests normal aus – wenn Sie Modulauflösungsfehler bezüglich eigener Jest-Module erhalten, liegt dies wahrscheinlich an einem nicht unterstützten Import, der entfernt oder aktualisiert werden muss.

Änderungen beim Glob-Pattern-Matching​

Jests Abhängigkeit für Dateipattern-Matching (glob) wurde auf v10 aktualisiert. Glob v10 kann leichte Unterschiede in Patternsyntax und Verhalten aufweisen.

Eine bemerkenswerte Änderung ist, dass glob@10 Klammererweiterungen und Extglobs etwas anders behandelt und bei einigen Patterns strenger ist. Wenn Sie benutzerdefinierte testMatch-Patterns, moduleNameMapper-Patterns oder andere glob-basierte Konfigurationen haben, sollten diese in den meisten Fällen weiterhin funktionieren. Seien Sie sich nur bewusst, dass Sie ein Pattern möglicherweise für die neue Glob-Engine anpassen müssen, wenn es Dateien nicht mehr wie gewohnt erfasst.

Fazit​

Aktualisieren Sie auf Jest 30, indem Sie zunächst sicherstellen, dass Ihre Umgebung die neuen Node.js- und TypeScript-Anforderungen erfüllt. Aktualisieren Sie Ihre Jest-Konfigurationsdatei und CLI-Nutzung für die umbenannten und entfernten Optionen (insbesondere testPathPatterns und die Entfernung von --init). Führen Sie Ihre Testsuite aus und beheben Sie auftretende Fehler:

  • Reparieren Sie Tests, die entfernte Matcher-Aliase verwenden, indem Sie diese durch offizielle Matcher-Namen ersetzen.

  • Aktualisieren Sie Snapshots, die aufgrund von Formatierungsänderungen fehlschlagen (Fehlerursachen, leere Strings usw.).

  • Achten Sie auf TypeScript-Compiler-Fehler – sie weisen Sie darauf hin, veraltete API-Verwendungen (wie genMockFromModule oder entfernte Typen) zu aktualisieren und Tests anzupassen, wo Typen jetzt strenger sind.

Viel Erfolg beim Testen!