diff --git a/source/_partial/code_runs_in_node.md b/source/_partial/code_runs_in_node.md new file mode 100644 index 0000000000..36c14cdf35 --- /dev/null +++ b/source/_partial/code_runs_in_node.md @@ -0,0 +1,3 @@ +{% note warning %} +⚠️ This code is part of the [plugin file](/guides/core-concepts/writing-and-organizing-tests.html#Plugin-files) and thus executes in the Node environment. You cannot call `Cypress` or `cy` commands in this file, but you do have the direct access to the file system and the rest of the operating system. +{% endnote %} diff --git a/source/api/plugins/after-run-api.md b/source/api/plugins/after-run-api.md index 4170a0866b..08aa18fb5f 100644 --- a/source/api/plugins/after-run-api.md +++ b/source/api/plugins/after-run-api.md @@ -13,6 +13,8 @@ The event will fire each time `cypress run` executes. As a result, if running yo # Syntax +{% partial code_runs_in_node %} + ```js on('after:run', (results) => { /* ... */ }) ``` diff --git a/source/api/plugins/after-screenshot-api.md b/source/api/plugins/after-screenshot-api.md index 15dfc2745b..bdbdd81093 100644 --- a/source/api/plugins/after-screenshot-api.md +++ b/source/api/plugins/after-screenshot-api.md @@ -8,6 +8,8 @@ This allows you to record those details, manipulate the image as needed, and ret # Syntax +{% partial code_runs_in_node %} + ```js on('after:screenshot', (details) => { /* ... */ }) ``` diff --git a/source/api/plugins/after-spec-api.md b/source/api/plugins/after-spec-api.md index 65d00266e7..4c755a7bda 100644 --- a/source/api/plugins/after-spec-api.md +++ b/source/api/plugins/after-spec-api.md @@ -11,6 +11,8 @@ The `after:spec` event fires after a spec file is run. The event only fires when # Syntax +{% partial code_runs_in_node %} + ```js on('after:spec', (spec, results) => { /* ... */ }) ``` diff --git a/source/api/plugins/before-run-api.md b/source/api/plugins/before-run-api.md index d41beffaf6..1ace0d5b40 100644 --- a/source/api/plugins/before-run-api.md +++ b/source/api/plugins/before-run-api.md @@ -13,6 +13,8 @@ The event will fire each time `cypress run` executes. As a result, if running yo # Syntax +{% partial code_runs_in_node %} + ```js on('before:run', (details) => { /* ... */ }) ``` diff --git a/source/api/plugins/before-spec-api.md b/source/api/plugins/before-spec-api.md index 3b133a7b9b..9a55963093 100644 --- a/source/api/plugins/before-spec-api.md +++ b/source/api/plugins/before-spec-api.md @@ -11,6 +11,8 @@ The `before:spec` event fires before a spec file is run. The event only fires wh # Syntax +{% partial code_runs_in_node %} + ```js on('before:spec', (spec) => { /* ... */ }) ``` diff --git a/source/api/plugins/browser-launch-api.md b/source/api/plugins/browser-launch-api.md index ed66dcc6c1..5253b7a2ad 100644 --- a/source/api/plugins/browser-launch-api.md +++ b/source/api/plugins/browser-launch-api.md @@ -6,6 +6,8 @@ Before Cypress launches a browser, it gives you the opportunity to modify the br # Syntax +{% partial code_runs_in_node %} + ```js on('before:browser:launch', (browser = {}, launchOptions) => { /* ... */ }) ``` diff --git a/source/api/plugins/configuration-api.md b/source/api/plugins/configuration-api.md index f53003f93d..8327db9bc8 100644 --- a/source/api/plugins/configuration-api.md +++ b/source/api/plugins/configuration-api.md @@ -6,6 +6,8 @@ Cypress enables you to dynamically modify configuration values and environment v # Usage +{% partial code_runs_in_node %} + To modify configuration, you return an object from your plugins file exported function. ```javascript diff --git a/source/api/plugins/preprocessors-api.md b/source/api/plugins/preprocessors-api.md index b3eb26823a..70de2ee1f6 100644 --- a/source/api/plugins/preprocessors-api.md +++ b/source/api/plugins/preprocessors-api.md @@ -47,6 +47,8 @@ If you don't use webpack in your project or would like to keep the majority of t # Usage +{% partial code_runs_in_node %} + To use a preprocessor, you should bind to the `file:preprocessor` event in your {% url "`pluginsFile`" configuration#Folders-Files %}: ```javascript diff --git a/source/api/plugins/writing-a-plugin.md b/source/api/plugins/writing-a-plugin.md index 8a0c390c3d..36a0e9f3a8 100644 --- a/source/api/plugins/writing-a-plugin.md +++ b/source/api/plugins/writing-a-plugin.md @@ -27,6 +27,8 @@ module.exports = (on, config) => { } ``` +{% partial code_runs_in_node %} + The exported function is called whenever a project is opened either with {% url "`cypress open`" command-line#cypress-open %} or {% url "`cypress run`" command-line#cypress-run %}. Your function will receive 2 arguments: `on` and `config`. diff --git a/source/guides/core-concepts/writing-and-organizing-tests.md b/source/guides/core-concepts/writing-and-organizing-tests.md index 031b7b0b54..39f2cc78fb 100644 --- a/source/guides/core-concepts/writing-and-organizing-tests.md +++ b/source/guides/core-concepts/writing-and-organizing-tests.md @@ -134,11 +134,11 @@ To learn more about videos and settings available, see {% url "Screenshots and V ## Plugin files -By default Cypress will automatically include the plugins file `cypress/plugins/index.js` **before** every single spec file it runs. We do this purely as a convenience mechanism so you don't have to import this file in every single one of your spec files. +The plugin file is a special file that executes in Node before the project is loaded, before the browser launches, and during your test execution. While the Cypress tests execute in the browser, the plugin file runs in the background Node process, giving your tests the ability to access the file system and the rest of the operating system by calling the {% url "cy.task()" task %} command. -The initial imported plugins file can be {% url 'configured to another file' configuration#Folders-Files %}. +The plugin file is a good place to define how you want to bundle the spec files via the {% url "preprocessors" preprocessors-api %}, how to find and launch the browsers via the {% url "browser launch API" browser-launch-api %}, and other cool things. Read our {% url "plugins guide" plugins-guide %} for more details and examples. -{% url "Read more about using plugins to extend Cypress behavior." plugins-guide %} +The initial imported plugins file can be {% url 'configured to another file' configuration#Folders-Files %}. ## Support file diff --git a/source/guides/tooling/plugins-guide.md b/source/guides/tooling/plugins-guide.md index 675f19aeb7..0c5a4dda44 100644 --- a/source/guides/tooling/plugins-guide.md +++ b/source/guides/tooling/plugins-guide.md @@ -116,6 +116,8 @@ You can use the `task` event to do things like: The {% url "Real World App (RWA)" https://github.com/cypress-io/cypress-realworld-app %} uses {% url tasks task %} to re-seed its database, and to filter/find test data for various testing scenarios. +{% partial code_runs_in_node %} + ```ts // cypress/plugins/index.ts