feat: set flag from plugins task that they were registered (#180)

* feat: set flag from plugins task that they were registered

BREAKING CHANGE: the task sets an environment variable and needs
to return its config. The new registration thus looks like this

```js
// your plugins file
module.exports = (on, config) => {
  require('cypress/code-coverage/task')(on, config)
  // IMPORTANT to return the config object
  // with the any changed environment variables
  return config
}
```

Support code can check variable `Cypress.env('codeCoverageTasksRegistered')`
before calling `cy.task`

* update readme

* update examples

* add small plugins file

* update readme

* add example using plugins and support

* add new example to CI

* no need to start server in the example

Author: bahmutov

.circleci/config.yml

@@ -251,6 +251,35 @@ workflows:
                   node ../../scripts/only-covered main.js
                 working_directory: examples/support-files
 
+      - cypress/run:
+          attach-workspace: true
+          name: example-use-plugins-and-support
+          requires:
+            - cypress/install
+          # there are no jobs to follow this one
+          # so no need to save the workspace files (saves time)
+          no-workspace: true
+          command: npx cypress run --project examples/use-plugins-and-support
+          # store screenshots and videos
+          store_artifacts: true
+          post-steps:
+            - run: cat examples/use-plugins-and-support/.nyc_output/out.json
+            # store the created coverage report folder
+            # you can click on it in the CircleCI UI
+            # to see live static HTML site
+            - store_artifacts:
+                path: examples/use-plugins-and-support/coverage
+            # make sure the examples captures 100% of code
+            - run:
+                command: npx nyc report --check-coverage true --lines 100
+                working_directory: examples/use-plugins-and-support
+            - run:
+                name: Check code coverage 📈
+                command: |
+                  node ../../scripts/check-coverage main.js
+                  node ../../scripts/only-covered main.js
+                working_directory: examples/use-plugins-and-support
+
       - publish:
           filters:
             branches:
@@ -266,3 +295,4 @@ workflows:
             - example-ts-example
             - example-same-folder
             - example-support-files
+            - example-use-plugins-and-support

README.md

@@ -23,7 +23,10 @@ Register tasks in your `cypress/plugins/index.js` file
 
 ```js
 module.exports = (on, config) => {
-  on('task', require('@cypress/code-coverage/task'))
+  require('@cypress/code-coverage/task')(on, config)
+  // IMPORTANT to return the config object
+  // with the any changed environment variables
+  return config
 }
 ```
 
@@ -109,8 +112,9 @@ Put the following in `cypress/plugins/index.js` file to use `.babelrc` file
 
 ```js
 module.exports = (on, config) => {
-  on('task', require('@cypress/code-coverage/task'))
+  require('@cypress/code-coverage/task')(on, config)
   on('file:preprocessor', require('@cypress/code-coverage/use-babelrc'))
+  return config
 }
 ```
 
@@ -122,11 +126,12 @@ If you cannot use `.babelrc` for some reason (maybe it is used by other tools?),
 
 ```js
 module.exports = (on, config) => {
-  on('task', require('@cypress/code-coverage/task'))
+  require('@cypress/code-coverage/task')(on, config)
   on(
     'file:preprocessor',
     require('@cypress/code-coverage/use-browserify-istanbul')
   )
+  return config
 }
 ```
 
@@ -349,6 +354,37 @@ npm run dev:no:coverage
 - [bahmutov/code-coverage-subfolder-example](https://github.com/bahmutov/code-coverage-subfolder-example) shows how to instrument `app` folder using `nyc instrument` as a separate step before running E2E tests
 - [bahmutov/docker-with-cypress-included-code-coverage-example](https://github.com/bahmutov/docker-with-cypress-included-code-coverage-example) runs tests inside pre-installed Cypress using [cypress/included:x.y.z](https://github.com/cypress-io/cypress-docker-images/tree/master/included) Docker image and reports code coverage.
 
+## Migrations
+
+### v2 to v3
+
+Change the plugins file `cypress/plugins/index.js`
+
+```js
+// BEFORE
+module.exports = (on, config) => {
+  on('task', require('@cypress/code-coverage/task'))
+}
+// AFTER
+module.exports = (on, config) => {
+  require('@cypress/code-coverage/task')(on, config)
+  // IMPORTANT to return the config object
+  // with the any changed environment variables
+  return config
+}
+```
+
+**Tip:** we include [plugins.js](plugins.js) file you can point at from your code in simple cases. From your `cypress.json` file:
+
+```json
+{
+  "pluginsFile": "node_modules/@cypress/code-coverage/plugins",
+  "supportFile": "node_modules/@cypress/code-coverage/support"
+}
+```
+
+See [examples/use-plugins-and-support](examples/use-plugins-and-support)
+
 ## Debugging
 
 This plugin uses [debug](https://github.com/visionmedia/debug) module to output additional logging messages from its [task.js](task.js) file. This can help with debugging errors while saving code coverage or reporting. In order to see these messages, run Cypress from the terminal with environment variable `DEBUG=code-coverage`. Example using Unix syntax to set the variable:

cypress/plugins/index.js

@@ -1,5 +1,5 @@
 module.exports = (on, config) => {
-  on('task', require('../../task'))
+  require('../../task')(on, config)
 
   // also use .babelrc file when bundling spec files
   // to get the code coverage from unit tests
@@ -9,4 +9,7 @@ module.exports = (on, config) => {
   // or use browserify and just push babel-plugin-istanbul
   // directory to the list of babelify plugins
   // on('file:preprocessor', require('../../use-browserify-istanbul'))
+
+  // IMPORTANT to return the config object with changed environment variable
+  return config
 }

examples/before-all-visit/cypress/plugins/index.js

@@ -1,3 +1,6 @@
 module.exports = (on, config) => {
-  on('task', require('../../../../task'))
+  require('../../../../task')(on, config)
+  // IMPORTANT to return the config object
+  // with the any changed environment variables
+  return config
 }

examples/before-each-visit/cypress/plugins/index.js

@@ -1,3 +1,6 @@
 module.exports = (on, config) => {
-  on('task', require('../../../../task'))
+  require('../../../../task')(on, config)
+  // IMPORTANT to return the config object
+  // with the any changed environment variables
+  return config
 }

examples/same-folder/plugins.js

@@ -1,4 +1,5 @@
 module.exports = (on, config) => {
-  on('task', require('../../task'))
+  require('../../task')(on, config)
   on('file:preprocessor', require('../../use-babelrc'))
+  return config
 }

examples/support-files/cypress/plugins/index.js

@@ -1,4 +1,5 @@
 module.exports = (on, config) => {
-  on('task', require('../../../../task'))
+  require('../../../../task')(on, config)
   on('file:preprocessor', require('../../../../use-babelrc'))
+  return config
 }

examples/ts-example/cypress/plugins/index.js

@@ -1,3 +1,4 @@
 module.exports = (on, config) => {
-  on('task', require('../../../../task'))
+  require('../../../../task')(on, config)
+  return config
 }

examples/use-plugins-and-support/README.md

@@ -0,0 +1,5 @@
+# example: use-plugins-and-support
+
+Using included plugins and support files
+
+See [cypress.json](cypress.json) file

examples/use-plugins-and-support/cypress.json

@@ -0,0 +1,5 @@
+{
+  "pluginsFile": "../../plugins",
+  "supportFile": "../../support",
+  "fixturesFolder": false
+}

examples/use-plugins-and-support/cypress/integration/spec.js

@@ -0,0 +1,18 @@
+/// <reference types="cypress" />
+describe('coverage information', () => {
+  beforeEach(() => {
+    cy.visit('index.html')
+  })
+
+  it('calls add', () => {
+    cy.window()
+      .invoke('add', 2, 3)
+      .should('equal', 5)
+  })
+
+  it('calls sub', () => {
+    cy.window()
+      .invoke('sub', 2, 3)
+      .should('equal', -1)
+  })
+})

examples/use-plugins-and-support/index.html

@@ -0,0 +1,4 @@
+<body>
+  Page body
+  <script src="main-instrumented.js"></script>
+</body>

examples/use-plugins-and-support/main-instrumented.js

@@ -0,0 +1,3 @@
+window.add = (a, b) => a + b
+
+window.sub = (a, b) => a - b

examples/use-plugins-and-support/main.js

@@ -0,0 +1,8 @@
+{
+  "name": "use-plugins-and-support",
+  "description": "Using included plugins and support files",
+  "devDependencies": {},
+  "scripts": {
+    "cy:open": "../../node_modules/.bin/cypress open"
+  }
+}

examples/use-plugins-and-support/package-lock.json

@@ -0,0 +1,13 @@
+// common Cypress plugin file you can point at to have the
+// code coverage tasks registered correctly. From your "cypress.json" file
+// {
+//   "pluginsFile": "@cypress/code-coverage/plugins",
+//   "supportFile": "@cypress/code-coverage/support"
+// }
+//
+module.exports = (on, config) => {
+  require('./task')(on, config)
+  // IMPORTANT to return the config object
+  // with the any changed environment variables
+  return config
+}