Plugins de surveillance

Le système de plugins de surveillance (NdT watch) de Jest permet d'accéder à des parties spécifiques de Jest et de définir des invites de menu en mode de surveillance qui exécutent du code en appuyant sur une touche. Combinées, ces fonctionnalités vous permettent de développer des expériences interactives personnalisées pour votre flux de travail.

Interface du plugin de surveillance

class MyWatchPlugin {
  // Ajoute des hooks aux événements du cycle de vie de Jest
  apply(jestHooks) {}

  // Récupère les informations de l'invite pour les plugins interactifs
  getUsageInfo(globalConfig) {}

  // Exécuté lorsque la clé de `getUsageInfo` est entrée
  run(globalConfig, updateConfigAndRun) {}
}

Faire des hooks dans Jest

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

jest.config.js

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

Les plugins de surveillance 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 surveillance.

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 de se raccrocher à des parties spécifiques du cycle de vie d'un test.

class MyWatchPlugin {
  apply(jestHooks) {}
}

Ci-dessous se trouvent les hooks disponibles en Jest.

jestHooks.shouldRunTestSuite(testSuiteInfo)

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

Par exemple :

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

    // ou une promesse
    jestHooks.shouldRunTestSuite(testSuiteInfo => {
      return Promise.resolve(testSuiteInfo.testPath.includes('my-keyword'));
    });
  }
}

jestHooks.onTestRunComplete(results)

Est appelé à la fin de chaque test. Il a les résultats du test comme argument.

Par exemple :

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

jestHooks.onFileChange({projects})

Est appelé à chaque fois qu'il y a un changement dans le système de fichiers

• projects: Array<config: ProjectConfig, testPaths: Array<string> : inclut tous les chemins de test que Jest surveille.

Par exemple :

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

Intégration du menu de surveillance

Les plugins de surveillance personnalisés peuvent également ajouter ou remplacer la fonctionnalité du menu de surveillance en spécifiant une paire key/prompt dans la méthode getUsageInfo et une méthode run pour l'exécution de key.

getUsageInfo(globalConfig)

Pour ajouter une touche au menu de surveillance, implémentez la méthode getUsageInfo, renvoyant une touche (key) et l'invite (prompt) :

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

Ceci ajoutera une ligne dans le menu du mode surveillance (› 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. // <-- C'est notre plugin
 › Press Enter to trigger a test run.

remarque

If the key for your plugin already exists as a default key, your plugin will override that key.

run(globalConfig, updateConfigAndRun)

Pour gérer les événements de pression de touche à partir de la touche retournée par getUsageInfo, vous pouvez implémenter la méthode run. Cette méthode renvoie une Promise<boolean> qui peut être résolue lorsque le plugin veut rendre le contrôle à Jest. Le boolean précise si Jest doit réexécuter les tests après avoir récupéré le contrôle.

• globalConfig: A representation of Jest's current global configuration
• updateConfigAndRun : Vous permet de lancer un test pendant que le plugin interactif est en cours d'exécution.

class MyWatchPlugin {
  run(globalConfig, updateConfigAndRun) {
    // fait quelque chose.
  }
}

remarque

If you do call updateConfigAndRun, your run method should not resolve to a truthy value, as that would trigger a double-run.

Touches de configuration autorisées

Pour des raisons de stabilité et de sécurité, seule une partie des touches de configuration globale peuvent être mises à jour avec updateConfigAndRun. La liste blanche actuelle est la suivante :

• bail
• changedSince
• collectCoverage
• collectCoverageFrom
• coverageDirectory
• coverageReporters
• notify
• notifyMode
• onlyFailures
• reporters
• testNamePattern
• testPathPattern
• updateSnapshot
• verbose

Personnalisation

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

jest.config.js

module.exports = {
  // ...
  watchPlugins: [
    [
      'path/to/yourWatchPlugin',
      {
        key: 'k', // <- votre touche personnalisée
        prompt: 'affiche une invite personnalisée',
      },
    ],
  ],
};

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 a fourni une configuration personnalisée, elle sera passée comme argument au constructeur du plugin.

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

Choix d'une bonne touche

Jest permet aux plugins tiers de surcharger certaines de ses touches de fonctionnalités intégrées, mais pas toutes. Plus précisément, les touches suivantes ne sont pas écrasables :

• c (efface les patterns de filtre)
• i (met à jour de façon interactive les snapshots non concordants)
• q (quitter)
• u (met à jour les snapshots non concordants)
• w (affiche l'utilisation du mode surveillance / les actions disponibles)

Les touches suivantes pour la fonctionnalité intégrée peuvent être écrasées :

• p (tester le pattern de nom de fichier)
• t (tester le pattern de nom)

Toute touche non utilisée par la fonctionnalité intégrée peut être invoquée, comme on peut s'y attendre. Essayez d'éviter d'utiliser des touches difficiles à obtenir sur divers claviers (par exemple é, €), ou non visibles par défaut (par exemple, de nombreux claviers Mac ne disposent pas d'indications visuelles pour des caractères tels que |, \, [, etc.)

Quand un conflit se produit

Si votre plugin tente d'écraser une touche réservée, Jest émettra une erreur avec un message descriptif, quelque chose du genre :

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 d'écraser une touche déjà réservée par un autre plugin tiers présent plus tôt dans la liste des plugins configurés (paramètre du tableau watchPlugins). Lorsque cela se produit, vous recevrez également un message d’erreur qui tente de vous aider à corriger ceci :

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.