From 8e6303dfeeebbadbffd675aeccadaf670a1f82b8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 22:50:26 +0000 Subject: [PATCH 1/3] docs: explain how to collect coverage from web workers (#102) The support hooks read `__coverage__` from the app and spec windows only. An instrumented dedicated worker keeps its counters on its own global, so its code never reached the report. Document a workaround: the worker replies to a coverage request over a MessageChannel, and an afterEach hook in the support file sends each reply to the combineCoverage task. Refs #102 Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r3qbyBkGWEnvGWtCrX --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/README.md b/README.md index 68b01a6d..1dd200a3 100644 --- a/README.md +++ b/README.md @@ -458,6 +458,80 @@ If there is ONLY frontend code coverage, set `expectFrontendCoverageOnly: true` } ``` +## Coverage from web workers + +Is code that runs in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) missing from your report, even though your tests exercise it? That's expected. The plugin reads `window.__coverage__` from the app and spec windows, but an instrumented worker keeps its counters on its own global, `self.__coverage__`, and the plugin never sees it. + +You can close the gap yourself in two steps: have the worker hand over its coverage when asked, and have your tests ask for it and pass it to the plugin's `combineCoverage` task. + +1. Make sure your bundler instruments the worker file too. Worker bundles are often built separately from the main bundle. If you're not sure, log `self.__coverage__` from inside the worker. +2. In the worker, reply to a coverage request. A [`MessageChannel`](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel) port carries the reply, so your app's own `message` handlers on the main thread never see it. + +```js +// src/worker.js +/* istanbul ignore next */ +if (self.__coverage__) { + self.addEventListener('message', (event) => { + if (event.data === 'cypress:coverage') { + event.ports[0].postMessage(self.__coverage__) + } + }) +} +``` + +If the worker has its own `message` handler, have it ignore the `'cypress:coverage'` message. + +3. In your support file, keep track of every worker the app creates. After each test, ask each one for its coverage and send it to the plugin. + +```js +// cypress/support/e2e.js +import '@cypress/code-coverage/support' + +let workers = [] + +Cypress.on('window:before:load', (win) => { + win.Worker = class extends win.Worker { + constructor(...args) { + super(...args) + workers.push(this) + } + } +}) + +function getWorkerCoverage(worker) { + return new Promise((resolve) => { + const channel = new MessageChannel() + // A worker that was terminated, or belonged to a page that's gone, + // never answers + const timer = setTimeout(() => resolve(null), 1000) + channel.port1.onmessage = (event) => { + clearTimeout(timer) + resolve(event.data) + } + worker.postMessage('cypress:coverage', [channel.port2]) + }) +} + +afterEach(() => { + const testWorkers = workers + workers = [] + + cy.then(() => Promise.all(testWorkers.map(getWorkerCoverage))).then( + (coverages) => { + coverages.filter(Boolean).forEach((coverage) => { + cy.task('combineCoverage', JSON.stringify(coverage), { log: false }) + }) + } + ) +}) +``` + +A few things to keep in mind: + +- A worker's counters live only as long as the worker does. Collect coverage before the test terminates the worker or leaves the page that started it. +- The example asks each worker for coverage once, at the end of the test that started it. That suits tests that call `cy.visit()` in each test or in `beforeEach()`, because every visit starts new workers. Workers that outlive their test don't report their activity in later tests. +- This covers dedicated workers created with `new Worker()`. Shared workers and service workers outlive the page, so you'd need a different way to reach them. + ## 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. From 0bda2e321e78987cce2725ebb830f3d5778fe903 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 23:03:55 +0000 Subject: [PATCH 2/3] docs: clarify the limits of the web worker coverage workaround (#102) Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r3qbyBkGWEnvGWtCrX --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1dd200a3..71e7d913 100644 --- a/README.md +++ b/README.md @@ -526,7 +526,7 @@ afterEach(() => { }) ``` -A few things to keep in mind: +Before you rely on this workaround, know where it stops working: - A worker's counters live only as long as the worker does. Collect coverage before the test terminates the worker or leaves the page that started it. - The example asks each worker for coverage once, at the end of the test that started it. That suits tests that call `cy.visit()` in each test or in `beforeEach()`, because every visit starts new workers. Workers that outlive their test don't report their activity in later tests. From e56f413b7b3b1ec8092574388c587df082387cd2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 1 Nov 2026 23:55:28 +0000 Subject: [PATCH 3/3] docs: tidy the web worker coverage steps (#102) Soften the lead-in to the workaround's limits, drop a step count that didn't match the list, and nest the code samples under their steps so the numbered list renders as one list. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01WUv8r3qbyBkGWEnvGWtCrX --- README.md | 106 +++++++++++++++++++++++++++--------------------------- 1 file changed, 53 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 71e7d913..6ea90aca 100644 --- a/README.md +++ b/README.md @@ -462,71 +462,71 @@ If there is ONLY frontend code coverage, set `expectFrontendCoverageOnly: true` Is code that runs in a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) missing from your report, even though your tests exercise it? That's expected. The plugin reads `window.__coverage__` from the app and spec windows, but an instrumented worker keeps its counters on its own global, `self.__coverage__`, and the plugin never sees it. -You can close the gap yourself in two steps: have the worker hand over its coverage when asked, and have your tests ask for it and pass it to the plugin's `combineCoverage` task. +You can close the gap yourself: have the worker hand over its coverage when asked, and have your tests ask for it and pass it to the plugin's `combineCoverage` task. 1. Make sure your bundler instruments the worker file too. Worker bundles are often built separately from the main bundle. If you're not sure, log `self.__coverage__` from inside the worker. 2. In the worker, reply to a coverage request. A [`MessageChannel`](https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel) port carries the reply, so your app's own `message` handlers on the main thread never see it. -```js -// src/worker.js -/* istanbul ignore next */ -if (self.__coverage__) { - self.addEventListener('message', (event) => { - if (event.data === 'cypress:coverage') { - event.ports[0].postMessage(self.__coverage__) - } - }) -} -``` + ```js + // src/worker.js + /* istanbul ignore next */ + if (self.__coverage__) { + self.addEventListener('message', (event) => { + if (event.data === 'cypress:coverage') { + event.ports[0].postMessage(self.__coverage__) + } + }) + } + ``` -If the worker has its own `message` handler, have it ignore the `'cypress:coverage'` message. + If the worker has its own `message` handler, have it ignore the `'cypress:coverage'` message. 3. In your support file, keep track of every worker the app creates. After each test, ask each one for its coverage and send it to the plugin. -```js -// cypress/support/e2e.js -import '@cypress/code-coverage/support' - -let workers = [] - -Cypress.on('window:before:load', (win) => { - win.Worker = class extends win.Worker { - constructor(...args) { - super(...args) - workers.push(this) - } - } -}) + ```js + // cypress/support/e2e.js + import '@cypress/code-coverage/support' -function getWorkerCoverage(worker) { - return new Promise((resolve) => { - const channel = new MessageChannel() - // A worker that was terminated, or belonged to a page that's gone, - // never answers - const timer = setTimeout(() => resolve(null), 1000) - channel.port1.onmessage = (event) => { - clearTimeout(timer) - resolve(event.data) - } - worker.postMessage('cypress:coverage', [channel.port2]) - }) -} + let workers = [] -afterEach(() => { - const testWorkers = workers - workers = [] + Cypress.on('window:before:load', (win) => { + win.Worker = class extends win.Worker { + constructor(...args) { + super(...args) + workers.push(this) + } + } + }) - cy.then(() => Promise.all(testWorkers.map(getWorkerCoverage))).then( - (coverages) => { - coverages.filter(Boolean).forEach((coverage) => { - cy.task('combineCoverage', JSON.stringify(coverage), { log: false }) - }) - } - ) -}) -``` + function getWorkerCoverage(worker) { + return new Promise((resolve) => { + const channel = new MessageChannel() + // A worker that was terminated, or belonged to a page that's gone, + // never answers + const timer = setTimeout(() => resolve(null), 1000) + channel.port1.onmessage = (event) => { + clearTimeout(timer) + resolve(event.data) + } + worker.postMessage('cypress:coverage', [channel.port2]) + }) + } + + afterEach(() => { + const testWorkers = workers + workers = [] + + cy.then(() => Promise.all(testWorkers.map(getWorkerCoverage))).then( + (coverages) => { + coverages.filter(Boolean).forEach((coverage) => { + cy.task('combineCoverage', JSON.stringify(coverage), { log: false }) + }) + } + ) + }) + ``` -Before you rely on this workaround, know where it stops working: +This workaround has a few limits: - A worker's counters live only as long as the worker does. Collect coverage before the test terminates the worker or leaves the page that started it. - The example asks each worker for coverage once, at the end of the test that started it. That suits tests that call `cy.visit()` in each test or in `beforeEach()`, because every visit starts new workers. Workers that outlive their test don't report their activity in later tests.