Plugin per la Modalità Watch

Traduzione Beta Non Ufficiale

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

Il sistema di plugin watch di Jest permette di collegarsi a parti specifiche del framework e di definire prompt nel menu della modalità watch che eseguono codice alla pressione di un tasto. Combinati, questi strumenti consentono di creare esperienze interattive personalizzate per il tuo flusso di lavoro.

Interfaccia dei Plugin Watch

class MyWatchPlugin {
  // Add hooks to Jest lifecycle events
  apply(jestHooks) {}

  // Get the prompt information for interactive plugins
  getUsageInfo(globalConfig) {}

  // Executed when the key from `getUsageInfo` is input
  run(globalConfig, updateConfigAndRun) {}
}

Collegamento a Jest

Per integrare il tuo plugin watch in Jest, aggiungi il suo percorso sotto watchPlugins nella configurazione di Jest:

jest.config.js

module.exports = {
  // ...
  watchPlugins: ['path/to/yourWatchPlugin'],
};

I plugin watch personalizzati possono aggiungere hook agli eventi di Jest. Questi hook possono essere implementati con o senza un tasto interattivo nel menu della modalità watch.

apply(jestHooks)

Gli hook di Jest si collegano implementando il metodo apply. Questo metodo riceve un argomento jestHooks che permette al plugin di agganciarsi a fasi specifiche del ciclo di vita di un'esecuzione di test.

class MyWatchPlugin {
  apply(jestHooks) {}
}

Di seguito gli hook disponibili in Jest.

jestHooks.shouldRunTestSuite(testSuiteInfo)

Restituisce un booleano (o Promise<boolean> per operazioni asincrone) per indicare se un test debba essere eseguito o meno.

Per esempio:

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return testSuiteInfo.testPath.includes('my-keyword');
    });

    // or a promise
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return Promise.resolve(testSuiteInfo.testPath.includes('my-keyword'));
    });
  }
}

jestHooks.onTestRunComplete(results)

Viene chiamato alla fine di ogni esecuzione di test. Riceve i risultati dei test come argomento.

Per esempio:

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.onTestRunComplete(results => {
      this._hasSnapshotFailure = results.snapshot.failure;
    });
  }
}

jestHooks.onFileChange({projects})

Viene chiamato quando c'è una modifica nel file system

• projects: Array<config: ProjectConfig, testPaths: Array<string>: Include tutti i percorsi dei test monitorati da Jest.

Per esempio:

class MyWatchPlugin {
  apply(jestHooks) {
    jestHooks.onFileChange(({projects}) => {
      this._projects = projects;
    });
  }
}

Integrazione con il Menu Watch

I plugin watch personalizzati possono aggiungere o sovrascrivere funzionalità nel menu tramite una coppia chiave/prompt nel metodo getUsageInfo e un metodo run per l'esecuzione del tasto.

getUsageInfo(globalConfig)

Per aggiungere un tasto al menu watch, implementa il metodo getUsageInfo restituendo una chiave e il prompt:

class MyWatchPlugin {
  getUsageInfo(globalConfig) {
    return {
      key: 's',
      prompt: 'do something',
    };
  }
}

Questo aggiungerà una riga nel menu della modalità watch (› Press s to do something.)

Watch Usage
 › Press p to filter by a filename regex pattern.
 › Press t to filter by a test name regex pattern.
 › Press q to quit watch mode.
 › Press s to do something. // <-- This is our plugin
 › Press Enter to trigger a test run.

nota

Se la chiave del tuo plugin esiste già come tasto predefinito, il tuo plugin la sovrascriverà.

run(globalConfig, updateConfigAndRun)

Per gestire gli eventi di pressione tasto dalla chiave restituita da getUsageInfo, implementa il metodo run. Questo metodo restituisce una Promise<boolean> risolta quando il plugin vuole restituire il controllo a Jest. Il boolean indica se Jest deve rieseguire i test dopo aver riottenuto il controllo.

• globalConfig: Rappresentazione della configurazione globale corrente di Jest

• updateConfigAndRun: Permette di attivare un'esecuzione di test durante l'attività del plugin interattivo.

class MyWatchPlugin {
  run(globalConfig, updateConfigAndRun) {
    // do something.
  }
}

nota

Se chiami updateConfigAndRun, il tuo metodo run non deve restituire un valore truthy per evitare una doppia esecuzione.

Chiavi di configurazione autorizzate

Per stabilità e sicurezza, solo alcune chiavi di configurazione globale possono essere aggiornate con updateConfigAndRun. La whitelist corrente include:

• bail

• changedSince

• collectCoverage

• collectCoverageFrom

• coverageDirectory

• coverageReporters

• notify

• notifyMode

• onlyFailures

• reporters

• testNamePattern

• testPathPatterns

• updateSnapshot

• verbose

Personalizzazione

I plugin possono essere personalizzati tramite la configurazione di Jest.

jest.config.js

module.exports = {
  // ...
  watchPlugins: [
    [
      'path/to/yourWatchPlugin',
      {
        key: 'k', // <- your custom key
        prompt: 'show a custom prompt',
      },
    ],
  ],
};

Nomi di configurazione consigliati:

• key: Modifica la chiave del plugin.

• prompt: Consente di personalizzare il testo nel prompt del plugin.

Se l'utente fornisce una configurazione personalizzata, questa verrà passata come argomento al costruttore del plugin.

class MyWatchPlugin {
  constructor({config}) {}
}

Scegliere una chiave appropriata

Jest consente ai plugin di terze parti di sovrascrivere alcune chiavi integrate, ma non tutte. Nello specifico, queste chiavi non sono sovrascrivibili:

• c (cancella i pattern di filtro)

• i (aggiorna gli snapshot non corrispondenti in modo interattivo)

• q (esce)

• u (aggiorna tutti gli snapshot non corrispondenti)

• w (mostra l'utilizzo della modalità watch / azioni disponibili)

Le seguenti chiavi per funzionalità integrate possono essere sovrascritte:

• p (pattern del nome del file di test)

• t (pattern del nome del test)

Qualsiasi chiave non utilizzata dalle funzionalità integrate può essere utilizzata. Si consiglia di evitare chiavi difficili da digitare su diverse tastiere (es. é, €) o non visibili per impostazione predefinita (es. molte tastiere Mac non mostrano caratteri come |, \, [).

Gestione dei conflitti

Se il tuo plugin tenta di sovrascrivere una chiave riservata, Jest genererà un errore con un messaggio descrittivo simile a:

Watch plugin YourFaultyPlugin attempted to register key `q`, that is reserved internally for quitting watch mode. Please change the configuration key for this plugin.

Ai plugin di terze parti è inoltre vietato sovrascrivere chiavi già riservate da altri plugin presenti prima nella lista di configurazione (array watchPlugins). In questo caso, riceverai un messaggio d'errore che ti aiuterà a risolvere il problema:

Watch plugins YourFaultyPlugin and TheirFaultyPlugin both attempted to register key `x`. Please change the key configuration for one of the conflicting plugins to avoid overlap.