Watch-Plugins

Inoffizielle Beta-Übersetzung

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

Das Watch-Plugin-System von Jest ermöglicht es, in bestimmte Teile von Jest einzuhaken und Menüoptionen für den Watch-Modus zu definieren, die bei Tastendruck Code ausführen. Diese Funktionen kombiniert ermöglichen es dir, interaktive Erfahrungen speziell für deinen Workflow zu entwickeln.

Watch-Plugin-Schnittstelle

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

Einbinden in Jest

Um dein Watch-Plugin mit Jest zu verbinden, füge seinen Pfad unter watchPlugins in deiner Jest-Konfiguration hinzu:

jest.config.js

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

Benutzerdefinierte Watch-Plugins können Hooks für Jest-Ereignisse hinzufügen. Diese Hooks können mit oder ohne interaktiver Taste im Watch-Modus-Menü hinzugefügt werden.

apply(jestHooks)

Jest-Hooks können durch Implementierung der apply-Methode angehängt werden. Diese Methode erhält ein jestHooks-Argument, das es dem Plugin ermöglicht, in bestimmte Teile des Lebenszyklus eines Testlaufs einzuhaken.

class MyWatchPlugin {
  apply(jestHooks) {}
}

Im Folgenden sind die in Jest verfügbaren Hooks aufgeführt.

jestHooks.shouldRunTestSuite(testSuiteInfo)

Gibt einen Boolean-Wert zurück (oder Promise<boolean> für asynchrone Operationen), um festzulegen, ob ein Test ausgeführt werden soll oder nicht.

Beispiel:

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)

Wird am Ende jedes Testlaufs aufgerufen. Erhält die Testergebnisse als Argument.

Beispiel:

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

jestHooks.onFileChange({projects})

Wird bei jeder Änderung im Dateisystem aufgerufen

• projects: Array<config: ProjectConfig, testPaths: Array<string>: Enthält alle Testpfade, die Jest überwacht.

Beispiel:

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

Watch-Menü-Integration

Benutzerdefinierte Watch-Plugins können auch Funktionen zum Watch-Menü hinzufügen oder überschreiben, indem sie ein Tasten-/Aufforderungspaar in der getUsageInfo-Methode und eine run-Methode für die Ausführung der Taste angeben.

getUsageInfo(globalConfig)

Um eine Taste zum Watch-Menü hinzuzufügen, implementiere die getUsageInfo-Methode und gib eine Taste sowie die Aufforderung zurück:

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

Dadurch wird eine Zeile im Watch-Modus-Menü hinzugefügt (› 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.

Hinweis

Wenn die Taste für dein Plugin bereits als Standardtaste existiert, überschreibt dein Plugin diese Taste.

run(globalConfig, updateConfigAndRun)

Um Tastendruckereignisse von der durch getUsageInfo zurückgegebenen Taste zu verarbeiten, kannst du die run-Methode implementieren. Diese Methode gibt ein Promise<boolean> zurück, das aufgelöst wird, wenn das Plugin die Kontrolle an Jest zurückgeben möchte. Der boolean-Wert gibt an, ob Jest die Tests erneut ausführen soll, nachdem es die Kontrolle zurückerhält.

• globalConfig: Repräsentiert die aktuelle globale Konfiguration von Jest

• updateConfigAndRun: Ermöglicht das Auslösen eines Testlaufs während das interaktive Plugin läuft.

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

Hinweis

Wenn du updateConfigAndRun aufrufst, sollte deine run-Methode keinen truthy-Wert zurückgeben, da dies einen Doppellauf auslösen würde.

Autorisierte Konfigurationsschlüssel

Aus Stabilitäts- und Sicherheitsgründen können mit updateConfigAndRun nur bestimmte globale Konfigurationsschlüssel aktualisiert werden. Die aktuelle Whitelist umfasst:

• bail

• changedSince

• collectCoverage

• collectCoverageFrom

• coverageDirectory

• coverageReporters

• notify

• notifyMode

• onlyFailures

• reporters

• testNamePattern

• testPathPatterns

• updateSnapshot

• verbose

Anpassung

Plugins können über deine Jest-Konfiguration angepasst werden.

jest.config.js

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

Empfohlene Konfigurationsnamen:

• key: Ändert die Plugin-Taste.

• prompt: Ermöglicht die Anpassung des Textes im Plugin-Prompt.

Falls der Benutzer eine benutzerdefinierte Konfiguration bereitstellt, wird diese als Argument an den Plugin-Konstruktor übergeben.

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

Wahl einer geeigneten Taste

Jest erlaubt Drittanbieter-Plugins, einige integrierte Funktionstasten zu überschreiben, aber nicht alle. Insbesondere folgende Tasten sind nicht überschreibbar:

• c (löscht Filterpatterns)

• i (aktualisiert nicht übereinstimmende Snapshots interaktiv)

• q (beendet)

• u (aktualisiert alle nicht übereinstimmenden Snapshots)

• w (zeigt Watch-Mode-Nutzung/verfügbare Aktionen)

Folgende Tasten für integrierte Funktionen können überschrieben werden:

• p (Test-Dateinamen-Pattern)

• t (Testnamen-Pattern)

Nicht verwendete Tasten können wie erwartet belegt werden. Vermeide Tasten, die schwer zu erreichen sind (z.B. é, €) oder nicht standardmäßig sichtbar sind (z.B. fehlen auf vielen Mac-Tastaturen visuelle Hinweise für |, \, [ etc.).

Bei Konflikten

Falls dein Plugin versucht, eine reservierte Taste zu überschreiben, wird Jest mit einer beschreibenden Fehlermeldung abbrechen:

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

Drittanbieter-Plugins dürfen auch keine Tasten überschreiben, die bereits von einem früher in der Plugin-Liste (watchPlugins-Array) konfigurierten Plugin reserviert wurden. In diesem Fall erhältst du ebenfalls eine Fehlermeldung, die dir bei der Lösung hilft:

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.