Updates for events overhaul

cypress/integration/api_spec.coffee

@@ -6,7 +6,7 @@ API_PATH = "/api/introduction/api"
 API_HTML = API_PATH + '.html'
 
 FIRST_PAGE = "api.html"
-NEXT_PAGE = "catalog-of-events.html"
+NEXT_PAGE = "and.html"
 
 describe "API", ->
   context "Catalog of events", ->

source/_data/sidebar.yml

@@ -29,7 +29,7 @@ guides:
     web-security: web-security.html
   tooling:
     intelligent-code-completion: intelligent-code-completion.html
-    plugins-guide: plugins-guide.html
+    background-process: background-process.html
     reporters: reporters.html
     typescript-support: typescript-support.html
 
@@ -51,14 +51,13 @@ guides:
     trade-offs: trade-offs.html
     # contributing: contributing.html
     changelog: changelog.html
+    migration-guide: migration-guide.html
     roadmap: roadmap.html
     # all-videos: all-videos.html
 
 api:
   introduction:
     api: api.html
-  events:
-    catalog-of-events: catalog-of-events.html
   assertions:
     all-assertions: assertions.html
   commands:
@@ -149,6 +148,36 @@ api:
     minimatch: minimatch.html
     moment: moment.html
     promise: promise.html
+  events:
+    catalog-of-events: catalog-of-events.html
+    after-screenshot-event: after-screenshot-event.html
+    after-run-event: after-run-event.html
+    after-spec-event: after-spec-event.html
+    after-test-run-event: after-test-run-event.html
+    before-browser-launch-event: before-browser-launch-event.html
+    before-run-event: before-run-event.html
+    before-spec-event: before-spec-event.html
+    before-test-run-event: before-test-run-event.html
+    before-window-load-event: before-window-load-event.html
+    before-window-unload-event: before-window-unload-event.html
+    command-end-event: command-end-event.html
+    command-enqueued-event: command-enqueued-event.html
+    command-retry-event: command-retry-event.html
+    command-start-event: command-start-event.html
+    configuration-event: configuration-event.html
+    fail-event: fail-event.html
+    file-preprocessor-event: file-preprocessor-event.html
+    log-added-event: log-added-event.html
+    log-changed-event: log-changed-event.html
+    scrolled-event: scrolled-event.html
+    task-event: task-event.html
+    uncaught-exception-event: uncaught-exception-event.html
+    url-changed-event: url-changed-event.html
+    viewport-changed-event: viewport-changed-event.html
+    window-alert-event: window-alert-event.html
+    window-confirm-event: window-confirm-event.html
+    window-load-event: window-load-event.html
+    window-unload-event: window-unload-event.html
   cypress-api:
     custom-commands: custom-commands.html
     cookies: cookies.html
@@ -164,12 +193,6 @@ api:
     platform: platform.html
     spec: spec.html
     version: version.html
-  plugins:
-    writing-a-plugin: writing-a-plugin.html
-    configuration-api: configuration-api.html
-    preprocessors-api: preprocessors-api.html
-    browser-launch-api: browser-launch-api.html
-    after-screenshot-api: after-screenshot-api.html
 
 plugins:
   plugins: index.html

source/api/commands/screenshot.md

@@ -174,9 +174,9 @@ describe('my tests', function () {
 })
 ```
 
-## `after:screenshot` plugin event
+## `after:screenshot` background event
 
-You can get details about any given screenshot and manipulate it after it has been written to disk with the {% url '`after:screenshot` plugin event' after-screenshot-api %}.
+You can get details about any given screenshot and manipulate it after it has been written to disk with the {% url '`after:screenshot` background event' after-screenshot-event %}.
 
 ## Test Failures
 
@@ -247,7 +247,7 @@ When clicking on `screenshot` within the command log, the console outputs the fo
 # See also
 
 - {% url `Cypress.Screenshot` screenshot-api %}
-- {% url 'After Screenshot API' after-screenshot-api %}
+- {% url '`after:screenshot` event' after-screenshot-event %}
 - {% url `cy.debug()` debug %}
 - {% url 'Dashboard Service' dashboard-service %}
 - {% url 'Screenshots and Videos' screenshots-and-videos %}

source/api/commands/task.md

@@ -2,10 +2,10 @@
 title: task
 ---
 
-Execute code in {% url "Node.js" https://nodejs.org %} via the `task` plugin event.
+Execute code in {% url "Node.js" https://nodejs.org %} via the {% url "`task` background event" task-event %}.
 
 {% note warning 'Anti-Pattern' %}
-We do not recommend starting a web server using `cy.task()`. Read about {% url 'best practices' best-practices#Web-Servers %} here.
+We do not recommend starting a web server using `cy.task()`. Read more about {% url "the `task` background event" task-event#Notes %} and about {% url 'best practices' best-practices#Web-Servers %}.
 {% endnote %}
 
 # Syntax
@@ -24,8 +24,9 @@ cy.task(event, arg, options)
 // in test
 cy.task('log', 'This will be output to the terminal')
 ```
+
 ```javascript
-// in plugins file
+// in background file
 on('task', {
   log (message) {
     console.log(message)
@@ -38,7 +39,7 @@ on('task', {
 
 **{% fa fa-angle-right %} event** ***(String)***
 
-An event name to be handled via the `task` event in the {% url "`pluginsFile`" configuration#Folders-Files %}.
+An event name to be handled via the {% url "`task` event" task-event %} in the {% url "`backgroundFile`" configuration#Folders-Files %}.
 
 **{% fa fa-angle-right %} arg** ***(Object)***
 
@@ -55,7 +56,7 @@ Option | Default | Description
 
 ## Yields {% helper_icon yields %}
 
-`cy.task()` yields the value returned or resolved by the `task` event in the {% url "`pluginsFile`" configuration#Folders-Files %}.
+`cy.task()` yields the value returned or resolved by the `task` event in the {% url "`backgroundFile`" configuration#Folders-Files %}.
 
 # Examples
 
@@ -68,9 +69,9 @@ Option | Default | Description
 - Performing parallel tasks, like making multiple http requests outside of Cypress.
 - Running an external process.
 
-In the `task` plugin event, the command will fail if `undefined` is returned. This helps catch typos or cases where the task event is not handled. 
+In the {% url "`task` background event" task-event %}, the command will fail if `undefined` is returned. It will also fail if you return a promise that resolves `undefined`. This helps catch typos or cases where the task event is not handled.
 
-If you do not need to return a value, explicitly return `null` to signal that the given event has been handled.
+If you do not need to return a value, explicitly return or resolve `null` to signal that the given event has been handled.
 
 ### Read a JSON file's contents
 
@@ -88,11 +89,13 @@ cy.task('readJson', 'cypress.json').then((data) => {
 ```
 
 ```javascript
-// in plugins/index.js file
+// in background/index.js file
+const fs = require('fs-extra')
+
 on('task', {
   readJson: (filename) => {
     // reads the file relative to current working directory
-    return fsExtra.readJson(path.join(process.cwd(), filename)
+    return fs.readJson(path.join(process.cwd(), filename)
   }
 })
 ```
@@ -103,7 +106,7 @@ on('task', {
 // in test
 describe('e2e', () => {
   beforeEach(() => {
-    cy.task('defaults:db')
+    cy.task('seed:database')
     cy.visit('/')
   })
 
@@ -115,15 +118,15 @@ describe('e2e', () => {
 ```
 
 ```javascript
-// in plugins/index.js file
+// in background/index.js file
 // we require some code in our app that
 // is responsible for seeding our database
-const db = require('../../server/src/db')
+const database = require('../../app/database')
 
 module.exports = (on, config) => {
   on('task', {
-    'defaults:db': () => {
-      return db.seed('defaults')
+    'seed:database': () => {
+      return database.seed()
     }
   })
 }
@@ -142,20 +145,6 @@ Cypress will *not* continue running any other commands until `cy.task()` has fin
 cy.task('seedDatabase', null, { timeout: 20000 });
 ```
 
-# Notes
-
-## Tasks must end
-
-### Tasks that do not end are not supported
-
-`cy.task()` does not support tasks that do not end, such as:
-
-- Starting a server.
-- A task that watches for file changes.
-- Any process that needs to be manually interrupted to stop.
-
-A task must end within the `taskTimeout` or Cypress will fail the current test.
-
 # Rules
 
 ## Requirements {% helper_icon requirements %}
@@ -184,10 +173,11 @@ The command above will display in the command log as:
 
 When clicking on the `task` command within the command log, the console outputs the following:
 
-![console.log task](/img/api/task/console-shows-task-result.png)
+![console.log task](/img/api/task/console-shresult.png)
 
 # See also
 
+- {% url "`task` event" task-event %}
 - {% url `cy.exec()` exec %}
 - {% url `cy.fixture()` fixture %}
 - {% url `cy.readFile()` readfile %}

source/api/commands/trigger.md

@@ -3,7 +3,7 @@ title: trigger
 
 ---
 
-Trigger an event on a DOM element.  
+Trigger an event on a DOM element.
 
 # Syntax
 
@@ -88,9 +88,9 @@ cy.get('.target').trigger('mousedown')
 cy.wait(1000)
 cy.get('.target').trigger('mouseleave')
 ```
-### jQuery UI Sortable 
+### jQuery UI Sortable
 
-To simulate drag and drop using jQuery UI sortable requires `pageX` and `pageY` properties along with `which:1`.     
+To simulate drag and drop using jQuery UI sortable requires `pageX` and `pageY` properties along with `which:1`.
 
 ```javascript
 cy.get('[data-cy=draggable]')

source/api/events/after-run-event.md

@@ -0,0 +1,48 @@
+---
+title: after:run Event
+---
+
+The `after:run` event fires after the run finishes.
+
+# Environment
+
+Occurs only in the {% url "background process" background-process %}.
+
+# Arguments
+
+* run results **(Object)**
+
+# Usage
+
+```javascript
+// cypress/background/index.js
+
+module.exports = (on, config) => {
+  on('after:run', (results) => {
+    // results will look something like this:
+    // {
+    //   totalDuration: 81,
+    //   totalSuites: 0,
+    //   totalTests: 1,
+    //   totalFailed: 0,
+    //   totalPassed: 1,
+    //   totalPending: 0,
+    //   totalSkipped: 0,
+    //   browserName: 'electron',
+    //   browserVersion: '59.0.3071.115',
+    //   osName: 'darwin',
+    //   osVersion: '16.7.0',
+    //   cypressVersion: '3.1.0',
+    //   config: {
+    //     projectId: '1qv3w7',
+    //     baseUrl: 'http://example.com',
+    //     viewportWidth: 1000,
+    //     viewportHeight: 660,
+    //     // more properties...
+    //   }
+    //   // ... more properties...
+    //   }
+    // }
+  })
+}
+```

source/api/plugins/after-screenshot-api.md → source/api/events/after-screenshot-event.md

@@ -1,17 +1,25 @@
 ---
-title: After Screenshot API
+title: after:screenshot event
 ---
 
-After a screenshot is taken, you can get details about the screenshot via the `after:screenshot` plugin event. This event is called whether a screenshot is taken with {% url `cy.screenshot()` screenshot %} or as a result of a test failure. The event is called after the screenshot image is written to disk.
+After a screenshot is taken, you can get details about the screenshot via the `after:screenshot` background event. This event is called whether a screenshot is taken with {% url `cy.screenshot()` screenshot %} or as a result of a test failure. The event is called after the screenshot image is written to disk.
 
 This allows you to record those details or manipulate the image as needed. You can also return updated details about the image.
 
+# Environment
+
+Occurs only in the {% url "background process" background-process %}.
+
+# Arguments
+
+* screenshot details **(Object)**
+
 # Usage
 
-Using your {% url "`pluginsFile`" plugins-guide %} you can tap into the `after:screenshot` event.
+Using your {% url "`backgroundFile`" background-process %} you can tap into the `after:screenshot` event.
 
 ```js
-// cypress/plugins/index.js
+// cypress/background/index.js
 
 const fs = require('fs')
 

source/api/events/after-spec-event.md

@@ -0,0 +1,57 @@
+---
+title: after:spec  Event
+---
+
+The `after:spec` event fires after a spec file and its tests run.
+
+# Environment
+
+Occurs only in the {% url "background process" background-process %}.
+
+# Arguments
+
+* spec **(Object)**
+* spec results **(Object)**
+
+# Usage
+
+```javascript
+// cypress/background/index.js
+
+module.exports = (on, config) => {
+  on('after:spec', (spec, results) => {
+    // spec will look something like this:
+    // {
+    //   name: 'login_spec.js',
+    //   relative: 'cypress/integration/login_spec.js',
+    //   absolute: '/Users/janelane/app/cypress/integration/login_spec.js',
+    // }
+
+    // results will look something like this:
+    // {
+    //   stats: {
+    //     suites: 0,
+    //     tests: 1,
+    //     passes: 1,
+    //     pending: 0,
+    //     skipped: 0,
+    //     failures: 0,
+    //     // ...more properties
+    //   }
+    //   reporter: 'spec',
+    //   tests: [
+    //     {
+    //       title: ['login', 'logs user in'],
+    //       state: 'passed',
+    //       body: 'function () {}',
+    //       // ...more properties...
+    //     }
+    //   ],
+    //   error: null,
+    //   video: '/Users/janelane/app/cypress/videos/passing_spec.js.mp4',
+    //   screenshots: [],
+    //   // ...more properties...
+    // }
+  })
+}
+```