Vai al contenuto principale
{ "message": "Versione: Prossima", "description": "" }

Da v29 a v30

Traduzione Beta Non Ufficiale

Questa pagina è stata tradotta da PageTurner AI (beta). Non ufficialmente approvata dal progetto. Hai trovato un errore? Segnala problema →

Stai aggiornando Jest dalla v29 alla v30? Questa guida ti aiuterà a ristrutturare configurazione e test.

info

Consulta il changelog per la lista completa delle modifiche.

nota

Aggiorni da una versione precedente? Trovi la guida per v28→v29 qui.

Compatibilità​

  • Jest 30 rimuove il supporto per Node 14, 16, 19 e 21. Le versioni minime supportate sono ora 18.x. Verifica di usare una versione compatibile di Node prima dell'aggiornamento.

  • La versione minima di TypeScript è ora la 5.4. Aggiorna TypeScript se utilizzi le definizioni dei tipi di Jest (o suoi pacchetti).

  • Il pacchetto jest-environment-jsdom utilizza ora JSDOM v26. Potrebbero verificarsi cambiamenti comportamentali nell'ambiente DOM. In caso di differenze o nuovi warning, consulta le release note di JSDOM per v21–26.

Expect e Matchers di Jest​

Rimozione delle funzioni matcher alias​

Tutti i nomi alias dei matcher sono stati rimossi a favore dei nomi principali. Se utilizzi ancora nomi deprecati, dovrai aggiornare i test:

  • Alias rimossi e sostituzioni:
    • 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)
info

Questi alias erano deprecati da Jest 26 e in Jest 30 sono stati completamente rimossi. Esegui una ricerca/sostituzione globale nel codice per usare i nomi canonici dei matcher. La funzionalità è identica - cambiano solo i nomi dei metodi. (Con ESLint e eslint-plugin-jest, la regola no-alias-methods automatizza questa sostituzione.)

Proprietà non enumerabili​

Le proprietà non enumerabili degli oggetti sono ora escluse per impostazione predefinita nei matcher. Ciò potrebbe influenzare expect.objectContaining o i controlli di uguaglianza.

Miglioramento dell'inferenza dei tipi per CalledWith​

Utenti TypeScript: i tipi dei matcher della famiglia CalledWith (es. toHaveBeenCalledWith) sono stati migliorati per inferire i tipi dei parametri. Rileverà in modo più accurato le incongruenze di tipo nella maggior parte dei casi. Cambiamento breaking a livello di compilazione.

Se stavi verificando chiamate con argomenti che non corrispondono ai tipi di parametro effettivi della funzione, TypeScript potrebbe ora segnalare errori in quei test. Ad esempio, se una funzione è tipizzata per accettare un numero e hai scritto expect(fn).toHaveBeenCalledWith("string"), TypeScript 5 con i tipi di Jest 30 segnalerà questo problema. Il comportamento runtime del matcher rimane invariato.

Per risolvere i nuovi errori di TypeScript, assicurati che gli argomenti dei test corrispondano ai tipi attesi dalla funzione (oppure usa dei cast di tipo se chiami intenzionalmente con tipi diversi).

Questo cambiamento non ha impatto sul runtime, ma può far emergere nuovi errori di tipo nei tuoi test che prima passavano inosservati, rendendo i test più type-safe.

Aggiornamenti di configurazione​

Supporto per le estensioni .mts e .cts​

Jest 30 amplia il supporto per le estensioni dei moduli ESM e TypeScript:

  • Le moduleFileExtensions predefinite ora includono .mts e .cts (moduli TypeScript ESM e CommonJS) oltre alle estensioni abituali.

  • I pattern predefiniti di testMatch e testRegex sono stati aggiornati per riconoscere i file .mjs, .cjs, .mts e .cts come file di test.

info

Se il tuo progetto contiene file con queste estensioni che non sono destinati a essere trattati come moduli o test, potresti dover modificare la configurazione. Al contrario, se hai file di test con queste estensioni, Jest ora li rileverà automaticamente (potrai rimuovere eventuali configurazioni personalizzate precedentemente necessarie per includerli).

--testPathPattern è stato rinominato in --testPathPatterns​

Se filtri i test per percorso, nota che il flag CLI è cambiato: il flag --testPathPattern è ora --testPathPatterns. Puoi passare più pattern separandoli con spazi o ripetendo il flag. Ad esempio:

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

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

Internamente, Jest consolida questi pattern in un oggetto TestPathPatterns. Se chiamavi programmaticamente la modalità watch di Jest con un testPathPattern, ora devi invece costruire un'istanza di TestPathPatterns.

Rimozione del comando --init​

Il comando interattivo di inizializzazione configurazione jest --init è stato rimosso. Questo comando deprecato era usato per creare un file di configurazione Jest. Se devi creare una configurazione, puoi eseguire:

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

Altri cambiamenti CLI​

  • Jest ora convalida i flag CLI che richiedono argomenti per assicurarsi che venga fornito un valore. Ad esempio, se usi --maxWorkers o --selectProjects, devi includere un valore (es. --maxWorkers=50%). In precedenza, Jest poteva consentire certi flag senza valore (ricadendo sui default); ora genererà un errore se manca il valore. Assicurati che script o comandi npm che passano flag Jest includano gli argomenti necessari.

  • Se usi l'opzione --filter per filtrare i file di test (un caso d'uso avanzato in cui fornisci un percorso a un'implementazione di filtro), l'interfaccia attesa è cambiata. La funzione di filtro dovrebbe ora restituire un oggetto con la forma {filtered: Array<string>}, corrispondente al formato documentato. Nelle versioni precedenti, poteva essere accettato un formato di ritorno diverso (es. restituendo direttamente un array). Aggiorna eventuali funzioni di filtro test personalizzate per restituire un oggetto con proprietà filtered come documentato.

Cambiamenti nel comportamento del Test Runner​

Rejection di Promise non gestite nei test​

Jest include una correzione per gestire correttamente le promise che vengono rifiutate e successivamente catturate, evitando falsi fallimenti dei test. In Jest 29, un rejection di promise gestito in modo asincrono (dopo il tick del test) poteva comunque causare un fallimento erroneo del test. Jest 30 ora attende un ulteriore giro di event loop per confermare che un rejection di promise rimanga non gestito prima di far fallire un test.

info

Dovresti vedere meno falsi positivi per i rifiuti di promesse non gestiti. I test che prima fallivano a causa di rifiuti asincroni gestiti ora dovrebbero passare. Tuttavia, questa modifica può rallentare leggermente il completamento dei test, specialmente in quelli che rifiutano intenzionalmente le promesse. Per mitigare l'impatto sulle prestazioni, è stata introdotta una nuova flag di configurazione waitForUnhandledRejections. Questa flag, se disabilitata, può ripristinare il comportamento precedente (non attendere) se strettamente necessario. La maggior parte degli utenti non dovrebbe modificarla: l'impostazione predefinita ora privilegia la correttezza prevenendo falsi fallimenti.

Sequenziatori di Test Personalizzati​

Se utilizzi un sequenziatore di test personalizzato (una classe che eredita da TestSequencer di Jest), dovrai aggiornarlo per Jest 30. Jest ora passa contesto aggiuntivo al sequenziatore. Nello specifico, l'API TestSequencer è stata estesa per esporre globalConfig e contexts nel tuo sequenziatore.

globalConfig Obbligatoria nel Runtime​

Per chi utilizza le API programmatiche di Jest: costruire un Runtime ora richiede un parametro globalConfig. Se usi jest.runCLI o helper simili, assicurati di passare tutte le opzioni richieste secondo l'API aggiornata. (L'utilizzo tipico della CLI jest o di npm test non è influenzato da questa modifica.)

Snapshot e Modifiche all'Output​

L'URL goo.gl deprecato è stato rimosso dagli snapshot test. Questa modifica aggiorna gli snapshot esistenti sostituendo eventuali link goo.gl con URL completi non abbreviati.

Cause degli Errori negli Snapshot​

La serializzazione degli errori negli snapshot è cambiata. Il serializer degli snapshot di Jest 30 includerà ora la proprietà cause di un Error (se presente) durante la stampa degli errori.

Rendering Stringhe Vuote in React​

Il serializer specifico per React non renderizza più figli di stringhe vuote ("") nell'output. In Jest 29, un figlio stringa vuota in un elemento React poteva apparire come "" nell'output dello snapshot; in Jest 30 verrà omesso (considerato come nessun contenuto).

Migliorata la Stampa degli Oggetti in pretty-format​

ArrayBuffer e DataView sono ora stampati in modo leggibile anziché come oggetti con campi interni.

Modifiche all'API dei Mock di Jest​

jest.genMockFromModule Rimosso​

La funzione legacy jest.genMockFromModule(moduleName) è stata rimossa. Era stata deprecata in favore di jest.createMockFromModule(moduleName). Se usi ancora genMockFromModule, passa a createMockFromModule: il comportamento è identico. Esempio:

Codice vecchio (Jest 29):

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

Codice nuovo (Jest 30):

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

Tipi di Funzioni Mock Rimossi​

info

Le modifiche ai tipi si applicano solo se importi esplicitamente le API di Jest:

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

Alcuni tipi TypeScript relativi alle funzioni mock sono stati rimossi dall'API pubblica.

  • MockFunctionMetadata

  • MockFunctionMetadataType

  • SpyInstance

Se utilizzavi jest.SpyInstance (ad esempio per annotare il return di jest.spyOn), dovresti aggiornare a jest.Spied.

jest.mock funziona solo con percorsi di modulo case-sensitive​

Da ora in poi jest.mock() funzionerà esclusivamente con percorsi di modulo rispettando la distinzione tra maiuscole/minuscole. Si tratta comunque di un caso limite poiché la maggior parte degli utenti segue già le convenzioni dei nomi file del sistema operativo. Consigliamo di utilizzare percorsi di modulo correttamente denominati per evitare problemi simili in futuro.

Codice vecchio (Jest 29):

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

Codice nuovo (Jest 30):

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

Modifiche ai Moduli e al Runtime​

Supporto Moduli ESM e Ristrutturazione Interna​

Jest ha introdotto importanti modifiche interne su come i suoi pacchetti sono raggruppati ed esportati:

  • Tutti i moduli interni di Jest sono ora raggruppati in singoli file per un avvio più veloce. Ciò significa che quando installi Jest, il numero di file caricati è notevolmente ridotto (migliorando le prestazioni). Tuttavia, un effetto collaterale è che qualsiasi importazione non ufficiale in profondità nei pacchetti di Jest probabilmente si interromperà. Ad esempio, se in precedenza hai fatto qualcosa come require('jest-runner/build/testWorker') (che non è un'API pubblica), questo percorso non esisterà più. Soluzione: Utilizza solo le API pubbliche di Jest o le interfacce documentate. Se dipendi da un modulo interno che ritieni dovrebbe far parte dell'API pubblica, apri una Pull Request per esporlo.

  • I pacchetti di Jest ora forniscono wrapper ESM. Questo fa parte del lavoro in corso per consentire l'esecuzione di Jest in un contesto ESM. Tutti i pacchetti ufficiali di Jest esportano se stessi correttamente tramite il campo "exports" nel package.json. Per la maggior parte degli utenti, questo non ha un impatto diretto – continui a usare Jest nello stesso modo. Ma se mantieni uno strumento o un plugin che importa i moduli di Jest, assicurati di utilizzare i nomi dei pacchetti come importazioni (che verranno risolte tramite la risoluzione dei moduli di Node).

Questi cambiamenti sono considerati di breaking per chi si addentra negli interni di Jest, ma non per l'uso tipico della CLI e della configurazione di Jest. Dopo l'aggiornamento, esegui i tuoi test normalmente – se ottieni errori di risoluzione dei moduli relativi ai moduli di Jest stesso, è probabile che siano dovuti a un'importazione non supportata che deve essere rimossa o aggiornata.

Modifiche alla Corrispondenza dei Pattern Glob​

La dipendenza di Jest per la corrispondenza dei pattern di file (glob) è stata aggiornata alla v10. Glob v10 potrebbe avere lievi differenze nella sintassi e nel comportamento dei pattern.

Un cambiamento degno di nota è che glob@10 tratta le espansioni di parentesi e gli extglob in modo leggermente diverso ed è più rigoroso riguardo ad alcuni pattern. Se hai pattern testMatch personalizzati, pattern moduleNameMapper o altre configurazioni basate su glob, nella maggior parte dei casi dovrebbero continuare a funzionare. Tieniti solo presente che se un pattern non corrisponde ai file come faceva in precedenza, potresti doverlo adattare per il nuovo motore glob.

Conclusione​

Aggiorna a Jest 30 assicurandoti prima che il tuo ambiente soddisfi i nuovi requisiti di Node.js e TypeScript. Aggiorna il tuo file di configurazione di Jest e l'utilizzo della CLI per le opzioni rinominate e rimosse (in particolare testPathPatterns e la rimozione di --init). Esegui la tua suite di test e risolvi eventuali errori:

  • Correggi i test che utilizzano alias di matcher rimossi sostituendoli con i nomi ufficiali dei matcher

  • Aggiorna gli snapshot che falliscono a causa delle modifiche di formattazione (cause di errore, stringhe vuote, ecc.)

  • Presta attenzione agli errori del compilatore TypeScript – ti guideranno nell'aggiornare l'utilizzo di API deprecate (come genMockFromModule o tipi rimossi) e ad adattare i test in cui i tipi sono ora più rigorosi

Buon testing!