From 57c162e225d87c596d6788c6783188c36e1aa20c Mon Sep 17 00:00:00 2001 From: Brian Mann Date: Fri, 17 Nov 2017 17:58:13 -0500 Subject: [PATCH] rewrite plugins guide to better explain what plugins are, what you can do with them, and how to get started --- source/guides/guides/plugins-guide.md | 92 ++++++++++++++++++--------- 1 file changed, 62 insertions(+), 30 deletions(-) diff --git a/source/guides/guides/plugins-guide.md b/source/guides/guides/plugins-guide.md index 65eeef2de9..b9c9f5e92c 100644 --- a/source/guides/guides/plugins-guide.md +++ b/source/guides/guides/plugins-guide.md @@ -3,59 +3,91 @@ title: Plugins comments: false --- -Plugins provides a way for hooking into and extending the behavior of Cypress. Plugins can be configured within the plugins file, which will be searched for at `cypress/plugins/index.js` by default. +Plugins enable you to tap into, modify, or extend the internal behavior of Cypress. -{% note info %} -You can configure a different location for the plugins file in your `cypress.json` via the {% url "`pluginsFile`" configuration#Folders-Files %} option. +Normally, as a user all of your test code, your application, and commands are executed in the browser. But Cypress is also a **Node.js** process which plugins can use. + +> Plugins enable you to tap into the `node` process running outside of the browser. + +Plugins are a "seam" for you to write your own custom code that executes during particular stages of the Cypress lifecycle. + +{% note info "New Projects" %} +When new projects are added to Cypress we will automatically seed them with a basic plugins file. + +By default Cypress will create a plugins file at: `cypress/plugins/index.js`. + +This is configurable in your `cypress.json` with the {% url "`pluginsFile`" configuration#Folders-Files %} option. {% endnote %} -# Installation +# Plugin Types + +## Preprocessors + +As of today we offer a single plugin event: `file:preprocessor`. This event is used to customize how your test code is transpiled and sent to the browser. By default Cypress handles `coffeescript` and `ES6` using `babel` and then uses `browserify` to package it for the browser. -See the list of available {% url "plugins" plugins %} to install. +You can use the `file:preprocessor` event to do things like: + +- Add `Typescript` support +- Add the latest ES* support +- Write your test code in `Clojurescript` +- Customize the `babel` settings to add your own plugins +- Swap out `browserify` for `webpack` or anything else + +Check out our {% url 'File Preprocessor API docs' preprocessors-api %} which describe how to use this event. + +# List of Plugins + +Cypress maintains an official list of plugins created by us as well as the community. You can NPM install any of the plugins listed below: + +{% url 'Here is our official list of Cypress plugins.' plugins %} + +# Installing Plugins + +Plugins that we and other contributors write are just NPM modules. This enables them to be versioned and updated separately without needing to update Cypress itself. + +You can install any published plugin with NPM: ```shell npm install <plugin name> --save-dev ``` -Installing a plugin requires [node.js](https://nodejs.org) (version 6.5.0+). +# Using a Plugin -# Usage +Whether you install an NPM module, or just want to write your own code - you do all of that in this file: -```javascript -module.exports = (on, config) => { - on('', (arg1, arg2) => { - // plugin stuff here - }) -} +```text +cypress/plugins/index.js ``` -The **event** depends on the {% urlHash "type of plugin" Plugin-types %} you are using. The exact usage depends on the plugin itself, so refer to any given plugin's documentation for details on its usage. +{% note info %} +By default Cypress seeds this file for new projects, but if you have an existing project just create this file yourself. +{% endnote %} -For example, here's how to use the [webpack preprocessor](https://github.com/cypress-io/cypress-webpack-preprocessor): +Inside of this file, you'll export a function. Cypress will call this function, pass you the project's configuration, and enable you to bind to the events we expose. ```javascript -const webpack = require('@cypress/webpack-preprocessor') +// cypress/plugins/index.js +// export a function module.exports = (on, config) => { - on('file:preprocessor', webpack(config)) + + // bind to the event we care about + on('', (arg1, arg2) => { + // plugin stuff here + }) } ``` -# Plugin types +Check out our {% url 'Writing a Plugin API docs' writing-a-plugin %} which describes how to write plugins. -## Preprocessors +{% note warning "Node Version" %} -Preprocessors are plugins that can process your {% url "support file" writing-and-organizing-tests#Support-file %} and {% url "test files" writing-and-organizing-tests#Test-files %} before they are served to the browser. They are also responsible for watching files for changes and notifying Cypress to re-run tests. +Keep in mind - code executed in plugins is executed **by the node version** that comes bundled in Cypress itself. -* **Event:** `file:preprocessor` -* **Examples:** {% url "browserify-preprocessor" https://github.com/cypress-io/cypress-browserify-preprocessor %}, {% url "webpack-preprocessor" https://github.com/cypress-io/cypress-webpack-preprocessor %}, {% url "watch-preprocessor" https://github.com/cypress-io/cypress-watch-preprocessor %} +This version of node has **nothing to do** with your locally installed versions. Therefore you have to write node code which is compatible with this version. -```javascript -// the plugins file -const webpack = require('@cypress/webpack-preprocessor') +Currently the node version we use is `6.5.0`. -module.exports = (on, config) => { - // register the webpack plugin, using its default options - on('file:preprocessor', webpack(config)) -} -``` +This gets regularly updated (next version will be in the `8.x.x` range) so you'll likely be able to use all the latest ES7 features. + +{% endnote %}