From f5e8dcc41b0c12672e1fe42fab1fc9cb18b813b9 Mon Sep 17 00:00:00 2001 From: Chris Breiding Date: Tue, 18 Oct 2022 15:59:11 -0400 Subject: [PATCH 1/6] update cy.origin dependencies / remove Cypress.require() --- content/api/commands/origin.md | 38 +++++++----- content/api/cypress-api/require.md | 77 ------------------------- cypress/fixtures/sidebar-overrides.json | 1 - 3 files changed, 24 insertions(+), 92 deletions(-) delete mode 100644 content/api/cypress-api/require.md diff --git a/content/api/commands/origin.md b/content/api/commands/origin.md index 0f620fee82..68c47a6257 100755 --- a/content/api/commands/origin.md +++ b/content/api/commands/origin.md @@ -507,27 +507,37 @@ into the callback. ### Dependencies / Sharing Code -It is not possible to use +[ES module dynamic `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports) +and/or [CommonJS `require()`](https://nodejs.org/en/knowledge/getting-started/what-is-require/) -or -[dynamic ES module `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports) -within the callback. However, [`Cypress.require()`](/api/cypress-api/require) -can be utilized to include [npm](https://www.npmjs.com/) packages and other -files. It is functionally the same as using -[CommonJS `require()`](https://nodejs.org/en/knowledge/getting-started/what-is-require/) -in browser-targeted code. +can be used within the callback to include [npm](https://www.npmjs.com/) +packages and other files. + +If you utilize a custom preprocessor, note that this feature requires the latest +version of +[`@cypress/webpack-preprocessor`](https://github.com/cypress-io/cypress/tree/master/npm/webpack-preprocessor) +to work. ```js +// ES modules +cy.origin('somesite.com', async () => { + const _ = await import('lodash') + const utils = await import('../support/utils') + + // ... use lodash and utils ... +}) + +// CommonJS cy.origin('somesite.com', () => { - const _ = Cypress.require('lodash') - const utils = Cypress.require('../support/utils') + const _ = require('lodash') + const utils = require('../support/utils') // ... use lodash and utils ... }) ``` -`Cypress.require()` can be used to share custom commands between tests run in -primary and secondary origins. We recommend this pattern for setting up your +This makes it possible to share custom commands between tests run in primary and +secondary origins. We recommend this pattern for setting up your [support file](/guides/core-concepts/writing-and-organizing-tests#Support-file) and setting up custom commands to run within the `cy.origin()` callback: @@ -561,7 +571,7 @@ before(() => { // calls in this spec. put it in your support file to make them available to // all specs cy.origin('somesite.com', () => { - Cypress.require('../support/commands') + require('../support/commands') }) }) @@ -582,7 +592,7 @@ before(() => { cy.origin('somesite.com', () => { // makes commands defined in this file available to all callbacks // for somesite.com - Cypress.require('../support/commands') + require('../support/commands') }) }) diff --git a/content/api/cypress-api/require.md b/content/api/cypress-api/require.md deleted file mode 100644 index f87b53b8f9..0000000000 --- a/content/api/cypress-api/require.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Cypress.require ---- - -`Cypress.require` enables utilizing dependencies within the -[`cy.origin()`](/api/commands/origin) callback function. It is used to require -modules such as [npm](https://www.npmjs.com/) packages and other local files. - -It is functionally the same as using -[CommonJS `require()`](https://nodejs.org/en/knowledge/getting-started/what-is-require/) -in browser-targeted code. - -## Syntax - -```js -Cypress.require(moduleId) -``` - -## Usage - -** Correct Usage** - -```js -cy.origin('somesite.com', () => { - const _ = Cypress.require('lodash') - const utils = Cypress.require('./utils') - - // ... use lodash and utils ... -}) -``` - -** Incorrect Usage** - -```js -// `Cypress.require()` cannot be used outside the `cy.origin()` callback. -// Use `require()` instead -const _ = Cypress.require('lodash') - -cy.origin('somesite.com', () => { - // `require()` cannot be used inside the `cy.origin()` callback. - // Use `Cypress.require()` instead - const _ = require('lodash') -}) - -// the callback must be inline and cannot be assigned to a variable for -// `Cypress.require()` to work -const callback = () => { - const _ = Cypress.require('lodash') -}) - -cy.origin('somesite.com', callback) -``` - -## Examples - -See -[`cy.origin()` Dependencies / Sharing Code](/api/commands/origin#Dependencies-Sharing-Code) -for example usages. - -## Limitations - -- `Cypress.require` only works when called within the - [`cy.origin()`](/api/commands/origin) callback function. It will error if used - elsewhere. -- `Cypress.require` only works in conjunction with the - [webpack preprocessor](https://www.npmjs.com/package/@cypress/webpack-preprocessor), - which is the default preprocessor for Cypress. If you have manually installed - and configured the webpack preprocessor, ensure you are using version `5.13.0` - or greater. -- For `Cypress.require` to work, the callback function must be written inline - with the `cy.origin()` call. The callback cannot be assigned to a variable. - -## History - -| Version | Changes | -| --------------------------------------------- | ----------------------- | -| [10.7.0](/guides/references/changelog#10-7-0) | `Cypress.require` added | diff --git a/cypress/fixtures/sidebar-overrides.json b/cypress/fixtures/sidebar-overrides.json index 6776822221..d8653b2086 100644 --- a/cypress/fixtures/sidebar-overrides.json +++ b/cypress/fixtures/sidebar-overrides.json @@ -34,7 +34,6 @@ "/api/cypress-api/iscy": "Cypress.isCy", "/api/cypress-api/cypress-log": "Cypress.log", "/api/cypress-api/platform": "Cypress.platform", - "/api/cypress-api/require": "Cypress.require", "/api/cypress-api/spec": "Cypress.spec", "/api/cypress-api/session": "Cypress.session", "/api/cypress-api/testing-type": "Cypress.testingType", From c90839ab9f4e9bcf56e8bcb920566bd47448a393 Mon Sep 17 00:00:00 2001 From: Chris Breiding Date: Tue, 18 Oct 2022 16:20:03 -0400 Subject: [PATCH 2/6] remove Cypress.require() from sidebar --- content/_data/sidebar.json | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/_data/sidebar.json b/content/_data/sidebar.json index 22196f636d..d547d20244 100644 --- a/content/_data/sidebar.json +++ b/content/_data/sidebar.json @@ -985,10 +985,6 @@ "title": "platform", "slug": "platform" }, - { - "title": "require", - "slug": "require" - }, { "title": "session", "slug": "session" From 590ce263e36bf9c2a5a1014fcad73cb699ec33b6 Mon Sep 17 00:00:00 2001 From: Chris Breiding Date: Tue, 18 Oct 2022 16:46:51 -0400 Subject: [PATCH 3/6] add error message --- content/api/commands/origin.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/content/api/commands/origin.md b/content/api/commands/origin.md index 68c47a6257..5db38f3f67 100755 --- a/content/api/commands/origin.md +++ b/content/api/commands/origin.md @@ -516,7 +516,13 @@ packages and other files. If you utilize a custom preprocessor, note that this feature requires the latest version of [`@cypress/webpack-preprocessor`](https://github.com/cypress-io/cypress/tree/master/npm/webpack-preprocessor) -to work. +to work. If using a custom preprocessor or an older version of the webpack +preprocessor, you'll see an error that includes the following text: + +``` +Using require() or import() to include dependencies requires using the +latest version of @cypress/webpack-preprocessor. +``` ```js // ES modules From 42354f2865a0abe95011ba798769dfff2879a8df Mon Sep 17 00:00:00 2001 From: Chris Breiding Date: Wed, 19 Oct 2022 09:28:44 -0400 Subject: [PATCH 4/6] add specific preprocessor version, improve copy, and add headers --- content/api/commands/origin.md | 30 +++++++++++++++++++++--------- 1 file changed, 21 insertions(+), 9 deletions(-) diff --git a/content/api/commands/origin.md b/content/api/commands/origin.md index 5db38f3f67..545a988782 100755 --- a/content/api/commands/origin.md +++ b/content/api/commands/origin.md @@ -513,16 +513,24 @@ and/or can be used within the callback to include [npm](https://www.npmjs.com/) packages and other files. -If you utilize a custom preprocessor, note that this feature requires the latest -version of -[`@cypress/webpack-preprocessor`](https://github.com/cypress-io/cypress/tree/master/npm/webpack-preprocessor) -to work. If using a custom preprocessor or an older version of the webpack -preprocessor, you'll see an error that includes the following text: + -``` -Using require() or import() to include dependencies requires using the -latest version of @cypress/webpack-preprocessor. -``` +Using `import()` and `require()` within the callback requires version 5.15.0 or +greater of the +[`@cypress/webpack-preprocessor`](https://github.com/cypress-io/cypress/tree/master/npm/webpack-preprocessor). +This is included in Cypress by default, but if your project installs its own +version of `@cypress/webpack-preprocessor` that is set up in your Cypress +config, make sure it is version 5.15.0 or greater. + +If using an older version of the webpack or a different preprocessor, you'll see +an error that includes the following text: + +_Using require() or import() to include dependencies requires using the latest +version of @cypress/webpack-preprocessor._ + + + +#### Example ```js // ES modules @@ -542,6 +550,8 @@ cy.origin('somesite.com', () => { }) ``` +#### Custom commands + This makes it possible to share custom commands between tests run in primary and secondary origins. We recommend this pattern for setting up your [support file](/guides/core-concepts/writing-and-organizing-tests#Support-file) @@ -589,6 +599,8 @@ it('tests somesite.com', () => { }) ``` +#### Shared execution context + The JavaScript execution context is persisted between `cy.origin()` callbacks that share the same origin. This can be utilized to share code between successive `cy.origin()` calls. From ff7fa2f5f55e7ce60761f86abd341c290a3afbf5 Mon Sep 17 00:00:00 2001 From: Chris Breiding Date: Wed, 19 Oct 2022 09:36:55 -0400 Subject: [PATCH 5/6] add 10.11.0 changelog --- content/_changelogs/10.11.0.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 content/_changelogs/10.11.0.md diff --git a/content/_changelogs/10.11.0.md b/content/_changelogs/10.11.0.md new file mode 100644 index 0000000000..0aabc8a722 --- /dev/null +++ b/content/_changelogs/10.11.0.md @@ -0,0 +1,8 @@ +## 10.11.0 + +_Released 10/25/2022_ + +**Features:** + +- `cy.origin()` now supports using `require()` and dynamic `import()` to include + dependencies. `Cypress.require()` has been removed. From e884c0e118fe6cd227cc5cbd138c52719fb290ff Mon Sep 17 00:00:00 2001 From: Chris Breiding Date: Wed, 19 Oct 2022 09:39:10 -0400 Subject: [PATCH 6/6] add gh link --- content/_changelogs/10.11.0.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/_changelogs/10.11.0.md b/content/_changelogs/10.11.0.md index 0aabc8a722..6dafe326f7 100644 --- a/content/_changelogs/10.11.0.md +++ b/content/_changelogs/10.11.0.md @@ -5,4 +5,5 @@ _Released 10/25/2022_ **Features:** - `cy.origin()` now supports using `require()` and dynamic `import()` to include - dependencies. `Cypress.require()` has been removed. + dependencies. `Cypress.require()` has been removed. Addresses + [#24293](https://github.com/cypress-io/cypress/issues/24293).