Add docs for plugins and preprocessors

CONTRIBUTING.md

@@ -9,6 +9,7 @@ Thanks for taking the time to contribute! :smile:
 - [Writing Documentation](#writing-documentation)
   - [Links](#links)
   - [Adding Examples](#adding-examples)
+  - [Adding Plugins](#adding-plugins)
 - [Committing Code](#committing-code)
   - [Linting](#linting)
   - [Pull Requests](#pull-requests)
@@ -61,15 +62,17 @@ variable set `DEBUG=docs npm run build`
 
 ### Adding Examples
 
- To add an blog, talk, or podcast to our docs, just add your data to the corresponding [blogs.yml](https://github.com/cypress-io/cypress-documentation/blob/develop/source/_data/blogs.yml), [talks.yml](https://github.com/cypress-io/cypress-documentation/blob/develop/source/_data/talks.yml), or [podcasts.yml](https://github.com/cypress-io/cypress-documentation/blob/develop/source/_data/podcasts.yml) file.
+ To add an blog, talk, or podcast to our docs, submit a [pull request](#Pull-Requests) with your data added to the corresponding [blogs.yml](https://github.com/cypress-io/cypress-documentation/blob/develop/source/_data/blogs.yml), [talks.yml](https://github.com/cypress-io/cypress-documentation/blob/develop/source/_data/talks.yml), or [podcasts.yml](https://github.com/cypress-io/cypress-documentation/blob/develop/source/_data/podcasts.yml) file.
 
 Add an associating image with the example within the [`source/img/examples`](/source/img/examples) directory. Each image should be resolution **715w x 480h**. Reference the image in the markdown document as follows:
 
 ```md
 {% img /img/examples/name-of-file.jpg "alt text describing img" %}
 ```
 
-To add anything else to an example page, the documents outlining examples are within the [`source/examples`](/source/examples) directory. Each document is written in markdown with a little bit of [Hexo flair](https://hexo.io/docs/tag-plugins.html). To add an example to a document, just try to follow the formatting of any previous examples in the markdown file.
+### Adding Plugins
+
+To add a plugin, submit a [pull request](#Pull-Requests) with the corresponding data added to the [plugins.yml](https://github.com/cypress-io/cypress-documentation/blob/develop/source/_data/plugins.yml) file. Your plugin should have a name, description, link to the plugins code, and any keywords.
 
 ## Commiting Code
 
@@ -80,8 +83,7 @@ Danger 📛: because we are minifying client side code using a [Hexo plugin](htt
 
 ### Pull Requests
 
-You should push your local changes to your forked GitHub repository and then
-open a pull request from your repo to the `cypress-io/cypress-documentation` repo.
+You should push your local changes to your forked GitHub repository and then open a pull request from your repo to the `cypress-io/cypress-documentation` repo.
 
 - The pull request should be from your repository to the `develop` branch in `cypress-io/cypress-documentation`
 - When opening a PR for a specific issue already open, please use the `address #[issue number]` or `closes #[issue number]` syntax in the pull request description.

_config.yml

@@ -57,6 +57,8 @@ alias:
   tutorials/test-a-react-todo-app/: tutorials/test-a-react-todo-app/introduction-to-tutorials.html
   tutorials/: tutorials/test-a-react-todo-app/introduction-to-tutorials.html
 
+  plugins/: plugins/index.html
+
   examples/index.html: examples/recipes/unit-testing-recipe.html
 
   dashboard/index.html: guides/core-concepts/dashboard-service.html

source/_data/main-menu.yml

@@ -1,5 +1,6 @@
 guides: /guides/overview/why-cypress.html
 api: /api/introduction/api.html
 tutorials: /tutorials/test-a-react-todo-app/introduction-to-tutorials.html
+plugins: /plugins/
 examples: /examples/recipes/unit-testing-recipe.html
 faq: /faq/questions/general-questions-faq.html

source/_data/plugins.yml

@@ -0,0 +1,16 @@
+- name: Preprocessors
+  plugins:
+    - name: Browserify
+      description: For bundling JavaScript via browserify.
+      link: https://github.com/cypress-io/cypress-browserify-preprocessor
+      keywords: [browserify]
+
+    - name: Webpack
+      description: For bundling JavaScript via webpack.
+      link: https://github.com/cypress-io/cypress-webpack-preprocessor
+      keywords: [webpack]
+
+    - name: Watch
+      description: Simple preprocessor that only watches files.
+      link: https://github.com/cypress-io/cypress-watch-preprocessor
+      keywords: [file-watcher]

source/_data/sidebar.yml

@@ -26,6 +26,7 @@ guides:
     launching-browsers: launching-browsers.html
     web-security: web-security.html
     reporters: reporters.html
+    plugins-guide: plugins-guide.html
   # advanced-cypress:
     # the-cypress-workflow: the-cypress-workflow.html
     # coming-from-selenium: coming-from-selenium.html
@@ -147,6 +148,9 @@ api:
     env: env.html
     cypress-log: cypress-log.html
     cypress-server: cypress-server.html
+  plugins:
+    plugins-api: plugins-api.html
+    preprocessors-api: preprocessors-api.html
 
 tutorials:
   test-a-react-todo-app:
@@ -156,6 +160,9 @@ tutorials:
     react-todo-form-submission: react-todo-form-submission.html
     react-todo-app-init: react-todo-app-init.html
 
+plugins:
+  plugins: index.html
+
 examples:
   recipes:
     unit-testing-recipe: unit-testing-recipe.html

source/api/commands/fixture.md

@@ -29,7 +29,7 @@ cy.fixture('logo.png').then((logo) => {
 
 **{% fa fa-angle-right %} filePath**  ***(String)***
 
-A path to a file within the {% url `fixturesFolder` configuration#Folders %} , which defaults to `cypress/fixtures`.
+A path to a file within the {% url `fixturesFolder` configuration#Folders-Files %} , which defaults to `cypress/fixtures`.
 
 You can nest fixtures within folders and reference them by defining the path from the fixturesFolder:
 
@@ -77,7 +77,7 @@ cy.fixture('users.json').as('usersData')
 
 ***Omit the fixture file's extension***
 
-When no extension is passed to `cy.fixture()`, Cypress will search for files with the specified name within the {% url `fixturesFolder` configuration#Folders %} (which defaults to `cypress/fixtures`) and resolve the first one.
+When no extension is passed to `cy.fixture()`, Cypress will search for files with the specified name within the {% url `fixturesFolder` configuration#Folders-Files %} (which defaults to `cypress/fixtures`) and resolve the first one.
 
 ```javascript
 cy.fixture('admin').as('adminJSON')

source/api/commands/screenshot.md

@@ -45,7 +45,7 @@ Option | Default | Description
 
 The screenshot will be stored in the `cypress/screenshots` folder by default.
 
-You can change the directory where screenshots are saved in your {% url 'configuration' configuration#Folders %}.
+You can change the directory where screenshots are saved in your {% url 'configuration' configuration#Folders-Files %}.
 
 ## No Args
 

source/api/plugins/plugins-api.md

@@ -0,0 +1,48 @@
+---
+title: Plugins API
+comments: false
+---
+
+The Plugins API allows you to hook into and extend Cypress behavior.
+
+# pluginsFile
+
+The API can be utilized within the plugins file, which will be searched for at `cypress/plugins/index.js` by default. Users can configure a different location for the plugins file in their `cypress.json` via the {% url "`pluginsFile`" configuration#Folders-Files %} option.
+
+{% note info %}
+The plugins file will be required by [Cypress' server](https://github.com/cypress-io/cypress/tree/master/packages/server), so it must be compatible with the [version of node that Cypress uses](https://github.com/cypress-io/cypress/blob/master/.node-version).
+{% endnote %}
+
+The plugins file should export a function with the following signature:
+
+```javascript
+module.exports = (on, config) => {
+  // configure plugins here
+}
+```
+
+The exported function is called whenever a project is opened (or at the beginning of a run if running tests headlessly) and takes 2 arguments, `on` and `config`:
+
+# on
+
+`on` is a function used on **events** that occur during the course of running Cypress. The function registered is what we call a *plugin*.
+
+{% url "Using it looks like this:" plugins-guide %}
+
+```javascript
+module.exports = (on, config) => {
+  on('<event>', (arg1, arg2) => {
+    // plugin stuff here
+  })
+}
+```
+
+The arguments received by the callback functions and the requirements for what the plugin should do depend on the **event**.
+
+***The following events are available:***
+
+* `file:preprocessor` Occurs when a spec or spec-related file is needed. Read the [Preprocessor API doc](./preprocessors.html) for more details.
+
+# config
+
+`config` is the resolved [Cypress configuration](https://on.cypress.io/guides/configuration), a combination of the default config and what the user has configured via `cypress.json`, `cypress.env.json`, command line options, and/or environment variables. Some plugins may require this to be passed along to them, so they can take certain actions based on the configuration.

source/api/plugins/preprocessors-api.md

@@ -0,0 +1,99 @@
+---
+title: Preprocessors API
+comments: false
+---
+
+A preprocessor is a {% url "plugin" plugins-api %} that runs when the {% url "support file" writing-and-organizing-tests#Support-file %} or {% url "test files" writing-and-organizing-tests#Test-files %} is required by the Test Runner.
+
+It can compile or transpile that file from another language (e.g. CoffeeScript, ClojureScript) to JavaScript or from a newer version of JavaScript (e.g. ES2017) to a version that has more browser compatibility (ES5).
+
+It can also watch the source file for changes, re-process it, and tell Cypress to re-run the tests.
+
+# Examples
+
+See the following preprocessors as examples. The code contains comments that explain how it utilizes the preprocessor API.
+
+* [Browserify Preprocessor](https://github.com/cypress-io/cypress-browserify-preprocessor)
+* [Webpack Preprocessor](https://github.com/cypress-io/cypress-webpack-preprocessor)
+* [Watch Preprocessor](https://github.com/cypress-io/cypress-watch-preprocessor)
+
+# Usage
+
+A user will configure a preprocessor by listening to the `file:preprocessor` event in their {% url "`plugins file`" configuration#Folders-Files %} (`cypress/plugins/index.js` by default), like so:
+
+```javascript
+// plugins file
+module.exports = (on) => {
+  on('file:preprocessor', (config) => {
+    // ...
+  })
+}
+```
+
+***The callback function should return one of the following:***
+
+* The path to the **output file**\*.
+* A promise\*\* that resolves the path to the **output file**\*.
+* A promise\*\* that rejects with an error that occurred during processing.
+
+\* *The output file is the file that is created by the processing and will be served to the browser. If, for example, the source file is CoffeeScript (e.g. `spec.coffee`), the preprocessor should compile the CoffeeScript into JavaScript (e.g. `spec.js`), write that JavaScript file to disk, and return or resolve the full path to that file (e.g. `/Users/foo/tmp/spec.js`).*
+
+\*\* *The promise should resolve only after the file has completed writing to disk. The promise resolving is a signal that the file is ready to be served to the browser.*
+
+{% note warning %}
+This function can and *will* be called multiple times with the same `filePath`, because it is called any time the file is requested by the browser (i.e. on each run of the tests). Make sure not to start a new watcher each time it is called. Instead, cache the watcher and, on subsequent calls, return a promise that resolves when the latest version of the file has been processed.
+{% endnote %}
+
+# Config object properties
+
+The `config` object passed to the callback function has the following properties:
+
+Property | Description
+--------- | ----------
+`filePath` | The full path to the source file.
+`outputPath` | A path unique to the source file for saving the preprocessed file to disk. A preprocessor can choose to write the file elsewhere, but this provides a convenient default path for the file (alongside other Cypress app data).
+`shouldWatch` | A boolean indicating whether the preprocessor should watch for file changes or not.
+
+# Config object events
+
+The `config` object passed to the callback function is an [Event Emitter](https://nodejs.org/api/events.html#events_class_eventemitter).
+
+***Receiving 'close' event***
+
+When the spec being run is closed or the project is closed, the 'close' event will be emitted. The preprocessor should do any necessary cleanup in this function, like closing the watcher when watching.
+
+```javascript
+// example
+const watcher = fs.watch(filePath, /* ... */)
+
+config.on('close', () => {
+  watcher.close()
+})
+```
+
+***Sending 'rerun' event***
+
+If watching for file changes, emit 'rerun' after a file has finished being processed to let Cypress know to rerun the tests.
+
+```javascript
+// example
+fs.watch(filePath, () => {
+  config.emit('rerun')
+})
+```
+
+# Publishing
+
+Publish preprocessors to [npm](https://www.npmjs.com/) with the naming convention `cypress-*-preprocessor` (e.g. cypress-clojurescript-preprocessor).
+
+Use the following npm keywords:
+
+```json
+"keywords": [
+  "cypress",
+  "cypress-plugin",
+  "cypress-preprocessor"
+]
+```
+
+Feel free to submit your published plugins to our {% url "list of plugins" plugins %}.

source/guides/core-concepts/dashboard-service.md

@@ -79,12 +79,12 @@ Make sure you {% url "install" installing-cypress %} and {% url "open" installin
 10. Within {% url 'Continuous Integration' continuous-integration %}, or from your local computer's terminal, pass the displayed {% urlHash "Record Key" Identification %} while running the {% url '`cypress run`' command-line#cypress-run %} command.
   - Provide record key directly:
     ```shell
-    cypress run --record --key abc-key-123
+    cypress run --record --key <record key>
     ```
 
   - Or set record key as environment variable
     ```shell
-    export CYPRESS_RECORD_KEY=abc-key-123
+    export CYPRESS_RECORD_KEY=<record key>
     ```
     ```shell
     cypress run --record

source/guides/core-concepts/writing-and-organizing-tests.md

@@ -24,6 +24,9 @@ After adding a new project, Cypress will automatically scaffold out a suggested
   /integration
     - example_spec.js
 
+  /plugins
+    - index.js
+
   /support
     - commands.js
     - index.js
@@ -35,7 +38,13 @@ While Cypress allows to configure where your tests, fixtures, and support files
 
 You can modify the folder configuration in your `cypress.json`. See {% url 'configuration' configuration %} for more detail.
 
-## Test Files
+## Fixture Files
+
+Fixtures are used as external pieces of static data that can be used by your tests.
+
+You would typically use them with the {% url `cy.fixture()` fixture %} command and most often when you're stubbing {% url 'Network Requests' network-requests %}.
+
+## Test files
 
 Test files may be written as:
 
@@ -54,7 +63,13 @@ To see an example of every command used in Cypress, open the {% url "`example_sp
 
 To start writing tests for your app, simply create a new file like `app_spec.js` within your `cypress/integration` folder. Refresh your tests list in the Cypress Test Runner and your new file should have appeared in the list.
 
-## Support Files
+## 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.
+
+{% url "Read more about using plugins to extend Cypress behavior." plugins-guide %}
+
+## Support file
 
 By default Cypress will automatically include the support file `cypress/support/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.
 
@@ -68,11 +83,7 @@ We automatically seed you an example support file, which has several commented o
 Our {% url 'Extending Cypress recipes' extending-cypress-recipe %} show you how to modify the support file.
 {% endnote %}
 
-## Fixture Files
 
-Fixtures are used as external pieces of static data that can be used by your tests.
-
-You would typically use them with the {% url `cy.fixture()` fixture %} command and most often when you're stubbing {% url 'Network Requests' network-requests %}.
 
 # How to Write Tests