diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index fb685d7d..e526d063 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -7,28 +7,28 @@ assignees: '' --- **Logs and screenshots** -Please provide debug logs by running Cypress from the terminal with `DEBUG=code-coverage` environment variable set, see the [Debugging](https://github.com/cypress-io/code-coverage#debugging) section of the README file. +Please provide debug logs by running Cypress from the terminal with `DEBUG=code-coverage` environment variable set. See the [Debugging](https://github.com/cypress-io/code-coverage#debugging) section of the README file. **Versions** -- What is this plugin's version? If this is NOT the latest [released version](https://github.com/cypress-io/code-coverage/releases) can you try the latest version, please? -- If the plugin worked before in version X, but stopped after upgrading to version Y, please try the [released versions](https://github.com/cypress-io/code-coverage/releases) between X and Y to see where the breaking change was. -- What is Cypress version? +- What is this plugin's version? If this is NOT the latest [released version](https://github.com/cypress-io/code-coverage/releases), can you try the latest version, please? +- If the plugin worked before in version X but stopped after upgrading to version Y, please try the [released versions](https://github.com/cypress-io/code-coverage/releases) between X and Y to see where the breaking change was. +- What is the Cypress version? - What is your operating system? - What is the shell? - What is the Node version? - What is the NPM version? -- How do you instrument your application? Cypress [does not instrument web application code](https://github.com/cypress-io/code-coverage#instrument-your-application), so you need to do it yourself. -- When running tests, if you open the web application in regular browser, and open DevTools, do you see `window.__coverage__` object? Can you paste a screenshot? -- Is there `.nyc_output` folder? Is there `.nyc_output/out.json` file. Is it empty? Can you paste at least part of it so we can see the keys and file paths? -- Do you have any custom NYC settings in `package.json` (`nyc` object) or in other [NYC config files](https://github.com/istanbuljs/nyc#configuration-files) +- How do you instrument your application? Cypress [does not instrument web application code](https://github.com/cypress-io/code-coverage#instrument-your-application), so you must do it yourself. +- When running tests, if you open the web application in a regular browser and open DevTools, do you see `window.__coverage__` object? Can you paste a screenshot? +- Is there a `.nyc_output` folder? Is there a `.nyc_output/out.json` file? Is it empty? Can you paste at least part of it so we can see the keys and file paths? +- Do you have any custom NYC settings in `package.json` (`nyc` object) or in other [NYC config files](https://github.com/istanbuljs/nyc#configuration-files)? - Do you run Cypress tests in a Docker container? **Describe the bug** A clear and concise description of what the bug is. **Link to the repo** -Bugs with a reproducible example, like an open source repo showing the bug, are the most likely to be resolved. +Bugs with a reproducible example, like an open-source repo showing the bug, are the most likely to be resolved. **Example** See [#217](https://github.com/cypress-io/code-coverage/issues/217) that is an excellent bug report example diff --git a/README.md b/README.md index 5bac7653..8eae2f3a 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,15 @@ npm install -D @cypress/code-coverage ``` -Note: this plugin assumes `cypress` is a peer dependency already installed in your project. +**Note:** This plugin assumes that `cypress` is a peer dependency already installed in your project. -Add to your `cypress/support/index.js` file +Add to your `cypress/support/index.js` file. ```js import '@cypress/code-coverage/support' ``` -Register tasks in your `cypress/plugins/index.js` file +Register tasks in your `cypress/plugins/index.js` file. ```js module.exports = (on, config) => { @@ -32,17 +32,17 @@ module.exports = (on, config) => { ## Instrument your application -This plugin **DOES NOT** instrument your code. You have to instrument it yourself using [Istanbul.js](https://istanbul.js.org/) tool. Luckily it is not difficult. For example, if you are already using Babel to transpile you can add [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul) to your `.babelrc` and instrument on the fly. +This plugin **DOES NOT** instrument your code. You have to instrument it yourself using the [Istanbul.js](https://istanbul.js.org/) tool. Luckily, it is not difficult. For example, if you are already using Babel to transpile, you can add [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul) to your `.babelrc` and instrument on the fly. -``` +```json { "plugins": ["istanbul"] } ``` -Please see the [Test Apps](#internal-test-apps) section down below, you can probably find a linked project matching your situation to see how to instrument your application's source code before running end-to-end tests to get the code coverage. +Please see the [Test Apps](#internal-test-apps) section below. You can find a linked project matching your situation to see how to instrument your application's source code before running end-to-end tests to get the code coverage. -If your application has been instrumented correctly, then you should see additional counters and instructions in the application's JavaScript resources, like the image down below shows. +If your application has been instrumented correctly, you should see additional counters and instructions in the application's JavaScript resources, as the image below shows. ![Instrumented code](images/instrumented-code.png) @@ -50,11 +50,11 @@ You should see the `window.__coverage__` object in the "Application under test i ![Window coverage object](images/window-coverage-object.png) -If you have instrumented your application's code and see the `window.__coverage__` object, then this plugin will save the coverage into `.nyc_output` folder and will generate reports after the tests finish (even in the interactive mode). Find the LCOV and HTML report in the `coverage/lcov-report` folder. +If you have instrumented your application's code and see the `window.__coverage__` object, then this plugin will save the coverage into the `.nyc_output` folder and will generate reports after the tests finish (even in the interactive mode). Find the LCOV and HTML report in the `coverage/lcov-report` folder. ![Coverage report](images/coverage.jpg) -That should be it! You should see messages from this plugin in the Cypress Command Log +That should be it! You should see messages from this plugin in the Cypress Command Log. ![Plugin messages](images/gui.png) @@ -66,13 +66,13 @@ That should be it! You should see messages from this plugin in the Cypress Comma ### App vs unit tests -You need to instrument your web application. This means that when the test does `cy.visit('localhost:3000')` any code the `index.html` requests should be instrumented by YOU. See [Test Apps](#test-apps) section for advice, usually you need to stick `babel-plugin-istanbul` into your pipeline somewhere. +You need to instrument your web application. This means that when the test does `cy.visit('localhost:3000')` any code, the `index.html` requests should be instrumented by YOU. See the [Test Apps](#internal-test-apps) section for advice. Usually, you need to stick `babel-plugin-istanbul` into your pipeline somewhere. If you are testing individual functions from your application code by importing them directly into Cypress spec files, this is called "unit tests" and Cypress can instrument this scenario for you. See [Instrument unit tests](#instrument-unit-tests) section. ## Reports -The `coverage` folder has results in several formats, and the coverage raw data is stored in `.nyc_output` folder. You can see the coverage numbers yourself. This plugin has `nyc` as a dependency, so it should be available right away. Here are common examples: +The `coverage` folder has results in several formats, and the coverage raw data is stored in the `.nyc_output` folder. You can see the coverage numbers yourself. This plugin has `nyc` as a dependency, so it should be available right away. Here are common examples: ```shell # see just the coverage summary @@ -83,7 +83,7 @@ $ npx nyc report --reporter=text $ npx nyc report --reporter=lcov ``` -It is useful to enforce [minimum coverage](https://github.com/istanbuljs/nyc#common-configuration-options) numbers. For example: +It is helpful to enforce [minimum coverage](https://github.com/istanbuljs/nyc#common-configuration-options) numbers. For example: ```shell $ npx nyc report --check-coverage --lines 80 @@ -104,27 +104,27 @@ All files | 100 | 100 | 100 | 100 | ERROR: Coverage for lines (100%) does not meet global threshold (101%) ``` -Watch video [How to read code coverage report](https://youtu.be/yVvCYtsmkZU) to see how to read the HTML coverage report. +Watch the video [How to read code coverage report](https://youtu.be/yVvCYtsmkZU) to see how to read the HTML coverage report. ## Instrument unit tests -If you test your application code directly from `specs` you might want to instrument them and combine unit test code coverage with any end-to-end code coverage (from iframe). You can easily instrument spec files using [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul) for example. +If you test your application code directly from `specs`, you might want to instrument them and combine unit test code coverage with any end-to-end code coverage (from iframe). You can easily instrument spec files using [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul), for example. Install the plugin -``` +```shell npm i -D babel-plugin-istanbul ``` -Set your `.babelrc` file +Set your `.babelrc` file. -```rc +```json { "plugins": ["istanbul"] } ``` -Put the following in `cypress/plugins/index.js` file to use `.babelrc` file +Put the following in the `cypress/plugins/index.js` file to use the `.babelrc` file. ```js module.exports = (on, config) => { @@ -134,13 +134,13 @@ module.exports = (on, config) => { } ``` -Now the code coverage from spec files will be combined with end-to-end coverage. +The code coverage from spec files will be combined with end-to-end coverage. -Find example of a just the unit tests and JavaScript source files with collected code coverage in [test-apps/new-cypress-config/unit-tests-js](./test-apps/new-cypress-config/unit-tests-js). +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` for some reason (maybe it is used by other tools?), try using the Browserify transformer included with this module in `use-browserify-istanbul` file. +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) => { @@ -155,12 +155,12 @@ module.exports = (on, config) => { ## Instrument backend code -Example in [test-apps/new-cypress-config/backend](test-apps/backend) folder. +Example in [test-apps/backend](test-apps/backend) folder. -You can also instrument your server-side code and produce combined coverage report that covers both the backend and frontend code +You can also instrument your server-side code and produce a combined coverage report that covers both the backend and frontend code. -1. Run the server code with instrumentation. The simplest way is to use [nyc](https://github.com/istanbuljs/nyc). If normally you run `node src/server` then to run instrumented version you can do `nyc --silent node src/server`. -2. Add an endpoint that returns collected coverage. If you are using Express, you can simply do +1. Run the server code with instrumentation. The simplest way is to use [nyc](https://github.com/istanbuljs/nyc). If normally you run `node src/server`, then to run the instrumented version, you can do `nyc --silent node src/server`. +2. Add an endpoint that returns collected coverage. If you are using Express, you can do ```js const express = require('express') @@ -168,7 +168,7 @@ const app = express() require('@cypress/code-coverage/middleware/express')(app) ``` -**Tip:** you can register the endpoint only if there is global code coverage object, and you can exclude the middleware code from the coverage numbers +**Tip:** You can register the endpoint only if there is a global code coverage object, and you can exclude the middleware code from the coverage numbers ```js // https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md @@ -178,7 +178,7 @@ if (global.__coverage__) { } ``` -If you use Hapi server, define the endpoint yourself and return the object +If you use a Hapi server, define the endpoint yourself and return the object. ```js if (global.__coverage__) { @@ -195,7 +195,7 @@ if (global.__coverage__) { } ``` -3. Save the API coverage endpoint in `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 `env.codeCoverage` object: ```json { @@ -211,7 +211,7 @@ That should be enough - the code coverage from the server will be requested at t ### expectBackendCoverageOnly -If there is NO frontend code coverage, and you want to only collect the backend code coverage using Cypress tests, set `expectBackendCoverageOnly: true` in `cypress.json` file. Otherwise Cypress complains that it cannot find the frontend code coverage. +If there is NO frontend code coverage, and you only want to collect backend code coverage using Cypress tests, set `expectBackendCoverageOnly: true` in the `cypress.json` file. Otherwise, Cypress complains that it cannot find the frontend code coverage. Default: @@ -234,7 +234,7 @@ After: ## Custom report folder -You can specify custom report folder by adding `nyc` object to the `package.json` file. For example to save reports to `cypress-coverage` folder, use: +You can specify a custom report folder by adding `nyc` object to the `package.json` file. For example, to save reports to `cypress-coverage` folder, use: ```json { @@ -246,7 +246,7 @@ You can specify custom report folder by adding `nyc` object to the `package.json ## Custom reporters -You can specify custom coverage reporter(s) to use. For example to output text summary and save JSON report in `cypress-coverage` folder set in your `package.json` folder: +You can specify custom coverage reporter(s) to use. For example, to output text summary and save JSON report in the `cypress-coverage` folder set in your `package.json` folder: ```json { @@ -261,7 +261,7 @@ You can specify custom coverage reporter(s) to use. For example to output text s ## Custom NYC command -Sometimes NYC tool might be installed in a different folder not in the current or parent folder, or you might want to customize the report command. In that case, put the custom command into `package.json` in the current folder and this plugin will automatically use it. +Sometimes, the NYC tool might be installed in a different folder, not the current or parent folder, or you might want to customize the report command. In that case, put the custom command into `package.json` in the current folder, and this plugin will automatically use it. ```json { @@ -273,15 +273,15 @@ Sometimes NYC tool might be installed in a different folder not in the current o ## TypeScript users -TypeScript source files should be automatically included in the report, if they are instrumented. +TypeScript source files should be automatically included in the report if they are instrumented. -See [test-apps/new-cypress-config/ts-example](test-apps/ts-example), [bahmutov/cra-ts-code-coverage-example](https://github.com/bahmutov/cra-ts-code-coverage-example) or [bahmutov/cypress-angular-coverage-example](https://github.com/bahmutov/cypress-angular-coverage-example). +See [test-apps/ts-example](test-apps/ts-example), [bahmutov/cra-ts-code-coverage-example](https://github.com/bahmutov/cra-ts-code-coverage-example) or [bahmutov/cypress-angular-coverage-example](https://github.com/bahmutov/cypress-angular-coverage-example). ## Include code -By default, the code coverage report includes _only_ the instrumented files loaded by the application during the tests. If some modules are loaded dynamically, or are loaded by the pages NOT visited during any tests, these files are not going to be in the report - because the plugin does not know about them. You can include all expected source files in the report by using `include` list in the `package.json` file. The files without counters will have 0 percent code coverage. +By default, the code coverage report includes _only_ the instrumented files loaded by the application during the tests. If some modules are loaded dynamically or by the pages NOT visited during any tests, these files will not be in the report - because the plugin does not know about them. You can include all expected source files in the report using the `include` list in the `package.json` file. The files without counters will have 0 percent code coverage. -For example, if you want to make sure the final report includes all JS files from the "src/pages" folder, set the "nyc" object in your `package.json` file. +For example, to ensure the final report includes all JS files from the "src/pages" folder, set the "nyc" object in your `package.json` file. ```json { @@ -292,15 +292,15 @@ For example, if you want to make sure the final report includes all JS files fro } ``` -See example [test-app/all-files](./test-apps/new-cypress-config/all-files) +See example [test-app/all-files](./test-apps/all-files) ## Exclude code You can exclude parts of the code or entire files from the code coverage report. See [Istanbul guide](https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md). Common cases: -### Exclude "else" branch +### Exclude the "else" branch -When running code only during Cypress tests, the "else" branch will never be hit. Thus we should exclude it from the branch coverage computation: +The "else" branch will never be hit when running code only during Cypress tests. Thus, we should exclude it from the branch coverage computation: ```js // expose "store" reference during tests @@ -310,9 +310,9 @@ if (window.Cypress) { } ``` -### Exclude next logical statement +### Exclude the next logical statement -Often needed to skip a statement +Often needed to skip a statement. ```js /* istanbul ignore next */ @@ -335,7 +335,7 @@ switch (foo) { ### Exclude files and folders -The code coverage plugin will automatically exclude any test/spec files you have defined in `testFiles` (Cypress < v10) or `specPattern` (Cypress >= v10) configuration options. Additionaly, 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 environment variable to specify additional files to be excluded: ```javascript // cypress.config.js or cypress.json @@ -346,11 +346,11 @@ env: { }, ``` -Cypress 10 and later users should set the `exclude` option to exclude any items from the `cypress` folder they don't want to be included in the coverage reports. +Cypress 10 and later users should set the `exclude` option to exclude any items from the `cypress` folder they don't want included in the coverage reports. -Additionaly, you can use [`nyc` configuration](https://github.com/istanbuljs/nyc#common-configuration-options) and [include and exclude options](https://github.com/istanbuljs/nyc#using-include-and-exclude-arrays). You can include and exclude files using `minimatch` patterns in `.nycrc` file or using "nyc" object inside your `package.json` file. +Additionally, you can use [`nyc` configuration](https://github.com/istanbuljs/nyc#common-configuration-options) and [include and exclude options](https://github.com/istanbuljs/nyc#using-include-and-exclude-arrays). You can include and exclude files using `minimatch` patterns in the `.nycrc` file or the "nyc" object inside your `package.json` file. -For example, if you want to only include files in the `app` folder, but exclude `app/util.js` file, you can set in your `package.json` +For example, if you want only to include files in the `app` folder but exclude the `app/util.js` file, you can set it in your `package.json`. ```json { @@ -361,9 +361,9 @@ For example, if you want to only include files in the `app` folder, but exclude } ``` -**Note:** if you have `all: true` NYC option set, this plugin will check the produced `.nyc_output/out.json` before generating the final report. If the `out.json` file does not have information for some files that should be there according to `include` list, then an empty placeholder will be included, see [PR 208](https://github.com/cypress-io/code-coverage/pull/208). +**Note:** If you have the `all: true` NYC option set, this plugin will check the produced `.nyc_output/out.json` before generating the final report. If the `out.json` file does not have information for some files that should be there according to the `include` list, then an empty placeholder will be included. See [PR 208](https://github.com/cypress-io/code-coverage/pull/208). -Another important option is `excludeAfterRemap`. By default it is false, which might let excluded files through. If you are excluding the files, and the instrumenter does not respect the `nyc.exclude` setting, then add `excludeAfterRemap: true` to tell `nyc report` to exclude files. See [test-apps/exclude-files](test-apps/new-cypress-config/exclude-files). +Another important option is `excludeAfterRemap`. By default, it is false, which might let excluded files through. If you exclude the files, and the instrumenter does not respect the `nyc.exclude` setting, then add `excludeAfterRemap: true` to tell `nyc report` to exclude files. See [test-apps/exclude-files](test-apps/exclude-files). ## Disable plugin @@ -376,7 +376,7 @@ cypress run --env coverage=false CYPRESS_COVERAGE=false cypress run ``` -or set it to `false` in the `cypress.json` file +Or set it to `false` in the `cypress.json` file. ```json { @@ -409,40 +409,40 @@ npm run dev:no:coverage Full examples we use for testing in this repository: -- [test-apps/backend](test-apps/new-cypress-config/backend) only instruments the backend Node server and saves the coverage report -- [test-apps/fullstack](test-apps/new-cypress-config/fullstack) instruments and merges backend, e2e and unit test coverage into a single report -- [test-apps/before-all-visit](test-apps/new-cypress-config/before-all-visit) checks if code coverage works when `cy.visit` is made once in the `before` hook -- [test-apps/before-each-visit](test-apps/new-cypress-config/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/new-cypress-config/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/new-cypress-config/ts-example) uses Babel + Parcel to instrument and serve TypeScript file -- [test-apps/use-webpack](test-apps/new-cypress-config/use-webpack) shows Webpack build with source maps and Babel -- [test-apps/unit-tests-js](test-apps/new-cypress-config/unit-tests-js) runs just the unit tests and reports code coverage (JavaScript source code) -- [test-apps/unit-tests-ts](test-apps/new-cypress-config/unit-tests-ts) **NOT WORKING** runs just the unit tests and reports code coverage (TypeScript source code) +- [test-apps/backend](test-apps/backend) only instruments the backend Node server and saves the coverage report +- [test-apps/fullstack](test-apps/fullstack) instruments and merges backend, e2e and unit test coverage into a single report +- [test-apps/before-all-visit](test-apps/before-all-visit) checks if code coverage works when `cy.visit` is made once in the `before` hook +- [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/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) ### External examples -Look up the list of examples under GitHub topic [cypress-code-coverage-example](https://github.com/topics/cypress-code-coverage-example) +Look up the list of examples under the GitHub topic [cypress-code-coverage-example](https://github.com/topics/cypress-code-coverage-example) -- [cypress-io/cypress-realworld-app](https://github.com/cypress-io/cypress-realworld-app) is an easy to setup and run real-world application with E2E, API, and unit tests that achieves 100% code-coverage for both front and back end code. Its CI pipeline also reports code-coverage reports across parallelized test runs to [Codecov](https://codecov.io/gh/cypress-io/cypress-realworld-app). +- [cypress-io/cypress-realworld-app](https://github.com/cypress-io/cypress-realworld-app) is an easy to set up and run a real-world application with E2E, API, and unit tests that achieves 100% code-coverage for both front and back end code. Its CI pipeline also reports code-coverage reports across parallelized test runs to [Codecov](https://codecov.io/gh/cypress-io/cypress-realworld-app). - [cypress-io/cypress-example-todomvc-redux](https://github.com/cypress-io/cypress-example-todomvc-redux) is a React / Redux application with 100% code coverage. -- [cypress-io/cypress-example-conduit-app](https://github.com/cypress-io/cypress-example-conduit-app) shows how to collect the coverage information from both back and front end code and merge it into a single report. The E2E test step runs in parallel in several CI containers, each saving just partial test coverage information. Then a merge job runs taking artifacts and combining coverage into the final report to be sent to an exteral coverage as a service app. +- [cypress-io/cypress-example-conduit-app](https://github.com/cypress-io/cypress-example-conduit-app) shows how to collect the coverage information from both back and frontend code and merge it into a single report. The E2E test step runs parallel in several CI containers, each saving just partial test coverage information. Then, a merge job runs, taking artifacts and combining coverage into the final report to be sent to an external coverage as a service app. - [bahmutov/code-coverage-webpack-dev-server](https://github.com/bahmutov/code-coverage-webpack-dev-server) shows how to collect code coverage from an application that uses webpack-dev-server. - [bahmutov/code-coverage-vue-example](https://github.com/bahmutov/code-coverage-vue-example) collects code coverage for Vue.js single file components. - [lluia/cypress-typescript-coverage-example](https://github.com/lluia/cypress-typescript-coverage-example) shows coverage for React App that uses TypeScript. See discussion in issue [#19](https://github.com/cypress-io/code-coverage/issues/19). -- [bahmutov/cypress-and-jest](https://github.com/bahmutov/cypress-and-jest) shows how to run Jest unit tests and Cypress unit tests, collecting code coverage from both test runners, and then produce merged report. -- [rootstrap/react-redux-base](https://github.com/rootstrap/react-redux-base) shows an example with a realistic Webpack config. Instruments the source code using `babel-plugin-istanbul` during tests. +- [bahmutov/cypress-and-jest](https://github.com/bahmutov/cypress-and-jest) shows how to run Jest unit tests and Cypress unit tests, collecting code coverage from both test runners and then producing a merged report. - [bahmutov/cypress-angular-coverage-example](https://github.com/bahmutov/cypress-angular-coverage-example) forked from [skylock/cypress-angular-coverage-example](https://github.com/skylock/cypress-angular-coverage-example) shows Angular 8 + TypeScript application with instrumentation done using [istanbul-instrumenter-loader](https://github.com/webpack-contrib/istanbul-instrumenter-loader). - [bahmutov/testing-react](https://github.com/bahmutov/testing-react) shows how to get code coverage for a React application created using [CRA v3](https://github.com/facebook/create-react-app) without ejecting `react-scripts`. - [bahmutov/cra-ts-code-coverage-example](https://github.com/bahmutov/cra-ts-code-coverage-example) instruments TypeScript React application on the fly without ejecting `react-scripts` by using [@cypress/instrument-cra](https://github.com/cypress-io/instrument-cra). - [bahmutov/next-and-cypress-example](https://github.com/bahmutov/next-and-cypress-example) shows how to get backend and frontend coverage for a [Next.js](https://nextjs.org) project. Uses [middleware/nextjs.js](middleware/nextjs.js). -- [kylemh/next-ts-with-cypress-coverage](https://github.com/kylemh/next-ts-with-cypress-coverage) this example project contains Next.js with TypeScript, instrumented coverage reporting, @testing-library/react, and instructions on how to type custom commands. -- [akoidan/vue-webpack-typescript](https://github.com/akoidan/vue-webpack-typescript) Pure webpack config with vue + typescript with codecov reports. This setup uses babel-loader with TS checker as a separate thread. -- [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 +- [kylemh/next-ts-with-cypress-coverage](https://github.com/kylemh/next-ts-with-cypress-coverage) This example project contains Next.js with TypeScript, instrumented coverage reporting, @testing-library/react, and instructions on how to type custom commands. +- [akoidan/vue-webpack-typescript](https://github.com/akoidan/vue-webpack-typescript) Pure webpack config with vue + typescript with codecov reports. This setup uses a babel-loader with a TS checker as a separate thread. +- [bahmutov/code-coverage-subfolder-example](https://github.com/bahmutov/code-coverage-subfolder-example) shows how to instrument the `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. -- [bahmutov/app-in-docker-coverage-example](https://github.com/bahmutov/app-in-docker-coverage-example) shows an app running inside a Docker container, while Cypress runs on the local machine. Cypress can still [discover the source files](https://github.com/cypress-io/code-coverage/pull/197) before generating the report. +- [bahmutov/app-in-docker-coverage-example](https://github.com/bahmutov/app-in-docker-coverage-example) shows an app running inside a Docker container, while Cypress runs on the local machine. Before generating the report, Cypress can still [discover the source files](https://github.com/cypress-io/code-coverage/pull/197). - [bahmutov/gatsby-cypress-with-code-coverage](https://github.com/bahmutov/gatsby-cypress-with-code-coverage) shows code coverage using the official Gatsby "Hello World" starter. - [muratkeremozcan/angular-playground](https://github.com/muratkeremozcan/angular-playground) is an Angular TypeScript application with combined unit and E2E coverage. -- [nefayran/cypress-react-vite](https://github.com/nefayran/cypress-react-vite) React with Vite and istanbul plugin for code coverage. +- [nefayran/cypress-react-vite](https://github.com/nefayran/cypress-react-vite) React with Vite and Istanbul plugin for code coverage. + ## Migrations ### v2 to v3 @@ -463,7 +463,7 @@ module.exports = (on, config) => { } ``` -**Tip:** we include [plugins.js](plugins.js) file you can point at from your code in simple cases. From your `cypress.json` file: +**Tip:** We include [plugins.js](plugins.js) file you can point at from your code in simple cases. From your `cypress.json` file: ```json { @@ -472,37 +472,35 @@ module.exports = (on, config) => { } ``` -See [test-apps/use-plugins-and-support](test-apps/new-cypress-config/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: +This plugin uses the [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. To see these messages, run Cypress from the terminal with the environment variable `DEBUG=code-coverage`. Example using Unix syntax to set the variable: ```shell $ DEBUG=code-coverage npm run dev ... code-coverage reset code coverage in interactive mode +0ms code-coverage wrote coverage file /code-coverage/.nyc_output/out.json +28ms - code-coverage saving coverage report using command: "nyc report --report-dir ./coverage --reporter=lcov --reporter=clover --reporter=json" +3ms + code-coverage saving coverage report using the command: "nyc report --report-dir ./coverage --reporter=lcov --reporter=clover --reporter=json" +3ms ``` -Deeply nested object will sometimes have `[object Object]` values printed. You can print these nested objects by specifying a deeper depth by adding `DEBUG_DEPTH=` setting +Deeply nested objects will sometimes have `[object Object]` values printed. You can print these nested objects by specifying a deeper depth by adding `DEBUG_DEPTH=` setting. ```shell -$ DEBUG_DEPTH=10 DEBUG=code-coverage npm run dev +DEBUG_DEPTH=10 DEBUG=code-coverage npm run dev ``` ### Common issues Common issue: [not instrumenting your application when running Cypress](#instrument-your-application). -If the plugin worked before in version X, but stopped after upgrading to version Y, please try the [released versions](https://github.com/cypress-io/code-coverage/releases) between X and Y to see where the breaking change was. +If the plugin worked before in version X but stopped after upgrading to version Y, please try the [released versions](https://github.com/cypress-io/code-coverage/releases) between X and Y to see where the breaking change was. -If you decide to open an issue in this repository, please fill all information the [issue template](https://github.com/cypress-io/code-coverage/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) asks. The issues most likely to be resolved have debug logs, screenshots and hopefully public repository links so we can try running the tests ourselves. +If you decide to open an issue in this repository, please fill in all information the [issue template](https://github.com/cypress-io/code-coverage/blob/master/.github/ISSUE_TEMPLATE/bug_report.md) asks for. The issues most likely to be resolved have debug logs, screenshots, and hopefully public repository links so we can try running the tests ourselves. ## Contributing -You can test changes locally by running tests and confirming the code coverage has been calculated and saved. +You can test changes locally by running tests and confirming that the code coverage has been calculated and saved. ```shell npm run test:ci @@ -516,7 +514,7 @@ npx nyc report --check-coverage true --lines 100 --include cypress/unit.js ### Markdown -You can validate links in Markdown files in this directory by executing (Linux + Mac only) script +You can validate links in Markdown files in this directory by executing (Linux + Mac only) script. ```shell npm run check:markdown diff --git a/cypress/README.md b/cypress/README.md index 3d50c9e0..27d0eec9 100644 --- a/cypress/README.md +++ b/cypress/README.md @@ -7,16 +7,16 @@ These folders hold end-to-end tests and supporting files for the Cypress Test Runner. - [fixtures](fixtures) holds optional JSON data for mocking, [read more](https://on.cypress.io/fixture) -- [integration](integration) holds the actual test files, [read more](https://on.cypress.io/writing-and-organizing-tests) +- [e2e](e2e) holds the actual test files, [read more](https://on.cypress.io/writing-and-organizing-tests) - [plugins](plugins) allow you to customize how tests are loaded, [read more](https://on.cypress.io/plugins) - [support](support) file runs before all tests and is a great place to write or load additional custom commands, [read more](https://on.cypress.io/writing-and-organizing-tests#Support-file) -## `cypress.json` file +## `cypress.config.js` file -You can configure project options in the [../cypress.json](../cypress.json) file, see [Cypress configuration doc](https://on.cypress.io/configuration). +You can configure project options in the [../cypress.config.js](../cypress.config.js) file, see [Cypress configuration doc](https://on.cypress.io/configuration). ## More information -- [https://github.com/cypress.io/cypress](https://github.com/cypress.io/cypress) +- [https://github.com/cypress-io/cypress](https://github.com/cypress-io/cypress) - [https://docs.cypress.io/](https://docs.cypress.io/) - [Writing your first Cypress test](http://on.cypress.io/intro)