From bea4891d193fff4139a15887e7f6139acfb0bb97 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 18:08:26 +0000 Subject: [PATCH 1/6] docs: explain where NYC options are read from The plugin reads NYC options and the `coverage:report` script from `process.cwd()`, which Cypress sets to the folder holding the Cypress config file. The README only said "package.json" or ".nycrc", so users who pass `--config-file` in a monorepo put their options in the wrong folder and saw them silently ignored. Add a "Where NYC options are read from" section that lists the supported files, their merge order, and the folder they must live in, with a monorepo example. Link to it from the sections that mention package.json and .nycrc. Closes #947 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r2ZU5whUYbhTLy6nfa --- README.md | 42 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 888436c3..a5cbf6d5 100644 --- a/README.md +++ b/README.md @@ -293,9 +293,45 @@ If there is ONLY frontend code coverage, set `expectFrontendCoverageOnly: true` } ``` +## Where NYC options are read from + +The plugin reads [NYC options](https://github.com/istanbuljs/nyc#common-configuration-options) from the folder that holds your Cypress config file, because that's the working directory Cypress uses when it loads the config and runs `setupNodeEvents`. Most of the time that's your project root. But if you pass `--config-file cypress/cypress.config.ts`, the plugin looks in the `cypress` folder, not in the folder you started Cypress from. + +The plugin looks for these files in that folder only. It doesn't search parent folders: + +- `.nycrc` +- `.nycrc.json` +- `.nycrc.yaml` +- `.nycrc.yml` +- `nyc.config.js` +- `nyc.config.cjs` +- the `nyc` object in `package.json` + +Unlike the `nyc` CLI, which uses the first config file it finds, the plugin merges every file it finds. If two files set the same option, the one later in the list wins, so the `nyc` object in `package.json` overrides the rest. The [`coverage:report` script](#custom-nyc-command) is looked up in that same `package.json`. Relative paths such as `report-dir`, `temp-dir`, and the `include` and `exclude` globs are resolved against that folder as well. + +For example, in a monorepo where you run `cypress run --config-file cypress/cypress.config.ts` from `libs/foo`, put the options next to the Cypress config rather than in `libs/foo/package.json`: + +```text +libs/foo/ +├── package.json <- not read by the plugin +├── src/ +└── cypress/ + ├── cypress.config.ts + └── .nycrc.json <- read by the plugin +``` + +```json +{ + "include": ["../src/**/*.ts"], + "report-dir": "../coverage" +} +``` + +If you aren't sure which options the plugin picked up, run Cypress with `DEBUG=code-coverage` and look for the `combined NYC options` line. See [Debugging](#debugging). + ## Custom report folder -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: +You can specify a custom report folder by adding `nyc` object to the `package.json` file in the [same folder as your Cypress config file](#where-nyc-options-are-read-from). For example, to save reports to `cypress-coverage` folder, use: ```json { @@ -322,7 +358,7 @@ You can specify custom coverage reporter(s) to use. For example, to output text ## Custom NYC command -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. +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 [same folder as your Cypress config file](#where-nyc-options-are-read-from), and this plugin will automatically use it. ```json { @@ -409,7 +445,7 @@ expose: { 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. -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. +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. Whichever you use, put it in the [same folder as your Cypress config file](#where-nyc-options-are-read-from). 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`. From d20b6c1901d3b8034ecd444014b8310df2a2a5f9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 18:34:06 +0000 Subject: [PATCH 2/6] docs: show the ES module import form for the coverage task The Install section only showed `require('@cypress/code-coverage/task')`, so people with a `cypress.config.ts` or `"type": "module"` project weren't sure how to register the task. Add an `import` example and note that both forms work in either kind of config file. Also document that TypeScript's older `node10` module resolution can't find the plugin's types, because its entry points are only declared in `exports`, and name the `tsconfig.json` settings that fix it. Closes #715 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r2ZU5whUYbhTLy6nfa --- README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/README.md b/README.md index a5cbf6d5..2ab3c73e 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,25 @@ module.exports = defineConfig({ }) ``` +If your config file uses ES module syntax, such as a `cypress.config.ts` file or a project with `"type": "module"` in its `package.json`, you can import the task instead of calling `require`: + +```ts +// cypress.config.ts +import { defineConfig } from 'cypress' +import codeCoverageTask from '@cypress/code-coverage/task' + +export default defineConfig({ + e2e: { + setupNodeEvents(on, config) { + codeCoverageTask(on, config) + return config + }, + }, +}) +``` + +Both forms work in either kind of config file. If TypeScript reports `Cannot find module '@cypress/code-coverage/task'`, set `"moduleResolution"` to `"bundler"` in your `tsconfig.json`, or set both `"module"` and `"moduleResolution"` to `"node16"` or `"nodenext"`. The plugin's entry points are only declared in the `exports` field of its `package.json`, and older module resolution settings don't read it. + ## Instrument your application 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. From 0c90288665686a1abd66c4e63e0cd24a280a30ee Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 18:43:05 +0000 Subject: [PATCH 3/6] docs: explain why coverage can be empty in CI but not locally People who get coverage locally but an empty report in CI are almost always testing an uninstrumented production build. Add a "Coverage works locally but not in CI" entry to Common issues that quotes the warnings they'll see, explains how Babel env config and vite-plugin-istanbul skip production builds by default, and adds a spec that fails when `window.__coverage__` is missing. Also remove the "Cannot find coverage file" branch from coverageReport. saveCoverage writes out.json on the line before the check, so it could never run. The README entry mentions the old message for anyone searching for it. Closes #528 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r2ZU5whUYbhTLy6nfa --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ lib/task.ts | 7 +------ 2 files changed, 49 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 2ab3c73e..997bef17 100644 --- a/README.md +++ b/README.md @@ -687,6 +687,54 @@ If the plugin worked before in version X but stopped after upgrading to version 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. +### Coverage works locally but not in CI + +If you get a coverage report on your machine but an empty one in CI, the app that CI tests is almost always not instrumented. You'll see this in the Command Log: + +```text +⚠️ Could not find any coverage information in your application +``` + +And this in the terminal: + +```text +⚠️ file .nyc_output/out.json has no coverage information +``` + +Versions before 3.13.4 printed `Cannot find coverage file .nyc_output/out.json` instead. + +Locally you probably run a dev server, while CI often builds the app for production first. Many instrumentation setups only switch on in development. For example: + +- **Babel:** an `istanbul` plugin listed under `"env": { "development": ... }` or `"env": { "test": ... }` in your Babel config only runs when `BABEL_ENV` or `NODE_ENV` matches that name. Production builds usually set `NODE_ENV=production`. +- **`vite-plugin-istanbul`:** by default, it only instruments code served by `vite dev` and skips `vite build`. Set `forceBuildInstrument: true` to instrument builds too. Pair it with `requireEnv: true` so only builds with `VITE_COVERAGE=true` get instrumented, and your real production build stays clean: + + ```js + // vite.config.js + import { defineConfig } from 'vite' + import istanbul from 'vite-plugin-istanbul' + + export default defineConfig({ + plugins: [ + istanbul({ + requireEnv: true, + forceBuildInstrument: true + }) + ] + }) + ``` + + Then build with `VITE_COVERAGE=true vite build` in CI. + +To catch this early, add a test that fails when the page has no coverage object, and run it in CI: + +```js +// cypress/e2e/instrumentation.cy.js +it('loads an instrumented app', () => { + cy.visit('/') + cy.window().should('have.property', '__coverage__') +}) +``` + ### Coverage reporting timeouts If the plugin times out when sending coverage report data to be merged, this may be due to a very large diff --git a/lib/task.ts b/lib/task.ts index 12619a20..bce5aa7a 100644 --- a/lib/task.ts +++ b/lib/task.ts @@ -193,13 +193,8 @@ const tasks = { * Saves the coverage to the nyc output file and generates the report, * using the "coverage:report" script when package.json has one */ - coverageReport(): Promise | null { + coverageReport(): Promise { saveCoverage(coverageMap) - if (!existsSync(nycFilename)) { - console.warn('Cannot find coverage file %s', nycFilename) - console.warn('Skipping coverage report') - return null - } showNycInfo(nycFilename) From 7ecfa1ac1c0138f3ddf293c91395fd7bafc96a08 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 18:51:25 +0000 Subject: [PATCH 4/6] docs: add a component testing section and a Vite component test app The plugin already collects coverage from component tests, but the README never said how to set it up, so people kept missing the support import in `cypress/support/component.js` or the dev server instrumentation. Add a "Component testing" section covering the support import, registering the task in `component.setupNodeEvents`, and instrumenting the dev server with vite-plugin-istanbul or with babel-plugin-istanbul in a webpack config. Add test-apps/component-vite, a React component tested with `cypress run --component`, which checks for 100% coverage of the component. Add it to the CI matrix and to the README's list of test apps. Closes #596 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r2ZU5whUYbhTLy6nfa --- .github/workflows/ci.yml | 1 + README.md | 111 ++++++++++++++++++ test-apps/component-vite/README.md | 9 ++ test-apps/component-vite/cypress.config.js | 18 +++ .../cypress/support/component-index.html | 10 ++ .../cypress/support/component.js | 4 + test-apps/component-vite/package.json | 20 ++++ test-apps/component-vite/src/Counter.cy.jsx | 14 +++ test-apps/component-vite/src/Counter.jsx | 12 ++ test-apps/component-vite/vite.config.js | 23 ++++ 10 files changed, 222 insertions(+) create mode 100644 test-apps/component-vite/README.md create mode 100644 test-apps/component-vite/cypress.config.js create mode 100644 test-apps/component-vite/cypress/support/component-index.html create mode 100644 test-apps/component-vite/cypress/support/component.js create mode 100644 test-apps/component-vite/package.json create mode 100644 test-apps/component-vite/src/Counter.cy.jsx create mode 100644 test-apps/component-vite/src/Counter.jsx create mode 100644 test-apps/component-vite/vite.config.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ef33ae9b..9d56cb55 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -81,6 +81,7 @@ jobs: - batch-send-coverage - before-all-visit - before-each-visit + - component-vite - esm-example - exclude-files - frontend diff --git a/README.md b/README.md index 997bef17..b33875b7 100644 --- a/README.md +++ b/README.md @@ -174,6 +174,116 @@ If your NYC options set `check-coverage` but `expose.codeCoverage.checkCoverage` Watch the video [How to read code coverage report](https://youtu.be/yVvCYtsmkZU) to see how to read the HTML coverage report. +## Component testing + +The plugin collects coverage from component tests, too. The setup is the same as for end-to-end tests, but it goes in your component testing configuration: + +1. Import the support file in `cypress/support/component.js`: + + ```js + // cypress/support/component.js + import '@cypress/code-coverage/support' + ``` + +2. Register the task in `component.setupNodeEvents`: + + ```js + // cypress.config.js + const { defineConfig } = require('cypress') + + module.exports = defineConfig({ + component: { + devServer: { + framework: 'react', + bundler: 'vite' + }, + setupNodeEvents(on, config) { + require('@cypress/code-coverage/task')(on, config) + return config + } + } + }) + ``` + +3. Instrument the code your dev server serves. Cypress builds your components with the dev server you configure, so that's where Istanbul needs to run. + +For Vite, add [vite-plugin-istanbul](https://github.com/iFaxity/vite-plugin-istanbul) to your Vite config. It instruments code served by the dev server by default: + +```js +// vite.config.js +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' +import istanbul from 'vite-plugin-istanbul' + +export default defineConfig({ + plugins: [ + react(), + istanbul({ + include: 'src/*', + exclude: ['node_modules', 'cypress', '**/*.cy.jsx'], + extension: ['.js', '.jsx'] + }) + ] +}) +``` + +For webpack, add [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul) to the Babel loader in the `webpackConfig` you pass to the dev server: + +```js +// cypress.config.js +const { defineConfig } = require('cypress') + +module.exports = defineConfig({ + component: { + devServer: { + framework: 'react', + bundler: 'webpack', + webpackConfig: { + resolve: { extensions: ['.js', '.jsx'] }, + module: { + rules: [ + { + test: /\.jsx?$/, + exclude: /node_modules/, + use: { + loader: 'babel-loader', + options: { + presets: [['@babel/preset-react', { runtime: 'automatic' }]], + plugins: ['istanbul'] + } + } + } + ] + } + } + }, + setupNodeEvents(on, config) { + require('@cypress/code-coverage/task')(on, config) + return config + } + } +}) +``` + +`babel-plugin-istanbul` doesn't skip `.cy.jsx` spec files on its own, so exclude them in your [NYC options](#where-nyc-options-are-read-from), for example in `.nycrc.json`: + +```json +{ + "exclude": ["**/*.cy.jsx", "cypress/**"] +} +``` + +If instrumentation isn't working, the plugin logs "Could not find any coverage information in your application" after each test. To fail fast instead, check for the coverage object right after mounting: + +```js +it('mounts an instrumented component', () => { + cy.mount() + cy.window().should('have.property', '__coverage__') +}) +``` + +See [test-apps/component-vite](test-apps/component-vite) for a complete example. + ## 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. @@ -531,6 +641,7 @@ Full examples we use for testing in this repository: - [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/component-vite](test-apps/component-vite) collects coverage from React component tests served by Vite - [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) diff --git a/test-apps/component-vite/README.md b/test-apps/component-vite/README.md new file mode 100644 index 00000000..e180850e --- /dev/null +++ b/test-apps/component-vite/README.md @@ -0,0 +1,9 @@ +# component-vite + +> Collects code coverage from React component tests served by Vite + +[vite-plugin-istanbul](https://github.com/iFaxity/vite-plugin-istanbul) in [vite.config.js](vite.config.js) instruments [src/Counter.jsx](src/Counter.jsx) while Cypress serves it for component testing. [cypress/support/component.js](cypress/support/component.js) imports `@cypress/code-coverage/support`, and [cypress.config.js](cypress.config.js) registers the coverage task in `component.setupNodeEvents`. + +The tests in [src/Counter.cy.jsx](src/Counter.cy.jsx) cover every line of the component. + +**Note:** the `optimizeDeps` and `resolve.dedupe` settings in `vite.config.js` are only needed because this app loads Cypress and the plugin from the root of this repository. A project that installs them in its own `node_modules` doesn't need them. diff --git a/test-apps/component-vite/cypress.config.js b/test-apps/component-vite/cypress.config.js new file mode 100644 index 00000000..93c0705c --- /dev/null +++ b/test-apps/component-vite/cypress.config.js @@ -0,0 +1,18 @@ +import { defineConfig } from 'cypress' +import codeCoverageTask from '@cypress/code-coverage/task' + +export default defineConfig({ + allowCypressEnv: false, + fixturesFolder: false, + component: { + devServer: { + framework: 'react', + bundler: 'vite' + }, + specPattern: 'src/**/*.cy.jsx', + setupNodeEvents(on, config) { + codeCoverageTask(on, config) + return config + } + } +}) diff --git a/test-apps/component-vite/cypress/support/component-index.html b/test-apps/component-vite/cypress/support/component-index.html new file mode 100644 index 00000000..6b8dfe73 --- /dev/null +++ b/test-apps/component-vite/cypress/support/component-index.html @@ -0,0 +1,10 @@ + + + + + Components App + + +
+ + diff --git a/test-apps/component-vite/cypress/support/component.js b/test-apps/component-vite/cypress/support/component.js new file mode 100644 index 00000000..abc15b4e --- /dev/null +++ b/test-apps/component-vite/cypress/support/component.js @@ -0,0 +1,4 @@ +import '@cypress/code-coverage/support' +import { mount } from 'cypress/react' + +Cypress.Commands.add('mount', mount) diff --git a/test-apps/component-vite/package.json b/test-apps/component-vite/package.json new file mode 100644 index 00000000..1a477b41 --- /dev/null +++ b/test-apps/component-vite/package.json @@ -0,0 +1,20 @@ +{ + "name": "example-component-vite", + "description": "Code coverage from React component tests served by Vite", + "private": true, + "type": "module", + "scripts": { + "cy:run": "cypress run --component", + "pretest": "rimraf .nyc_output coverage", + "test": "npm run cy:run", + "coverage:verify": "npx nyc report --check-coverage true --lines 100", + "coverage:check-files": "check-coverage src/Counter.jsx && only-covered src/Counter.jsx" + }, + "devDependencies": { + "@vitejs/plugin-react": "^5.2.0", + "react": "^18.3.1", + "react-dom": "^18.3.1", + "vite": "^7.3.6", + "vite-plugin-istanbul": "^7.2.1" + } +} diff --git a/test-apps/component-vite/src/Counter.cy.jsx b/test-apps/component-vite/src/Counter.cy.jsx new file mode 100644 index 00000000..f57b674a --- /dev/null +++ b/test-apps/component-vite/src/Counter.cy.jsx @@ -0,0 +1,14 @@ +import { Counter } from './Counter' + +describe('Counter', () => { + it('starts at zero', () => { + cy.mount() + cy.contains('Zero') + }) + + it('increments', () => { + cy.mount() + cy.contains('button', 'Increment').click() + cy.contains('Count: 2') + }) +}) diff --git a/test-apps/component-vite/src/Counter.jsx b/test-apps/component-vite/src/Counter.jsx new file mode 100644 index 00000000..29e7847e --- /dev/null +++ b/test-apps/component-vite/src/Counter.jsx @@ -0,0 +1,12 @@ +import { useState } from 'react' + +export function Counter({ initial = 0 }) { + const [count, setCount] = useState(initial) + + return ( +
+

{count === 0 ? 'Zero' : `Count: ${count}`}

+ +
+ ) +} diff --git a/test-apps/component-vite/vite.config.js b/test-apps/component-vite/vite.config.js new file mode 100644 index 00000000..606db743 --- /dev/null +++ b/test-apps/component-vite/vite.config.js @@ -0,0 +1,23 @@ +import { defineConfig } from 'vite' +import react from '@vitejs/plugin-react' +import istanbul from 'vite-plugin-istanbul' + +export default defineConfig({ + plugins: [ + react(), + istanbul({ + include: 'src/*', + exclude: ['node_modules', 'cypress', '**/*.cy.jsx'], + extension: ['.js', '.jsx'] + }) + ], + // This app loads Cypress and the plugin from the repo root instead of its + // own node_modules. Vite only pre-bundles CommonJS packages it finds in + // node_modules, and `cypress/react` can't see this app's React from there. + optimizeDeps: { + include: ['@cypress/code-coverage/support'] + }, + resolve: { + dedupe: ['react', 'react-dom'] + } +}) From 5f2a264fb8b377ca86bf33c37e16366196b2c374 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 20:01:55 +0000 Subject: [PATCH 5/6] fix: collect coverage created after the page loads, and document SWC The plugin captured `window.__coverage__` only at `window:load` and at the start of each test. Apps that create the coverage object later, such as a Next.js app whose components run during hydration, ended up with an empty report. Re-read the window in `afterEach`, before sending coverage. Objects already captured are matched by identity, so they aren't sent twice. Add an "Instrument with SWC" section to the README. It explains that the plugin reads any Istanbul-format coverage, shows how to add swc-plugin-coverage-instrument through `.swcrc` or Next.js `experimental.swcPlugins`, and notes that the SWC plugin version must match the SWC version that loads it. Add test-apps/swc-webpack, which builds with swc-loader and loads the bundle after the page's `load` event. It reports 0% without the fix and 100% with it. Add it to the CI matrix and the README's list of test apps. Closes #583 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r2ZU5whUYbhTLy6nfa --- .github/workflows/ci.yml | 1 + .gitignore | 3 +- README.md | 37 +++++++ lib/support.ts | 110 ++++++++++--------- test-apps/swc-webpack/.swcrc | 10 ++ test-apps/swc-webpack/README.md | 7 ++ test-apps/swc-webpack/cypress.config.js | 13 +++ test-apps/swc-webpack/cypress/e2e/spec.cy.js | 4 + test-apps/swc-webpack/cypress/support/e2e.js | 1 + test-apps/swc-webpack/index.html | 15 +++ test-apps/swc-webpack/package.json | 19 ++++ test-apps/swc-webpack/src/calc.js | 1 + test-apps/swc-webpack/src/index.js | 3 + test-apps/swc-webpack/webpack.config.js | 20 ++++ 14 files changed, 191 insertions(+), 53 deletions(-) create mode 100644 test-apps/swc-webpack/.swcrc create mode 100644 test-apps/swc-webpack/README.md create mode 100644 test-apps/swc-webpack/cypress.config.js create mode 100644 test-apps/swc-webpack/cypress/e2e/spec.cy.js create mode 100644 test-apps/swc-webpack/cypress/support/e2e.js create mode 100644 test-apps/swc-webpack/index.html create mode 100644 test-apps/swc-webpack/package.json create mode 100644 test-apps/swc-webpack/src/calc.js create mode 100644 test-apps/swc-webpack/src/index.js create mode 100644 test-apps/swc-webpack/webpack.config.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9d56cb55..59c5f5c8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -90,6 +90,7 @@ jobs: - one-spec - same-folder - support-files + - swc-webpack - ts-example - unit-tests-js - use-webpack diff --git a/.gitignore b/.gitignore index 02b260c2..198060a9 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,5 @@ dist/ cypress-coverage/ yarn.lock .parcel-cache -test-apps/*/package-lock.json \ No newline at end of file +test-apps/*/package-lock.json +.swc/ diff --git a/README.md b/README.md index b33875b7..ad2e37f6 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,42 @@ That should be it! You should see messages from this plugin in the Cypress Comma ![Plugin messages](images/gui.png) +### Instrument with SWC + +The plugin doesn't depend on Babel. It reads whatever Istanbul-format coverage your code writes to `window.__coverage__`, so you can instrument with [SWC](https://swc.rs) instead by adding [swc-plugin-coverage-instrument](https://github.com/kwonoj/swc-coverage-instrument) to your SWC config. + +If you compile with `@swc/core` directly or through `swc-loader`, add the plugin to your `.swcrc`: + +```json +{ + "jsc": { + "experimental": { + "plugins": [["swc-plugin-coverage-instrument", {}]] + } + } +} +``` + +For Next.js, which compiles with SWC by default, add it to `experimental.swcPlugins` in `next.config.js`. Instrumented code is slower and larger, so turn it on only for the builds you test, for example with an environment variable: + +```js +// next.config.js +module.exports = { + experimental: { + swcPlugins: + process.env.INSTRUMENT_CODE === 'true' + ? [['swc-plugin-coverage-instrument', {}]] + : [] + } +} +``` + +Then build with `INSTRUMENT_CODE=true next build` before running Cypress. + +SWC plugins only load in the SWC version they were built for, and a mismatch makes the build fail when it loads the plugin. If that happens, try a different `swc-plugin-coverage-instrument` version that matches your `@swc/core`, or the SWC version bundled in your Next.js release. For example, `swc-plugin-coverage-instrument` 0.0.33 works with `@swc/core` 1.16.18 and with Next.js 16.4.3. + +See [test-apps/swc-webpack](test-apps/swc-webpack) for a complete example. + ### More information - Read [Cypress Code Coverage: Instrumenting code](https://on.cypress.io/code-coverage#Instrumenting-code) guide @@ -642,6 +678,7 @@ Full examples we use for testing in this repository: - [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/component-vite](test-apps/component-vite) collects coverage from React component tests served by Vite +- [test-apps/swc-webpack](test-apps/swc-webpack) instruments a webpack build with SWC instead of Babel, and loads it after the page's `load` event - [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) diff --git a/lib/support.ts b/lib/support.ts index 215d98dc..72202977 100644 --- a/lib/support.ts +++ b/lib/support.ts @@ -87,48 +87,48 @@ function registerHooks(): void { }) }) - beforeEach(() => { - windowCoverageObjects = [] - - const saveCoverageObject = (win: Window): void => { - let applicationSourceCoverage: unknown - try { - // Note that we are purposefully not supporting the optional chaining syntax here to - // support a wide range of projects (some of which are not set up to support the optional - // chaining syntax due to current Cypress limitations). See: - // https://github.com/cypress-io/cypress/issues/20753 - if (win) { - // @ts-ignore - __coverage__ is added by instrumentation - applicationSourceCoverage = ( - win as typeof win & { __coverage__?: unknown } - ).__coverage__ - } - } catch { - // Reading __coverage__ from a cross-origin window throws, and we don't - // collect coverage for code we don't control - } - - if (!applicationSourceCoverage) { - return + const saveCoverageObject = (win: Window): void => { + let applicationSourceCoverage: unknown + try { + // Note that we are purposefully not supporting the optional chaining syntax here to + // support a wide range of projects (some of which are not set up to support the optional + // chaining syntax due to current Cypress limitations). See: + // https://github.com/cypress-io/cypress/issues/20753 + if (win) { + // @ts-ignore - __coverage__ is added by instrumentation + applicationSourceCoverage = ( + win as typeof win & { __coverage__?: unknown } + ).__coverage__ } + } catch { + // Reading __coverage__ from a cross-origin window throws, and we don't + // collect coverage for code we don't control + } - const existingCoverage = Cypress._.find(windowCoverageObjects, { - coverage: applicationSourceCoverage - }) - if (existingCoverage) { - // Both `window:load` and `cy.window()` can report the same window, and - // navigating away and back creates a new object for the same page. The - // old object stops updating, so keep the latest one. - existingCoverage.coverage = applicationSourceCoverage - return - } + if (!applicationSourceCoverage) { + return + } - windowCoverageObjects.push({ - coverage: applicationSourceCoverage, - pathname: win.location.pathname - }) + const existingCoverage = Cypress._.find(windowCoverageObjects, { + coverage: applicationSourceCoverage + }) + if (existingCoverage) { + // Both `window:load` and `cy.window()` can report the same window, and + // navigating away and back creates a new object for the same page. The + // old object stops updating, so keep the latest one. + existingCoverage.coverage = applicationSourceCoverage + return } + windowCoverageObjects.push({ + coverage: applicationSourceCoverage, + pathname: win.location.pathname + }) + } + + beforeEach(() => { + windowCoverageObjects = [] + cy.on('window:load', saveCoverageObject) // Catches a page visited in a before() hook, which loaded before the @@ -137,30 +137,36 @@ function registerHooks(): void { }) afterEach(() => { + // Some apps only create `__coverage__` after `window:load`, for example + // when a framework runs component code during hydration + cy.window({ log: false }).then(saveCoverageObject) + // Send after the test so the counters include everything it ran - windowCoverageObjects.forEach((cover) => { - sendCoverage(cover.coverage, cover.pathname) - }) + cy.then(() => { + windowCoverageObjects.forEach((cover) => { + sendCoverage(cover.coverage, cover.pathname) + }) - if (!hasE2ECoverage()) { - if (hasUnitTestCoverage()) { - logMessage(`👉 Only found unit test code coverage.`) - } else { - const expectBackendCoverageOnly = Cypress._.get( - Cypress.expose('codeCoverage'), - 'expectBackendCoverageOnly', - false - ) - if (!expectBackendCoverageOnly) { - logMessage(` + if (!hasE2ECoverage()) { + if (hasUnitTestCoverage()) { + logMessage(`👉 Only found unit test code coverage.`) + } else { + const expectBackendCoverageOnly = Cypress._.get( + Cypress.expose('codeCoverage'), + 'expectBackendCoverageOnly', + false + ) + if (!expectBackendCoverageOnly) { + logMessage(` ⚠️ Could not find any coverage information in your application by looking at the window coverage object. Did you forget to instrument your application? See [code-coverage#instrument-your-application](https://github.com/cypress-io/code-coverage#instrument-your-application) `) + } } } - } + }) }) after(function collectBackendCoverage() { diff --git a/test-apps/swc-webpack/.swcrc b/test-apps/swc-webpack/.swcrc new file mode 100644 index 00000000..81ae22ec --- /dev/null +++ b/test-apps/swc-webpack/.swcrc @@ -0,0 +1,10 @@ +{ + "jsc": { + "parser": { + "syntax": "ecmascript" + }, + "experimental": { + "plugins": [["swc-plugin-coverage-instrument", {}]] + } + } +} diff --git a/test-apps/swc-webpack/README.md b/test-apps/swc-webpack/README.md new file mode 100644 index 00000000..10acadf6 --- /dev/null +++ b/test-apps/swc-webpack/README.md @@ -0,0 +1,7 @@ +# swc-webpack + +> Instruments the bundle with SWC instead of Babel + +webpack builds [src/index.js](src/index.js) with [swc-loader](https://www.npmjs.com/package/swc-loader). The [.swcrc](.swcrc) file adds [swc-plugin-coverage-instrument](https://github.com/kwonoj/swc-coverage-instrument), which writes Istanbul-compatible counters to `window.__coverage__`. + +[index.html](index.html) loads the bundle after the page's `load` event, the way frameworks like Next.js run component code during hydration. This checks that the plugin still collects coverage that appears after the page loads. diff --git a/test-apps/swc-webpack/cypress.config.js b/test-apps/swc-webpack/cypress.config.js new file mode 100644 index 00000000..8fee4073 --- /dev/null +++ b/test-apps/swc-webpack/cypress.config.js @@ -0,0 +1,13 @@ +const { defineConfig } = require('cypress') + +module.exports = defineConfig({ + allowCypressEnv: false, + fixturesFolder: false, + e2e: { + baseUrl: 'http://localhost:1234', + setupNodeEvents(on, config) { + require('@cypress/code-coverage/task')(on, config) + return config + } + } +}) diff --git a/test-apps/swc-webpack/cypress/e2e/spec.cy.js b/test-apps/swc-webpack/cypress/e2e/spec.cy.js new file mode 100644 index 00000000..6adbe5fc --- /dev/null +++ b/test-apps/swc-webpack/cypress/e2e/spec.cy.js @@ -0,0 +1,4 @@ +it('shows the sum', () => { + cy.visit('/') + cy.contains('#result', '2 + 3 = 5') +}) diff --git a/test-apps/swc-webpack/cypress/support/e2e.js b/test-apps/swc-webpack/cypress/support/e2e.js new file mode 100644 index 00000000..cc6040de --- /dev/null +++ b/test-apps/swc-webpack/cypress/support/e2e.js @@ -0,0 +1 @@ +import '@cypress/code-coverage/support' diff --git a/test-apps/swc-webpack/index.html b/test-apps/swc-webpack/index.html new file mode 100644 index 00000000..6f8527de --- /dev/null +++ b/test-apps/swc-webpack/index.html @@ -0,0 +1,15 @@ + + + +

+ + + diff --git a/test-apps/swc-webpack/package.json b/test-apps/swc-webpack/package.json new file mode 100644 index 00000000..074bbf64 --- /dev/null +++ b/test-apps/swc-webpack/package.json @@ -0,0 +1,19 @@ +{ + "name": "example-swc-webpack", + "description": "Code coverage from SWC instrumentation in a webpack build", + "private": true, + "scripts": { + "cy:run": "cypress run", + "build": "webpack && cp ./index.html ./dist/index.html", + "start": "serve -p 1234 dist", + "pretest": "rimraf .nyc_output coverage dist", + "test": "npm run build && start-test 1234 cy:run", + "coverage:verify": "npx nyc report --check-coverage true --lines 100", + "coverage:check-files": "check-coverage src/index.js && check-coverage src/calc.js && only-covered src/index.js src/calc.js" + }, + "devDependencies": { + "@swc/core": "1.16.18", + "swc-loader": "^0.2.7", + "swc-plugin-coverage-instrument": "0.0.33" + } +} diff --git a/test-apps/swc-webpack/src/calc.js b/test-apps/swc-webpack/src/calc.js new file mode 100644 index 00000000..6e31ef4b --- /dev/null +++ b/test-apps/swc-webpack/src/calc.js @@ -0,0 +1 @@ +export const add = (a, b) => a + b diff --git a/test-apps/swc-webpack/src/index.js b/test-apps/swc-webpack/src/index.js new file mode 100644 index 00000000..c3879a46 --- /dev/null +++ b/test-apps/swc-webpack/src/index.js @@ -0,0 +1,3 @@ +import { add } from './calc' + +document.getElementById('result').textContent = `2 + 3 = ${add(2, 3)}` diff --git a/test-apps/swc-webpack/webpack.config.js b/test-apps/swc-webpack/webpack.config.js new file mode 100644 index 00000000..fd42db0e --- /dev/null +++ b/test-apps/swc-webpack/webpack.config.js @@ -0,0 +1,20 @@ +const path = require('path') + +module.exports = { + entry: './src/index.js', + mode: 'development', + devtool: 'source-map', + output: { + filename: 'main.js', + path: path.resolve(__dirname, 'dist') + }, + module: { + rules: [ + { + test: /\.js$/, + exclude: /node_modules/, + use: 'swc-loader' + } + ] + } +} From a11e1b2fd85c7c98911149577f55a9522fa04be9 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 21:42:19 +0000 Subject: [PATCH 6/6] fix: read each page's coverage before it unloads Re-reading the window in `afterEach` only reached the page a test ended on. If a test visited a page that created `__coverage__` after `window:load` and then visited another page, the first page's coverage was lost. Also read the window on `window:before:unload`, so every page is read before it goes away. Extend test-apps/swc-webpack to visit two pages that run different branches. It reports 75% lines when only the last page is read, and 100% with this change. Refs #583 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r2ZU5whUYbhTLy6nfa --- lib/support.ts | 10 ++++++++-- test-apps/swc-webpack/README.md | 2 +- test-apps/swc-webpack/cypress/e2e/spec.cy.js | 4 +++- test-apps/swc-webpack/src/index.js | 7 ++++++- 4 files changed, 18 insertions(+), 5 deletions(-) diff --git a/lib/support.ts b/lib/support.ts index 72202977..c30c9c77 100644 --- a/lib/support.ts +++ b/lib/support.ts @@ -131,14 +131,20 @@ function registerHooks(): void { cy.on('window:load', saveCoverageObject) + // Some apps only create `__coverage__` after `window:load`, for example + // when a framework runs component code during hydration, so read each + // page again before it goes away + cy.on('window:before:unload', (event: BeforeUnloadEvent) => { + saveCoverageObject(event.currentTarget as Window) + }) + // Catches a page visited in a before() hook, which loaded before the // `window:load` listener existed cy.window({ log: false }).then(saveCoverageObject) }) afterEach(() => { - // Some apps only create `__coverage__` after `window:load`, for example - // when a framework runs component code during hydration + // The last page never unloads during the test cy.window({ log: false }).then(saveCoverageObject) // Send after the test so the counters include everything it ran diff --git a/test-apps/swc-webpack/README.md b/test-apps/swc-webpack/README.md index 10acadf6..2f96508f 100644 --- a/test-apps/swc-webpack/README.md +++ b/test-apps/swc-webpack/README.md @@ -4,4 +4,4 @@ webpack builds [src/index.js](src/index.js) with [swc-loader](https://www.npmjs.com/package/swc-loader). The [.swcrc](.swcrc) file adds [swc-plugin-coverage-instrument](https://github.com/kwonoj/swc-coverage-instrument), which writes Istanbul-compatible counters to `window.__coverage__`. -[index.html](index.html) loads the bundle after the page's `load` event, the way frameworks like Next.js run component code during hydration. This checks that the plugin still collects coverage that appears after the page loads. +[index.html](index.html) loads the bundle after the page's `load` event, the way frameworks like Next.js run component code during hydration. The test in [cypress/e2e/spec.cy.js](cypress/e2e/spec.cy.js) visits two pages that run different branches, which checks that the plugin collects coverage that appears after each page loads, including a page the test has already left. diff --git a/test-apps/swc-webpack/cypress/e2e/spec.cy.js b/test-apps/swc-webpack/cypress/e2e/spec.cy.js index 6adbe5fc..c74b3f25 100644 --- a/test-apps/swc-webpack/cypress/e2e/spec.cy.js +++ b/test-apps/swc-webpack/cypress/e2e/spec.cy.js @@ -1,4 +1,6 @@ -it('shows the sum', () => { +it('visits two pages', () => { cy.visit('/') cy.contains('#result', '2 + 3 = 5') + cy.visit('/?second') + cy.contains('#result', 'second page') }) diff --git a/test-apps/swc-webpack/src/index.js b/test-apps/swc-webpack/src/index.js index c3879a46..0ce3b2fd 100644 --- a/test-apps/swc-webpack/src/index.js +++ b/test-apps/swc-webpack/src/index.js @@ -1,3 +1,8 @@ import { add } from './calc' -document.getElementById('result').textContent = `2 + 3 = ${add(2, 3)}` +const result = document.getElementById('result') +if (location.search === '?second') { + result.textContent = 'second page' +} else { + result.textContent = `2 + 3 = ${add(2, 3)}` +}