From c483350861a599629e92a056db3510ab2f0da3b5 Mon Sep 17 00:00:00 2001 From: Rogelio Guzman Date: Tue, 27 Mar 2018 10:14:37 -0700 Subject: [PATCH 1/5] Add skeleton --- .../version-22.4/WatchPlugins.md | 125 ++++++++++++++++++ .../version-22.4-sidebars.json | 1 + 2 files changed, 126 insertions(+) create mode 100644 website/versioned_docs/version-22.4/WatchPlugins.md diff --git a/website/versioned_docs/version-22.4/WatchPlugins.md b/website/versioned_docs/version-22.4/WatchPlugins.md new file mode 100644 index 000000000000..9f0c7462a585 --- /dev/null +++ b/website/versioned_docs/version-22.4/WatchPlugins.md @@ -0,0 +1,125 @@ +--- +id: version-22.4-watch-plugins +title: Watch Plugins +original_id: watch-plugins +--- + +A watch plugin allows you to enhance Jest in a couple of ways. It provides you with ways of hooking into specific parts of Jest. It allows you to handle user input and provide an interactive experience + +## JestHooks + +Jest hooks can be accessed by implementing the `apply` method in a plugin +class. This receives a `jestHooks` argument that allows the plugin to hook into +specific parts of the lifecycle of a test run. + +```javascript +class MyPlugin { + apply(jestHooks) {} +} +``` + +### `jestHooks.shouldRunTestSuite(testPath)` + +It returns a boolean to specify if a test should be run or not. It can return a +`Promise` for handling asynchronous operations. + +For example: + +```javascript +class MyPlugin { + apply(jestHooks) { + jestHooks.shouldRunTestSuite(testPath => { + return testPath.includes('my-keyword'); + }); + + // or a promise + + jestHooks.shouldRunTestSuite(testPath => { + return Promise.resolve(testPath.includes('my-keyword')); + }); + } +} +``` + +### `jestHooks.testRunComplete(results)` + +Gets called at the end of every test run. It has the test results as an +argument. + +For example: + +```javascript +class MyPlugin { + apply(jestHooks) { + jestHooks.testRunComplete(results => { + this._hasSnapshotFailure = results.snapshot.failure; + }); + } +} +``` + +### `jestHooks.fsChange({ projects })` + +Gets called whenever there is a change in the file system. testPaths: + +* `projects: Array`: Includes + all the test paths that Jest is watching. + +For example: + +```javascript +class MyPlugin { + apply(jestHooks) { + jestHooks.fsChange(({projects}) => { + this._projects = projects; + }); + } +} +``` + +## Interactive Plugins + +### Showing the plugin on the watch usage menu. + +Interactive plugins allow you to add functionality to the watch usage menu. + +```javascript +class MyPlugin { + getUsageInfo(globalConfig) { + return { + key: 's'.codePointAt(0), + prompt: 'do something', + }; + } +} +``` + +Adding `getUsageInfo` to a plugin adds a line in the watch mode menu +_(`› Press s to do something.`)_ + +```text +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. +``` + +### Running the plugin when the user interacts with it. + +Given the example above, the plugin will run when the user presses `'s'`. For +that we can add a `run` method. + +`run(globalConfig, updateConfigAndRun)`: + - Returns a `Promise` that can be resolved when the plugin wants to return control to Jest. The `boolean` specifies if Jest should rerun the tests after it gets the control back. + - `globalConfig`: A representation of Jest's current global configuration + - `updateConfigAndRun`: Allows you to trigger a test run while the interactive plugin is running. + +```javascript +class MyPlugin { + run(globalConfig, updateConfigAndRun) { + // do something. + } +} +``` diff --git a/website/versioned_sidebars/version-22.4-sidebars.json b/website/versioned_sidebars/version-22.4-sidebars.json index 0fb00ab55d8a..64fadfa31dde 100644 --- a/website/versioned_sidebars/version-22.4-sidebars.json +++ b/website/versioned_sidebars/version-22.4-sidebars.json @@ -18,6 +18,7 @@ "version-22.4-es6-class-mocks", "version-22.4-webpack", "version-22.4-puppeteer", + "version-22.4-watch-plugins", "version-22.4-mongodb", "version-22.4-migration-guide", "version-22.4-troubleshooting" From a247c97075dd420bad53f7da02485aaa32b5b01d Mon Sep 17 00:00:00 2001 From: rickhanlonii Date: Thu, 24 May 2018 15:28:04 +0100 Subject: [PATCH 2/5] Update based on feedback --- docs/WatchPlugins.md | 137 ++++++++++++++++++ website/i18n/en.json | 1 + .../version-22.4/WatchPlugins.md | 125 ---------------- .../version-22.4-sidebars.json | 1 - 4 files changed, 138 insertions(+), 126 deletions(-) create mode 100644 docs/WatchPlugins.md delete mode 100644 website/versioned_docs/version-22.4/WatchPlugins.md diff --git a/docs/WatchPlugins.md b/docs/WatchPlugins.md new file mode 100644 index 000000000000..37a91023efc0 --- /dev/null +++ b/docs/WatchPlugins.md @@ -0,0 +1,137 @@ +--- +id: watch-plugins +title: Watch Plugins +original_id: watch-plugins +--- + +The Jest watch plugin system provides a way to hook into specific parts of Jest and to define watch mode menu prompts that execute code on key press. Combined, these features allow you to develop interactive experiences custom for your workflow. + +## Watch Plugin Interface +```javascript +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) {} +} +``` +## Hooking into Jest +Custom watch plugins can add hooks to Jest events. These hooks can be added either with or without having an interactive key in the watch mode menu. + +### `apply(jestHooks)` +Jest hooks can be attached by implementing the `apply` method. This method receives a `jestHooks` argument that allows the plugin to hook into +specific parts of the lifecycle of a test run. + +```javascript +class MyWatchPlugin { + apply(jestHooks) {} +} +``` + +Below are the hooks available in Jest. +#### `jestHooks.shouldRunTestSuite(testPath)` + +Returns a boolean to specify if a test should be run or not. It can return a +`Promise` for handling asynchronous operations. + +For example: + +```javascript +class MyWatchPlugin { + apply(jestHooks) { + jestHooks.shouldRunTestSuite(testPath => { + return testPath.includes('my-keyword'); + }); + + // or a promise + jestHooks.shouldRunTestSuite(testPath => { + return Promise.resolve(testPath.includes('my-keyword')); + }); + } +} +``` + +#### `jestHooks.testRunComplete(results)` + +Gets called at the end of every test run. It has the test results as an +argument. + +For example: + +```javascript +class MyWatchPlugin { + apply(jestHooks) { + jestHooks.testRunComplete(results => { + this._hasSnapshotFailure = results.snapshot.failure; + }); + } +} +``` + +#### `jestHooks.fsChange({ projects })` + +Gets called whenever there is a change in the file system + +* `projects: Array`: Includes + all the test paths that Jest is watching. + +For example: + +```javascript +class MyWatchPlugin { + apply(jestHooks) { + jestHooks.fsChange(({projects}) => { + this._projects = projects; + }); + } +} +``` + +## Watch Menu Integration + +Custom watch plugins can also add or override functionality to the watch menu by specifying a key/prompt pair in `getUsageInfo` method and a `run` method for the execution of the key. + +### `getUsageInfo(globalConfig)` +To add a key to the watch menu, implement the `getUsageInfo` method, returning a key and the prompt: + +```javascript +class MyWatchPlugin { + getUsageInfo(globalConfig) { + return { + key: 's'.codePointAt(0), + prompt: 'do something', + }; + } +} +``` + +This will add a line in the watch mode menu +_(`› Press s to do something.`)_ + +```text +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**: If the key for your plugin already exists as a default key, your plugin will override that key. + +### `run(globalConfig, updateConfigAndRun)` + +To handle key press events from the key returned by `getUsageInfo`, you can implement the `run` method. This method returns a `Promise` that can be resolved when the plugin wants to return control to Jest. The `boolean` specifies if Jest should rerun the tests after it gets the control back. + - `globalConfig`: A representation of Jest's current global configuration + - `updateConfigAndRun`: Allows you to trigger a test run while the interactive plugin is running. + +```javascript +class MyWatchPlugin { + run(globalConfig, updateConfigAndRun) { + // do something. + } +} +``` diff --git a/website/i18n/en.json b/website/i18n/en.json index ab79fd12f251..bb16921e985d 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -31,6 +31,7 @@ "tutorial-react": "Testing React Apps", "tutorial-react-native": "Testing React Native Apps", "using-matchers": "Using Matchers", + "watch-plugins": "Watch Plugins", "webpack": "Using with webpack", "Docs": "Docs", "API": "API", diff --git a/website/versioned_docs/version-22.4/WatchPlugins.md b/website/versioned_docs/version-22.4/WatchPlugins.md deleted file mode 100644 index 9f0c7462a585..000000000000 --- a/website/versioned_docs/version-22.4/WatchPlugins.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: version-22.4-watch-plugins -title: Watch Plugins -original_id: watch-plugins ---- - -A watch plugin allows you to enhance Jest in a couple of ways. It provides you with ways of hooking into specific parts of Jest. It allows you to handle user input and provide an interactive experience - -## JestHooks - -Jest hooks can be accessed by implementing the `apply` method in a plugin -class. This receives a `jestHooks` argument that allows the plugin to hook into -specific parts of the lifecycle of a test run. - -```javascript -class MyPlugin { - apply(jestHooks) {} -} -``` - -### `jestHooks.shouldRunTestSuite(testPath)` - -It returns a boolean to specify if a test should be run or not. It can return a -`Promise` for handling asynchronous operations. - -For example: - -```javascript -class MyPlugin { - apply(jestHooks) { - jestHooks.shouldRunTestSuite(testPath => { - return testPath.includes('my-keyword'); - }); - - // or a promise - - jestHooks.shouldRunTestSuite(testPath => { - return Promise.resolve(testPath.includes('my-keyword')); - }); - } -} -``` - -### `jestHooks.testRunComplete(results)` - -Gets called at the end of every test run. It has the test results as an -argument. - -For example: - -```javascript -class MyPlugin { - apply(jestHooks) { - jestHooks.testRunComplete(results => { - this._hasSnapshotFailure = results.snapshot.failure; - }); - } -} -``` - -### `jestHooks.fsChange({ projects })` - -Gets called whenever there is a change in the file system. testPaths: - -* `projects: Array`: Includes - all the test paths that Jest is watching. - -For example: - -```javascript -class MyPlugin { - apply(jestHooks) { - jestHooks.fsChange(({projects}) => { - this._projects = projects; - }); - } -} -``` - -## Interactive Plugins - -### Showing the plugin on the watch usage menu. - -Interactive plugins allow you to add functionality to the watch usage menu. - -```javascript -class MyPlugin { - getUsageInfo(globalConfig) { - return { - key: 's'.codePointAt(0), - prompt: 'do something', - }; - } -} -``` - -Adding `getUsageInfo` to a plugin adds a line in the watch mode menu -_(`› Press s to do something.`)_ - -```text -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. -``` - -### Running the plugin when the user interacts with it. - -Given the example above, the plugin will run when the user presses `'s'`. For -that we can add a `run` method. - -`run(globalConfig, updateConfigAndRun)`: - - Returns a `Promise` that can be resolved when the plugin wants to return control to Jest. The `boolean` specifies if Jest should rerun the tests after it gets the control back. - - `globalConfig`: A representation of Jest's current global configuration - - `updateConfigAndRun`: Allows you to trigger a test run while the interactive plugin is running. - -```javascript -class MyPlugin { - run(globalConfig, updateConfigAndRun) { - // do something. - } -} -``` diff --git a/website/versioned_sidebars/version-22.4-sidebars.json b/website/versioned_sidebars/version-22.4-sidebars.json index 64fadfa31dde..0fb00ab55d8a 100644 --- a/website/versioned_sidebars/version-22.4-sidebars.json +++ b/website/versioned_sidebars/version-22.4-sidebars.json @@ -18,7 +18,6 @@ "version-22.4-es6-class-mocks", "version-22.4-webpack", "version-22.4-puppeteer", - "version-22.4-watch-plugins", "version-22.4-mongodb", "version-22.4-migration-guide", "version-22.4-troubleshooting" From aa43d42d32ebea896b4fb9989439acd1c69f4a64 Mon Sep 17 00:00:00 2001 From: rickhanlonii Date: Thu, 24 May 2018 15:39:30 +0100 Subject: [PATCH 3/5] fix lint --- docs/WatchPlugins.md | 44 ++++++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/docs/WatchPlugins.md b/docs/WatchPlugins.md index 37a91023efc0..eb48cddeed8d 100644 --- a/docs/WatchPlugins.md +++ b/docs/WatchPlugins.md @@ -4,9 +4,13 @@ title: Watch Plugins original_id: watch-plugins --- -The Jest watch plugin system provides a way to hook into specific parts of Jest and to define watch mode menu prompts that execute code on key press. Combined, these features allow you to develop interactive experiences custom for your workflow. +The Jest watch plugin system provides a way to hook into specific parts of Jest +and to define watch mode menu prompts that execute code on key press. Combined, +these features allow you to develop interactive experiences custom for your +workflow. ## Watch Plugin Interface + ```javascript class MyWatchPlugin { // Add hooks to Jest lifecycle events @@ -19,12 +23,17 @@ class MyWatchPlugin { run(globalConfig, updateConfigAndRun) {} } ``` + ## Hooking into Jest -Custom watch plugins can add hooks to Jest events. These hooks can be added either with or without having an interactive key in the watch mode menu. + +Custom watch plugins can add hooks to Jest events. These hooks can be added +either with or without having an interactive key in the watch mode menu. ### `apply(jestHooks)` -Jest hooks can be attached by implementing the `apply` method. This method receives a `jestHooks` argument that allows the plugin to hook into -specific parts of the lifecycle of a test run. + +Jest hooks can be attached by implementing the `apply` method. This method +receives a `jestHooks` argument that allows the plugin to hook into specific +parts of the lifecycle of a test run. ```javascript class MyWatchPlugin { @@ -33,6 +42,7 @@ class MyWatchPlugin { ``` Below are the hooks available in Jest. + #### `jestHooks.shouldRunTestSuite(testPath)` Returns a boolean to specify if a test should be run or not. It can return a @@ -93,10 +103,14 @@ class MyWatchPlugin { ## Watch Menu Integration -Custom watch plugins can also add or override functionality to the watch menu by specifying a key/prompt pair in `getUsageInfo` method and a `run` method for the execution of the key. +Custom watch plugins can also add or override functionality to the watch menu by +specifying a key/prompt pair in `getUsageInfo` method and a `run` method for the +execution of the key. ### `getUsageInfo(globalConfig)` -To add a key to the watch menu, implement the `getUsageInfo` method, returning a key and the prompt: + +To add a key to the watch menu, implement the `getUsageInfo` method, returning a +key and the prompt: ```javascript class MyWatchPlugin { @@ -109,8 +123,7 @@ class MyWatchPlugin { } ``` -This will add a line in the watch mode menu -_(`› Press s to do something.`)_ +This will add a line in the watch mode menu _(`› Press s to do something.`)_ ```text Watch Usage @@ -120,13 +133,20 @@ Watch Usage › Press s to do something. // <-- This is our plugin › Press Enter to trigger a test run. ``` -**Note**: If the key for your plugin already exists as a default key, your plugin will override that key. + +**Note**: If the key for your plugin already exists as a default key, your +plugin will override that key. ### `run(globalConfig, updateConfigAndRun)` -To handle key press events from the key returned by `getUsageInfo`, you can implement the `run` method. This method returns a `Promise` that can be resolved when the plugin wants to return control to Jest. The `boolean` specifies if Jest should rerun the tests after it gets the control back. - - `globalConfig`: A representation of Jest's current global configuration - - `updateConfigAndRun`: Allows you to trigger a test run while the interactive plugin is running. +To handle key press events from the key returned by `getUsageInfo`, you can +implement the `run` method. This method returns a `Promise` that can be +resolved when the plugin wants to return control to Jest. The `boolean` +specifies if Jest should rerun the tests after it gets the control back. + +* `globalConfig`: A representation of Jest's current global configuration +* `updateConfigAndRun`: Allows you to trigger a test run while the interactive + plugin is running. ```javascript class MyWatchPlugin { From 352677c6ee3cac7cf795cda89bb695da20da4cf4 Mon Sep 17 00:00:00 2001 From: rickhanlonii Date: Thu, 24 May 2018 15:45:13 +0100 Subject: [PATCH 4/5] fix lint --- docs/WatchPlugins.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/WatchPlugins.md b/docs/WatchPlugins.md index eb48cddeed8d..1dbbfb89fb60 100644 --- a/docs/WatchPlugins.md +++ b/docs/WatchPlugins.md @@ -45,8 +45,8 @@ Below are the hooks available in Jest. #### `jestHooks.shouldRunTestSuite(testPath)` -Returns a boolean to specify if a test should be run or not. It can return a -`Promise` for handling asynchronous operations. +Returns a boolean (or `Promise` for handling asynchronous operations) +to specify if a test should be run or not. For example: @@ -82,7 +82,7 @@ class MyWatchPlugin { } ``` -#### `jestHooks.fsChange({ projects })` +#### `jestHooks.fileChange({projects})` Gets called whenever there is a change in the file system @@ -94,7 +94,7 @@ For example: ```javascript class MyWatchPlugin { apply(jestHooks) { - jestHooks.fsChange(({projects}) => { + jestHooks.fileChange(({projects}) => { this._projects = projects; }); } From 9cee1defe44be9494d8836c5c1955e860eb212e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 24 May 2018 15:52:12 +0100 Subject: [PATCH 5/5] Update WatchPlugins.md --- docs/WatchPlugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/WatchPlugins.md b/docs/WatchPlugins.md index 1dbbfb89fb60..89eecb81802a 100644 --- a/docs/WatchPlugins.md +++ b/docs/WatchPlugins.md @@ -45,7 +45,7 @@ Below are the hooks available in Jest. #### `jestHooks.shouldRunTestSuite(testPath)` -Returns a boolean (or `Promise` for handling asynchronous operations) +Returns a boolean (or `Promise`) for handling asynchronous operations) to specify if a test should be run or not. For example: