Plugins Watch

Traduction Bêta Non Officielle

Cette page a été traduite par PageTurner AI (bêta). Non approuvée officiellement par le projet. Vous avez trouvé une erreur ? Signaler un problème →

Le système de plugins watch de Jest permet d'interagir avec des parties spécifiques du framework et de définir des actions dans le menu du mode watch qui s'exécutent par pression de touches. Combinées, ces fonctionnalités vous permettent de créer des expériences interactives adaptées à votre flux de travail.

Interface de 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) {}
}

Intégration avec Jest

Pour connecter votre plugin watch à Jest, ajoutez son chemin sous watchPlugins dans votre configuration Jest :

jest.config.js

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

Les plugins watch personnalisés peuvent ajouter des hooks aux événements Jest. Ces hooks peuvent être ajoutés avec ou sans touche interactive dans le menu du mode watch.

apply(jestHooks)

Les hooks Jest peuvent être attachés en implémentant la méthode apply. Cette méthode reçoit un argument jestHooks qui permet au plugin d'interagir avec des parties spécifiques du cycle d'exécution des tests.

class MyWatchPlugin {
  apply(jestHooks) {}
}

Voici les hooks disponibles dans Jest :

jestHooks.shouldRunTestSuite(testSuiteInfo)

Retourne un booléen (ou Promise<boolean> pour les opérations asynchrones) indiquant si un test doit être exécuté.

Par exemple :

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)

Appelé à la fin de chaque exécution de tests. Reçoit les résultats des tests en argument.

Par exemple :

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

jestHooks.onFileChange({projects})

Appelé dès qu'un changement survient dans le système de fichiers

• projects: Array<config: ProjectConfig, testPaths: Array<string> : Inclut tous les chemins de tests surveillés par Jest.

Par exemple :

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

Intégration au menu Watch

Les plugins watch personnalisés peuvent aussi ajouter ou remplacer des fonctionnalités dans le menu watch en spécifiant une paire touche/invite dans la méthode getUsageInfo et une méthode run pour exécuter l'action.

getUsageInfo(globalConfig)

Pour ajouter une touche au menu watch, implémentez la méthode getUsageInfo en retournant une touche et l'invite correspondante :

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

Cela ajoutera une ligne dans le menu du mode 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.

note

Si la touche de votre plugin existe déjà comme touche par défaut, votre plugin écrasera cette fonctionnalité.

run(globalConfig, updateConfigAndRun)

Pour gérer les événements de pression de touche à partir de la touche renvoyée par getUsageInfo, implémentez la méthode run. Elle retourne une Promise<boolean> qui peut être résolue lorsque le plugin veut rendre le contrôle à Jest. Le boolean spécifie si Jest doit relancer les tests après avoir récupéré le contrôle.

• globalConfig : Représentation de la configuration globale actuelle de Jest

• updateConfigAndRun : Permet de déclencher une exécution de tests pendant l'exécution du plugin interactif.

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

note

Si vous appelez updateConfigAndRun, votre méthode run ne doit pas résoudre une valeur truthy, car cela déclencherait une double exécution.

Clés de configuration autorisées

Pour des raisons de stabilité et sécurité, seule une partie des clés de configuration globale peut être mise à jour avec updateConfigAndRun. La liste blanche actuelle est :

• bail

• changedSince

• collectCoverage

• collectCoverageFrom

• coverageDirectory

• coverageReporters

• notify

• notifyMode

• onlyFailures

• reporters

• testNamePattern

• testPathPatterns

• updateSnapshot

• verbose

Personnalisation

Les plugins peuvent être personnalisés via votre configuration Jest.

jest.config.js

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

Noms de configuration recommandés :

• key : Modifie la touche du plugin.

• prompt : Permet à l'utilisateur de personnaliser le texte dans l'invite du plugin.

Si l'utilisateur fournit une configuration personnalisée, celle-ci sera passée en argument au constructeur du plugin.

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

Choisir une bonne touche

Jest permet aux plugins tiers de remplacer certaines touches intégrées, mais pas toutes. Plus précisément, les touches suivantes ne peuvent pas être remplacées :

• c (efface les modèles de filtre)

• i (met à jour les instantanés non concordants de manière interactive)

• q (quitte)

• u (met à jour tous les instantanés non concordants)

• w (affiche l'utilisation du mode watch / les actions disponibles)

Les touches suivantes des fonctionnalités intégrées peuvent être remplacées :

• p (modèle de nom de fichier de test)

• t (modèle de nom de test)

Toute touche non utilisée par les fonctionnalités intégrées peut être revendiquée. Évitez les touches difficiles à saisir sur certains claviers (ex. é, €) ou peu visibles (ex. |, \, [ sur de nombreux claviers Mac).

En cas de conflit

Si votre plugin tente de remplacer une touche réservée, Jest affichera un message d'erreur descriptif, par exemple :

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

Il est également interdit aux plugins tiers de remplacer une touche déjà réservée par un autre plugin tiers antérieur dans la liste (watchPlugins). Dans ce cas, un message d'erreur explicatif vous aidera à résoudre le problème :

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.