feat!: read code coverage config from Cypress.expose instead of Cypress.env

.circleci/config.yml

@@ -2,7 +2,7 @@
 version: 2.1
 orbs:
   # https://github.com/cypress-io/circleci-orb
-  cypress: cypress-io/cypress@3.0.0 # used to run e2e tests
+  cypress: cypress-io/cypress@6.0.0 # used to run e2e tests
   win: circleci/windows@5.1.0 # run a test job on Windows
 
 jobs:
@@ -40,14 +40,21 @@ jobs:
     steps:
       - checkout
       - run:
-          name: Install node 20
-          command: nvm install 20.12.1
+          name: Install node 22
+          command: nvm install 22
       - run:
-          name: Use node 20
-          command: nvm use 20.12.1
+          name: Use node 22
+          command: nvm use 22
       - run:
           name: Install deps for code coverage
           command: npm ci
+      - run:
+          name: Build project
+          command: npm run build
+      - run:
+          name: Install test app deps
+          command: npm i
+          working_directory: test-apps/all-files
       - cypress/run-tests:
           # no-workspace: true
           start-command: npm run start:windows --prefix test-apps/all-files
@@ -68,6 +75,18 @@ jobs:
           command: npm i -D check-code-coverage && npm run coverage:check-files
           working_directory: test-apps/all-files
 
+  build-dist:
+    docker:
+      - image: cimg/node:22.14.0
+    steps:
+      - attach_workspace:
+          at: ~/
+      - run: npm run build
+      - persist_to_workspace:
+          paths:
+            - project/dist
+          root: ~/
+
   publish:
     description: Publishes the new version of the plugin to NPM
     docker:
@@ -85,45 +104,45 @@ jobs:
           at: ~/
       - run: npm run semantic-release
 
-  cyrun:
+  verify-test-apps:
     docker:
-      - image: cypress/base:16.18.1
+      - image: cypress/base:22.14.0
     parameters:
-      jobname:
+      app:
         type: string
     steps:
       - attach_workspace:
           at: ~/
+      - run:
+          working_directory: test-apps/<< parameters.app >>
+          command: npm i
       - run:
           command: npm run test
-          working_directory: test-apps/<< parameters.jobname >>
+          working_directory: test-apps/<< parameters.app >>
       - store_artifacts:
-          path: test-apps/<< parameters.jobname >>/coverage
+          path: test-apps/<< parameters.app >>/coverage
       - run:
           name: Verify Code Coverage
           command: npm run coverage:verify
-          working_directory: test-apps/<< parameters.jobname >>
+          working_directory: test-apps/<< parameters.app >>
       - run:
           name: Check code coverage files 📈
           # we will check the final coverage report
           # to make sure it only has files we are interested in
           # because there are files covered at 0 in the report
           command: npm run coverage:check-files
-          working_directory: test-apps/<< parameters.jobname >>
+          working_directory: test-apps/<< parameters.app >>
 
-  test-code-coverage-plugin:
+  unit-test:
     docker:
-      - image: cypress/base:16.18.1
+      - image: cypress/base:24.11.0
     steps:
       - attach_workspace:
           at: ~/
       - run:
           command: npm run test
       - store_artifacts:
           path: coverage
-      - run:
-          name: Verify Code Coverage
-          command: npm run coverage:verify
 
 workflows:
   build:
@@ -132,24 +151,25 @@ workflows:
       - lint:
           requires:
             - install_and_persist
-
-      - test-code-coverage-plugin:
+      - unit-test:
           requires:
             - install_and_persist
-
-      - cyrun:
-          name: test-<< matrix.jobname>>
+      - build-dist:
           requires:
-            - install_and_persist
+            - lint
+            - unit-test
+      - verify-test-apps:
+          requires:
+            - build-dist
           matrix:
             parameters:
-              jobname:
+              app:
                 - all-files
                 - backend
                 - batch-send-coverage
                 - before-all-visit
                 - before-each-visit
-                - cra-e2e-and-ct
+                - esm-example
                 - exclude-files
                 - frontend
                 - fullstack
@@ -161,7 +181,9 @@ workflows:
                 - unit-tests-js
                 - use-webpack
                 - redirect
-      - windows_test
+      - windows_test:
+          requires:
+            - build-dist
       - publish:
           context: org-npm-credentials
           filters:
@@ -172,23 +194,5 @@ workflows:
                 - next
                 - dev
           requires:
-            - lint
-            - test-code-coverage-plugin
-            - test-all-files
-            - test-backend
-            - test-batch-send-coverage
-            - test-before-all-visit
-            - test-before-each-visit
-            - test-cra-e2e-and-ct
-            - test-exclude-files
-            - test-frontend
-            - test-fullstack
-            - test-multiple-backends
-            - test-one-spec
-            - test-same-folder
-            - test-support-files
-            - test-ts-example
-            - test-unit-tests-js
-            - test-use-webpack
-            - test-redirect
+            - verify-test-apps
             - windows_test

.gitignore

@@ -9,3 +9,4 @@ dist/
 cypress-coverage/
 yarn.lock
 .parcel-cache
+test-apps/*/package-lock.json

README.md

@@ -30,7 +30,7 @@ module.exports = defineConfig({
       // include any other plugin code...
 
       // It's IMPORTANT to return the config object
-      // with any changed environment variables
+      // with any changes
       return config
     },
   },
@@ -145,21 +145,6 @@ The code coverage from spec files will be combined with end-to-end coverage.
 
 Find examples of just the unit tests and JavaScript source files with collected code coverage in [test-apps/unit-tests-js](./test-apps/unit-tests-js).
 
-### Alternative for unit tests
-
-If you cannot use `.babelrc` (maybe it is used by other tools?), try using the Browserify transformer included with this module in the `use-browserify-istanbul` file.
-
-```js
-module.exports = (on, config) => {
-  require('@cypress/code-coverage/task')(on, config)
-  on(
-    'file:preprocessor',
-    require('@cypress/code-coverage/use-browserify-istanbul')
-  )
-  return config
-}
-```
-
 ## Instrument backend code
 
 Example in [test-apps/backend](test-apps/backend) folder.
@@ -202,11 +187,11 @@ if (global.__coverage__) {
 }
 ```
 
-3. Save the API coverage endpoint in the `cypress.json` file to let the plugin know where to call to receive the code coverage data from the server. Place it in `env.codeCoverage` object:
+3. Save the API coverage endpoint in the `cypress.json` file to let the plugin know where to call to receive the code coverage data from the server. Place it in `expose.codeCoverage` object:
 
 ```json
 {
-  "env": {
+  "expose": {
     "codeCoverage": {
       "url": "http://localhost:3000/__coverage__"
     }
@@ -218,7 +203,7 @@ Or if you have multiple servers from which you are wanting to gather code covera
 
 ```json
 {
-  "env": {
+  "expose": {
     "codeCoverage": {
       "url": ["http://localhost:3000/__coverage__", "http://localhost:3001/__coverage__"]
     }
@@ -240,7 +225,7 @@ After:
 
 ```json
 {
-  "env": {
+  "expose": {
     "codeCoverage": {
       "url": "http://localhost:3003/__coverage__",
       "expectBackendCoverageOnly": true
@@ -257,7 +242,7 @@ If there is ONLY frontend code coverage, set `expectFrontendCoverageOnly: true`
 
 ```json
 {
-  "env": {
+  "expose": {
     "codeCoverage": {
       "url": "http://localhost:3003/__coverage__",
       "expectFrontendCoverageOnly": true
@@ -369,11 +354,11 @@ switch (foo) {
 
 ### Exclude files and folders
 
-The code coverage plugin will automatically exclude any test/spec files you have defined in the `testFiles` (Cypress < v10) or `specPattern` (Cypress >= v10) configuration options. Additionally, you can set the `exclude` pattern glob in the code coverage environment variable to specify additional files to be excluded:
+The code coverage plugin will automatically exclude any test/spec files you have defined in the `testFiles` (Cypress < v10) or `specPattern` (Cypress >= v10) configuration options. Additionally, you can set the `exclude` pattern glob in the code coverage configuration key to specify additional files to be excluded:
 
 ```javascript
 // cypress.config.js or cypress.json
-env: {
+expose: {
   codeCoverage: {
     exclude: ['cypress/**/*.*'],
   },
@@ -401,20 +386,18 @@ Another important option is `excludeAfterRemap`. By default, it is false, which
 
 ## Disable plugin
 
-You can skip the client-side code coverage hooks by setting the environment variable `coverage` to `false`.
+You can skip the client-side code coverage hooks by setting the exposed `coverage` value to `false`.
 
 ```shell
-# tell Cypress to set environment variable "coverage" to false
-cypress run --env coverage=false
-# or pass the environment variable
-CYPRESS_COVERAGE=false cypress run
+# tell Cypress to set the exposed variable "coverage" to false
+cypress run --expose coverage=false
 ```
 
 Or set it to `false` in the `cypress.json` file.
 
 ```json
 {
-  "env": {
+  "expose": {
     "coverage": false
   }
 }
@@ -449,6 +432,7 @@ Full examples we use for testing in this repository:
 - [test-apps/before-each-visit](test-apps/before-each-visit) checks if code coverage correctly keeps track of code when doing `cy.visit` before each test
 - [test-apps/one-spec](test-apps/one-spec) confirms that coverage is collected and filtered correctly if the user only executes a single Cypress test
 - [test-apps/ts-example](test-apps/ts-example) uses Babel + Parcel to instrument and serve TypeScript file
+- [test-apps/esm-example](test-apps/esm-example) demonstrates using ES module syntax (`import`/`export`) with the plugin
 - [test-apps/use-webpack](test-apps/use-webpack) shows Webpack build with source maps and Babel
 - [test-apps/unit-tests-js](test-apps/unit-tests-js) runs just the unit tests and reports code coverage (JavaScript source code)
 - [test-apps/unit-tests-ts](test-apps/ts-example) runs just the unit tests and reports code coverage (TypeScript source code)
@@ -479,6 +463,40 @@ Look up the list of examples under the GitHub topic [cypress-code-coverage-examp
 
 ## Migrations
 
+### `@cypress/code-coverage` 3.x to 4.x
+
+`Cypress.env()` was deprecated in Cypress v15.10.0, and will be removed in Cypress 16. This necessitates a breaking change to how you configure `@cypress/code-coverage`.
+
+```js
+// BEFORE
+// Configure in the `env` key in your Cypress config:
+const { defineConfig } = require('cypress')
+
+module.exports = defineConfig({
+  env: {
+    codeCoverage: {
+      url: 'http://localhost:1234/__coverage__',
+      exclude: 'cypress/**/*.*'
+    }
+  }
+})
+```
+
+```js
+// AFTER
+// Configure in the `expose` key in your Cypress config:
+const { defineConfig } = require('cypress')
+
+module.exports = defineConfig({
+  expose: {
+    codeCoverage: {
+      url: 'http://localhost:1234/__coverage__',
+      exclude: 'cypress/**/*.*'
+    }
+  }
+})
+```
+
 ### Cypress v9 to v10
 
 With the removal of the `plugins` directory in Cypress version 10+, you'll need to add all of your configuration into the configuration file (`cypress.config.js` by default).
@@ -493,7 +511,7 @@ module.exports = (on, config) => {
   // add other tasks to be registered here
 
   // IMPORTANT to return the config object
-  // with the any changed environment variables
+  // with the any changes
   return config
 }
 ```
@@ -512,7 +530,7 @@ module.exports = defineConfig({
       // include any other plugin code...
 
       // It's IMPORTANT to return the config object
-      // with any changed environment variables
+      // with any changes
       return config
     },
   },
@@ -532,7 +550,7 @@ module.exports = (on, config) => {
 module.exports = (on, config) => {
   require('@cypress/code-coverage/task')(on, config)
   // IMPORTANT to return the config object
-  // with the any changed environment variables
+  // with the any changes
   return config
 }
 ```
@@ -575,8 +593,7 @@ If you decide to open an issue in this repository, please fill in all informatio
 ### Coverage reporting timeouts
 
 If the plugin times out when sending coverage report data to be merged, this may be due to a very large
-report being sent across processes. You can batch the report by setting the `sendCoverageBatchSize` environment
-variable in your `cypress.config.js` file's 'env' section. Assign the variable an integer value representing
+report being sent across processes. You can batch the report by setting the `sendCoverageBatchSize` value in your `cypress.config.js` file's `expose` section. Assign the variable an integer value representing
 the number of report keys to send per batch.
 
 ## Contributing

cypress-backend.json

@@ -1,7 +1,7 @@
 {
   "baseUrl": "http://localhost:3003",
   "integrationFolder": "cypress/test-backend",
-  "env": {
+  "expose": {
     "codeCoverage": {
       "url": "http://localhost:3003/__coverage__"
     }