diff --git a/docs/api/commands/origin.mdx b/docs/api/commands/origin.mdx index d98a40bd00..9d8f5f89e9 100644 --- a/docs/api/commands/origin.mdx +++ b/docs/api/commands/origin.mdx @@ -3,8 +3,8 @@ title: origin e2eSpecific: true --- -Visit multiple domains of different -[origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#definition_of_an_origin) +Visit multiple different +[origins](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy#definition_of_an_origin) in a single test. In normal use, a single Cypress test may only run commands in a single origin, a @@ -28,6 +28,18 @@ doc. ::: +:::info + +Changes in Cypress [v14.0.0](/app/references/changelog#14-0-0) + +Cypress no longer injects `document.domain` by default, which means `cy.origin()` +must now be used to navigate between any two origins in the same test, even if +the two origins are in the same superdomain. This behavior can be disabled by setting +the `injectDocumentDomain` configuration option to `true`, to allow a smooth transition +of tests to the new behavior. In Cypress 15, this configuration option will be removed. + +::: + ## Syntax ```js @@ -63,26 +75,28 @@ cy.get('h1').contains('My cool site under test') const hits = getHits() cy.visit('https://example.cypress.io/history/founder') // To interact with cross-origin content, move this inside cy.origin() callback -cy.get('h1').contains('About our Founder') -// Domain must be a precise match including subdomain, i.e. example.cypress.io -cy.origin('cypress.io', () => { - cy.visit('/history/founder') - cy.get('h1').contains('About our Founder') - // Fails because hits is not passed in via args - cy.get('#hitcounter').contains(hits) +cy.get('h1').contains('Kitchen Sink') +// Origin must be a precise match including scheme, subdomain and port, i.e. https://www.cypress.io +cy.origin('https://www.cypress.io', () => { + cy.visit('/about-us') + cy.get('h1').contains('About us') + // Fails because doanloads is not passed in via args + cy.contains(downloads) }) -// Won't work because still on cypress.io -cy.get('h1').contains('My cool site under test') +// Won't work because still on www.cypress.io +cy.get('h1').contains('Kitchen Sink') ``` ### Arguments - **url _(String)_** + **origin _(String)_** -A URL specifying the secondary origin in which the callback is to be executed. -This should at the very least contain a hostname, and may also include the -protocol, port number & path. The hostname must precisely match that of the -secondary origin, including all subdomains. Query params are not supported. +A string specifying the origin in which the callback is to be executed. +This should at the very least contain a hostname. It may also include the +scheme and port number. The path may be included, but is not necessary. +The hostname must precisely match that of the secondary origin, including +all subdomains. Query params are not supported. If no scheme is provided, +the scheme defaults to `https`. This argument will be used in two ways: @@ -542,6 +556,7 @@ inclusion in a future version of Cypress. | Version | Changes | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| [14.0.0](/app/references/changelog#14-0-0) | `cy.origin()` is now required when navigating between origins in the same test, rather than superdomains. | | [12.6.0](/app/references/changelog#10-7-0) | Support for `Cypress.require()` added and support for CommonJS `require()` and ES module `import()` removed | | [10.11.0](/app/references/changelog#10-7-0) | Support for CommonJS `require()` and ES module `import()` added and support for `Cypress.require()` removed | | [10.7.0](/app/references/changelog#10-7-0) | Support for `Cypress.require()` added | diff --git a/docs/app/faq.mdx b/docs/app/faq.mdx index 28a0798a30..d8bfc15aaa 100644 --- a/docs/app/faq.mdx +++ b/docs/app/faq.mdx @@ -452,7 +452,7 @@ a remote page and does not resolve until all of the external resources complete their loading phase. Because we expect your applications to observe differing load times, this command's default timeout is set to 60000ms. If you visit an invalid url or a -[second unique domain](/app/guides/cross-origin-testing#Different-superdomain-per-test-requires-cyorigin), +[second unique domain](/app/guides/cross-origin-testing#Different-origins-per-test-require-cyorigin), Cypress will log a verbose yet friendly error message. **_In CI, how do I make sure my server has started?_** diff --git a/docs/app/guides/cross-origin-testing.mdx b/docs/app/guides/cross-origin-testing.mdx index 5f67abeadc..ce0c74e719 100644 --- a/docs/app/guides/cross-origin-testing.mdx +++ b/docs/app/guides/cross-origin-testing.mdx @@ -31,9 +31,6 @@ and we are _mostly_ able to do this. ### What Cypress does under the hood -- Injects - [`document.domain`](https://developer.mozilla.org/en-US/docs/Web/API/Document/domain) - into `text/html` pages. - Proxies all HTTP / HTTPS traffic. - Changes the hosted URL to match that of the application under test. - Uses the browser's internal APIs for network level traffic. @@ -55,7 +52,7 @@ Cypress must assign and manage browser certificates to be able to modify the traffic in real time. You'll notice Chrome display a warning that the 'SSL certificate does not match'. This is expected behavior. Under the hood we act as our own CA authority and issue certificates dynamically in order to intercept requests -otherwise impossible to access. We only do this for the superdomain currently +otherwise impossible to access. We only do this for the origin currently under test, and bypass other traffic. Note, that Cypress allows you to optionally specify CA / client certificate @@ -72,39 +69,37 @@ It's important to note that although we do our **very best** to ensure your application works normally inside of Cypress, there _are_ some limitations you need to be aware of. -- [Different superdomain per test requires cy.origin command](#Different-superdomain-per-test-requires-cyorigin) +- [Different origins per test require cy.origin()](#Different-origins-per-test-require-cyorigin) - [Cross-origin iframes are not supported](#Cross-origin-iframes) - [Navigating from HTTPS to HTTP will error](#Insecure-Content) - [Cypress requires that the URLs navigated to have the same port](#Same-port-per-test) -### Different superdomain per test requires cy.origin +### Different origins per test require `cy.origin()` Cypress changes its own host URL to match that of your applications. With the exception of `cy.origin`, Cypress requires that the URLs navigated to have the -[same superdomain](/app/guides/cross-origin-testing#Parts-of-a-URL) for the +[origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin) for the entirety of a single test. -If you attempt to visit two different superdomains, the `cy.origin` command must +If you attempt to visit two different origins, the `cy.origin` command must be used to wrap Cypress commands of the second visited domain. Otherwise, Cypress commands will timeout after the navigation and will eventually error. This is because the commands that were expected to run on the second domain are actually being run on the first domain. -Without `cy.origin`, you can visit different superdomains in _different_ tests, -but not in the _same_ test. Please read our -[Cross Origin Testing Guide](/app/guides/cross-origin-testing) for more -information. +Without `cy.origin()`, you can visit different origins in _different_ tests, +but not in the _same_ test. #### Examples of test cases that will error without the use of `cy.origin` 1. [`.click()`](/api/commands/click) an `` with an `href` to a different - superdomain with subsequent Cypress commands being run. + origin with subsequent Cypress commands being run. 2. [`.submit()`](/api/commands/submit) a `
` that causes your web server to - redirect you a different superdomain where additional Cypress commands are + redirect you to a different origin where additional Cypress commands are run. 3. Issue a JavaScript redirect in your application, such as - `window.location.href = '...'`, to a different superdomain where additional - Cypress commands are run. + `window.location.href = '...'`, which navigates to a different origin + where additional Cypress commands are run. In each of these situations, Cypress will lose the ability to automate your application and will error via command timeout unless the `cy.origin` command is @@ -113,17 +108,6 @@ used. Read on to learn about [working around these common problems](#Common-Workarounds). -#### What is a superdomain? - -But what is same superdomain? It's actually very similar to that of same -origin! Two URLs have the same origin if the **protocol**, **port** (if specified), and -**host** match. Cypress automatically handles hosts of the same superdomain by -injecting the -[`document.domain`](https://developer.mozilla.org/en-US/docs/Web/API/Document/domain) -property into the visited `text/html` pages. This is why navigations without the -use of the [`cy.origin()`](/api/commands/origin) command are solely scoped to the -same superdomain. - #### Parts of a URL @@ -136,38 +120,33 @@ chart to help clarify the differences! alt="Diagram showing the parts of a URL including href broken into protocol, host, pathname, hash and smaller components of hostname, port, path, and search with and example URL" /> -Given the URLs below, all have the same superdomain compared to -`https://www.cypress.io`. - -- `https://cypress.io` -- `https://docs.cypress.io` -- `https://example.cypress.io/commands/querying` +##### Origin -The URLs below, however, will have different superdomains/origins compared to -`https://www.cypress.io`. +An `origin` is comprised of a URL's `scheme`, `hostname`, _and_ `port`. Given the URLs +below, all have the same origin compared to `https://www.cypress.io`: -- `http://www.cypress.io` (Different protocol) -- `https://docs.cypress.io:81` (Different port) -- `https://www.auth0.com/` (Different host of different superdomain) +- `https://www.cypress.io/cloud` +- `https://www.cypress.io/app` -The `http://localhost` URLs differ if their ports are different. For example, -the `http://localhost:3000` URL is considered to be a different origin from the -`http://localhost:8080` URL. +But the following have different origins compared to `https://www.cypress.io`: -The rules are: +- `http://www.cypress.io` (different `scheme`) +- `https://docs.cypress.io` (different `hostname` due to the subdomain) +- `https://www.auth0.com` (different `hostname`) +- `https://www.cypress.io:81` (different `port`) :::danger You **cannot** [visit](/api/commands/visit) -two domains of different superdomains in the same test and continue to interact with -the page without the use of the [`cy.origin()`](/api/commands/origin) command. +two different origins in the same test and continue to interact with the page without +the use of the [`cy.origin()`](/api/commands/origin) command. ::: :::tip You **can** [visit](/api/commands/visit) -two or more domains of different origin in **different** tests without needing [`cy.origin()`](/api/commands/origin). +two or more origins in **different** tests without needing [`cy.origin()`](/api/commands/origin). ::: For practical purposes, this means the following: @@ -176,16 +155,16 @@ For practical purposes, this means the following: // This test will run without error it('navigates', () => { cy.visit('https://www.cypress.io') - cy.visit('https://docs.cypress.io') + cy.visit('https://www.cypress.io/app') cy.get('selector') // yup all good }) ``` ```javascript -// this will error because cypress-dx.com doesn't match the cypress.io superdomain +// this will error because the origin https://docs.cypress.io doesn't match the origin https://www.cypress.io it('navigates', () => { cy.visit('https://www.cypress.io') - cy.visit('https://www.cypress-dx.com') + cy.visit('https://docs.cypress.io') cy.get('selector') }) ``` @@ -196,8 +175,8 @@ the sequential command should run against: ```javascript it('navigates', () => { cy.visit('https://example.cypress.io') - cy.visit('https://www.cypress-dx.com') - cy.origin('https://www.cypress-dx.com', () => { + cy.visit('https://docs.cypress.io') + cy.origin('https://docs.cypress.io', () => { cy.get('selector') // yup all good }) }) @@ -306,7 +285,7 @@ and break down how to work around them in Cypress. ### External Navigation The most common situation where you might encounter this error is when you click -on an `` that navigates to another superdomain. +on an `` that navigates to another origin. ```html title="index.html" @@ -322,14 +301,14 @@ cy.get('selector').should('exist') // Cypress errors :::warning -We don't recommend visiting a superdomain that you don't control in your tests +We don't recommend visiting an origin that you don't control in your tests which you can read more about [here](/app/core-concepts/best-practices#Visiting-External-Sites) ::: -If you control this superdomain, either by owning the hosted instance -or by other means, we recommend testing this superdomain with `cy.origin`. +If you control this origin, either by owning the hosted instance +or by other means, we recommend testing this origin with `cy.origin`. ```javascript title="test.cy.js" cy.visit('http://localhost:8080') // where your web server + HTML is hosted @@ -340,7 +319,7 @@ cy.origin('https://example.cypress.io', () => { }) ``` -If you're not in control of this superdomain, we recommend you test that the `href` +If you're not in control of this origin, we recommend you test that the `href` property is correct instead of performing the navigation. This will help lead to more deterministic tests. @@ -385,7 +364,7 @@ cy.get('form').submit() // submit the form! ``` If your back end server handling the `/submit` route does a `30x` redirect to a -different superdomain, you'll need to use the `cy.origin` command if running +different origin, you'll need to use the `cy.origin` command if running additional Cypress commands after submitting the form. ```javascript title="routes.js" @@ -533,7 +512,7 @@ Setting `chromeWebSecurity` to `false` in Chrome-based browsers allows you to do the following: - Display insecure content -- Navigate to any superdomain without cross-origin errors with or without +- Navigate to any origin without cross-origin errors with or without `cy.origin` - Access cross-origin iframes that are embedded in your application @@ -586,7 +565,7 @@ Want to enable `experimentalModifyObstructiveThirdPartyCode`? Let's do it! ## Other workarounds -There are other ways of testing the interaction between two superdomains. The +There are other ways of testing the interaction between two origins. The browser has a natural security barrier called `origin policy` this means that state like `localStorage`, `cookies`, `service workers` and many other APIs are not shared between them anyways. Cypress does offer APIs around `localStorage`, @@ -596,7 +575,7 @@ As a best practice, you should not visit or interact with any website not under your control. If your organization uses Single Sign On (SSO) or OAuth then you might choose to -test a 3rd party service other than your superdomain, which can be tested with +test a 3rd party service other than your origin, which can be tested with [`cy.origin()`](/api/commands/origin). We've written several other guides specifically about handling this situation. diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index 6e40caaf43..c80c0f6a3e 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -136,6 +136,8 @@ _Released 11/19/2024_ ## 13.15.2 +## 13.15.2 + _Released 11/5/2024_ **Bugfixes:** @@ -1542,11 +1544,11 @@ _Released 1/24/2023_ will help us make decisions to improve memory issues. Addresses [#23391](https://github.com/cypress-io/cypress/issues/23391). - Added new - [`experimentalSkipDomainInjection`](/app/references/experiments#Experimental-Skip-Domain-Injection) + `experimentalSkipDomainInjection` configuration option to disable Cypress from setting `document.domain` on injection, allowing users to test Salesforce domains. If you believe you are having `document.domain` issues, please see the - [`experimentalSkipDomainInjection`](/app/references/experiments#Experimental-Skip-Domain-Injection) + `experimentalSkipDomainInjection` guide. This config option is end-to-end only. Addresses [#2367](https://github.com/cypress-io/cypress/issues/2367), [#23958](https://github.com/cypress-io/cypress/issues/23958), diff --git a/docs/app/references/configuration.mdx b/docs/app/references/configuration.mdx index f19767b929..4b2bb8ebed 100644 --- a/docs/app/references/configuration.mdx +++ b/docs/app/references/configuration.mdx @@ -185,16 +185,17 @@ creating `e2e` and `component` objects inside your Cypress configuration. These options are available to be specified inside the `e2e` configuration object: -| Option | Default | Description | -| ------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `baseUrl` | `null` | URL used as prefix for [`cy.visit()`](/api/commands/visit) or [`cy.request()`](/api/commands/request) command's URL. | -| `setupNodeEvents` | `null` | Function in which node events can be registered and config can be modified. Takes the place of the (removed) pluginFile option. [Please read the notes for examples on using this.](#setupNodeEvents) | -| `supportFile` | `cypress/support/e2e.{js,jsx,ts,tsx}` | Path to file to load before spec files load. This file is compiled and bundled. (Pass `false` to disable) | -| `specPattern` | cypress/e2e/\*\*/\*.cy.\{js,jsx,ts,tsx\} | A String or Array of glob patterns of the test files to load. | -| `excludeSpecPattern` | `*.hot-update.js` | A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. [Please read the notes on using this.](#excludeSpecPattern) | -| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | -| `slowTestThreshold` | `10000` | Time, in milliseconds, to consider a test "slow" during `cypress run`. A slow test will display in orange text in the default reporter. | -| `testIsolation` | `true` | Whether or not [test isolation](/app/core-concepts/writing-and-organizing-tests#Test-Isolation) is enabled to ensure a clean browser context between tests. | +| Option | Default | Description | +| --------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `baseUrl` | `null` | URL used as prefix for [`cy.visit()`](/api/commands/visit) or [`cy.request()`](/api/commands/request) command's URL. | +| `setupNodeEvents` | `null` | Function in which node events can be registered and config can be modified. Takes the place of the (removed) pluginFile option. [Please read the notes for examples on using this.](#setupNodeEvents) | +| `supportFile` | `cypress/support/e2e.{js,jsx,ts,tsx}` | Path to file to load before spec files load. This file is compiled and bundled. (Pass `false` to disable) | +| `specPattern` | cypress/e2e/\*\*/\*.cy.\{js,jsx,ts,tsx\} | A String or Array of glob patterns of the test files to load. | +| `excludeSpecPattern` | `*.hot-update.js` | A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. [Please read the notes on using this.](#excludeSpecPattern) | +| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | +| `slowTestThreshold` | `10000` | Time, in milliseconds, to consider a test "slow" during `cypress run`. A slow test will display in orange text in the default reporter. | +| `testIsolation` | `true` | Whether or not [test isolation](/app/core-concepts/writing-and-organizing-tests#Test-Isolation) is enabled to ensure a clean browser context between tests. | +| `injectDocumentDomain` deprecated | `false` | Instructs Cypress to use the `document.domain` property to reduce the need for [`cy.origin`](/api/commands/origin). [Please read the notes on using this.](#injectDocumentDomain) | :::cypress-config-example @@ -590,6 +591,54 @@ The `**/node_modules/**` pattern is automatically added to `excludeSpecPattern` and does not need to be specified (and can't be overridden). See [`e2e`](#e2e) or [`component`](#component) testing-specific options. +### injectDocumentDomain + +This option is deprecated, and will be removed in Cypress. 15 + +Set this configuration option to `true` to instruct Cypress to +[inject document.domain](/app/guides/cross-origin-testing#What-Cypress-does-under-the-hood) +into your test application. This can reduce the need for `cy.origin()` when [navigating +between subdomains](/app/guides/cross-origin-testing), but comes with compatibility +caveats for some sites. + +This configuration option is provided to ease the transition between `cy.origin()`'s behavior +in Cypress 13 and the default behavior in Cypress 14. It will be removed in Cypress 15. +[Read the Cypress 14 migration guide](/app/references/migration-guide#Migrating-to-Cypress-140) to understand how to update your tests to remove +the need to set this flag. + +This configuration value _must_ be set to true if you are running tests with experimental +WebKit support, as `cy.origin` is not yet supported in WebKit. + +:::caution + +#### Known Incompatibilities + +Setting this configuration value to `true` can cause the application you are testing +to behave in unexpected ways. This is especially true if a site your tests visit +sets the [`Origin-Agent-Cluster`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster) +header. + +At this point in time, we are aware of the following sites that cannot be tested properly +if this option is set to `true`: + +- Azure AD B2C authentication workflows +- Salesforce +- Google + +::: + +:::cypress-config-example + +```js +{ + e2e: { + injectDocumentDomain: true + } +} +``` + +::: + ### isInteractive You can open Cypress in the interactive mode via the `cypress open` command, and @@ -714,26 +763,27 @@ DEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-conte ## History -| Version | Changes | -| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| [13.16.0](/app/references/changelog#13-16-0) | Added `defaultBrowser` option. | -| [13.4.0](/app/references/changelog#13-4-0) | Added support for configuring the Experimental Flake Detection strategy via `retries.experimentalStrategy` and `retries.experimentalOptions`. | -| [13.0.0](/app/references/changelog#13-0-0) | Removed `nodeVersion` option. | -| [13.0.0](/app/references/changelog#13-0-0) | Removed `videoUploadOnPasses` option. | -| [11.0.0](/app/references/changelog#11-0-0) | Removed `e2e.experimentalSessionAndOrigin` option. | -| [10.4.0](/app/references/changelog#10-4-0) | Added `e2e.testIsolation` option. | -| [10.0.0](/app/references/changelog#10-0-0) | Reworked page to support new `cypress.config.js` and deprecated `cypress.json` files. | -| [8.7.0](/app/references/changelog#8-7-0) | Added `slowTestThreshold` option. | -| [8.0.0](/app/references/changelog#8-0-0) | Added `clientCertificates` option and removed `firefoxGcInterval` configuration. | -| [7.0.0](/app/references/changelog#7-0-0) | Added `e2e` and `component` options. | -| [7.0.0](/app/references/changelog#7-0-0) | Added `redirectionLimit` option. | -| [6.1.0](/app/references/changelog#6-1-0) | Added `scrollBehavior` option. | -| [5.2.0](/app/references/changelog#5-2-0) | Added `includeShadowDom` option. | -| [5.0.0](/app/references/changelog#5-0-0) | Added `retries` configuration. | -| [5.0.0](/app/references/changelog#5-0-0) | Renamed `blacklistHosts` configuration to `blockHosts`. | -| [4.1.0](/app/references/changelog#4-12-0) | Added `screenshotOnRunFailure` configuration. | -| [4.0.0](/app/references/changelog#4-0-0) | Added `firefoxGcInterval` configuration. | -| [3.5.0](/app/references/changelog#3-5-0) | Added `nodeVersion` configuration. | +| Version | Changes | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [14.0.0](/app/references/changelog#14-0-0) | Added support for re-enabling superdomain navigation with the `injectDocumentDomain` configuration option | +| [13.16.0](/app/references/changelog#13-16-0) | Added `defaultBrowser` option. +| [13.4.0](/app/references/changelog#13-4-0) | Added support for configuring the Experimental Flake Detection strategy via `retries.experimentalStrategy` and `retries.experimentalOptions`. | +| [13.0.0](/app/references/changelog#13-0-0) | Removed `nodeVersion` option. | +| [13.0.0](/app/references/changelog#13-0-0) | Removed `videoUploadOnPasses` option. | +| [11.0.0](/app/references/changelog#11-0-0) | Removed `e2e.experimentalSessionAndOrigin` option. | +| [10.4.0](/app/references/changelog#10-4-0) | Added `e2e.testIsolation` option. | +| [10.0.0](/app/references/changelog#10-0-0) | Reworked page to support new `cypress.config.js` and deprecated `cypress.json` files. | +| [8.7.0](/app/references/changelog#8-7-0) | Added `slowTestThreshold` option. | +| [8.0.0](/app/references/changelog#8-0-0) | Added `clientCertificates` option and removed `firefoxGcInterval` configuration. | +| [7.0.0](/app/references/changelog#7-0-0) | Added `e2e` and `component` options. | +| [7.0.0](/app/references/changelog#7-0-0) | Added `redirectionLimit` option. | +| [6.1.0](/app/references/changelog#6-1-0) | Added `scrollBehavior` option. | +| [5.2.0](/app/references/changelog#5-2-0) | Added `includeShadowDom` option. | +| [5.0.0](/app/references/changelog#5-0-0) | Added `retries` configuration. | +| [5.0.0](/app/references/changelog#5-0-0) | Renamed `blacklistHosts` configuration to `blockHosts`. | +| [4.1.0](/app/references/changelog#4-12-0) | Added `screenshotOnRunFailure` configuration. | +| [4.0.0](/app/references/changelog#4-0-0) | Added `firefoxGcInterval` configuration. | +| [3.5.0](/app/references/changelog#3-5-0) | Added `nodeVersion` configuration. | ## See also diff --git a/docs/app/references/experiments.mdx b/docs/app/references/experiments.mdx index 71316b7774..5058186fef 100644 --- a/docs/app/references/experiments.mdx +++ b/docs/app/references/experiments.mdx @@ -257,63 +257,11 @@ creating `e2e` and `component` objects inside your Cypress configuration. These experiments are available to be specified inside the `e2e` configuration object: -| Option | Default | Description | -| --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- | -| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. | -| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | -| `experimentalOriginDependencies` | `false` | Enables support for `Cypress.require` within `cy.origin`. | -| `experimentalSkipDomainInjection` | `null` | Removes injecting `document.domain` into `text/html` pages for any sites that match the provided patterns. | - -#### Experimental Skip Domain Injection - -Under the hood, Cypress -[injects document.domain](/app/guides/cross-origin-testing#What-Cypress-does-under-the-hood) -into your test application to lessen the burden of navigation. This is well -described in our [Cross Origin Testing](/app/guides/cross-origin-testing) -guide. However, some sites have compatibility issues with this feature. - -The `experimentalSkipDomainInjection` option disables injecting -`document.domain` inside Cypress. When enabled, all cross-origin/subdomain -navigation must use `cy.origin()`, which may make tests a bit more verbose. We -only recommend including your site pattern if you are having issues running -Cypress out of the box and suspect setting `document.domain` is interfering with -your site's ability to render properly. - -Before enabling, verify your application is not implementing frame busting -techniques, which you can mitigate with the -[`modifyObstructiveCode`](/app/references/configuration#modifyObstructiveCode) -and -[`experimentalModifyObstructiveThirdPartyCode`](/app/guides/cross-origin-testing#Modifying-Obstructive-Third-Party-Code) -flags. - -At this point in time, we are aware of the following sites that require the -`experimentalSkipDomainInjection` option to be set to be tested properly: - -- Google -- Salesforce - -This flag can be enabled by passing an array of origin URLs or -[minimatch](https://github.com/isaacs/minimatch) glob patterns: - -:::cypress-config-example - -```js -{ - e2e: { - experimentalSkipDomainInjection: [ - '*.salesforce.com', - '*.force.com', - '*.google.com', - ] - } -} -``` - -::: - -If using other Salesforce domains, such as -[enhanced domains](https://help.salesforce.com/s/articleView?id=sf.domain_name_enhanced.htm&type=5), -you will need to add the correct matching glob pattern. +| Option | Default | Description | +| -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. | +| `experimentalRunAllSpecs` | `false` | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. | +| `experimentalOriginDependencies` | `false` | Enables support for `Cypress.require` within `cy.origin`. | ### Component Testing diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx index 26368544d9..808406b3f1 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -33,6 +33,52 @@ Starting in Cypress 14, Cypress will officially support [the latest 3 major vers Older browser versions may still work with Cypress, but we recommend keeping your browsers up to date to ensure compatibility with Cypress. +### Changes to `cy.origin()` + +To account for Chrome's [impending deprecation](https://developer.chrome.com/blog/document-domain-setter-deprecation) of setting `document.domain`, and to support sites that use [origin-keyed agent clusters](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster), +Cypress no longer injects `document.domain` into `text/html` content by default. + +Because of this, tests that visit more than one origin (defined as a composite of the URL _scheme_, _hostname_, and _port_) must now use `cy.origin()`. +Without `cy.origin()`, interacting with a second origin in the same test will cause the test to fail, even if the two origins +are in the same superdomain. This means you must now use `cy.origin()` in more situations than before. + + **Failing Test** ```js cy.visit('https://www.cypress.io') +cy.visit('https://docs.cypress.io') cy.get('[role="banner"]').should('be.visible') +// Cypress will not be able to interact with the page, causing the test to fail ``` + + **Fixed Test** ```js cy.visit('https://www.cypress.io') +cy.visit('https://docs.cypress.io') cy.origin('https://docs.cypress.io', () => {cy + .get('[role="banner"]') + .should('be.visible')} +) ``` + +:::info + +To ease this transition, Cypress v14.0 introduced the ["injectDocumentDomain" configuration option](/app/references/configuration#injectDocumentDomain). When this option +is set to true, `cy.origin()` will not be required to navigate between origins, as long as the superdomain matches. + + If `injectDocumentDomain` is set to `true`, +Cypress will warn that this option is deprecated. + + `injectDocumentDomain` will be removed in Cypress +15. + + Setting `injectDocumentDomain` to `true` may +cause certain sites to stop working in Cypress. Please read the [configuration notes](/app/references/configuration#injectDocumentDomain) +before use. + + If your test suites require `experimentalWebKitSupport`, +`injectDocumentDomain` must be set to `true`. + + Chrome may remove support for `document.domain` +at any time; if this configuration option is enabled, Cypress may cease to work in +Chrome at any time. If this occurs, Chrome will raise an issue in its developer tools +indicating that the deprecated `document.domain` is in use. To resolve this issue, +set the `injectDocumentDomain` option to `false` and issue any newly necessary `cy.origin()` +commands.{' '} + +::: + ### Deprecation of `resourceType` on `cy.intercept` The `resourceType` option on [`cy.intercept`](/api/commands/intercept) has been deprecated in Cypress 14.0.0. We anticipate the types of the `resourceType` to change in the future or be completely removed @@ -68,7 +114,6 @@ If you would like to disable JIT compilation, you can do so by setting [`justInT For users with the existing `experimentalJustInTimeCompile` flag set, you can remove this flag from your configuration. - ### React `<18` CT no longer supported With [LTS ending](https://github.com/reactjs/react.dev/issues/1745#issuecomment-466767389) for React 16 and 17 several years ago, the minimum required React version for component testing is now `18.0.0`. diff --git a/docs/partials/_document-domain-workaround.mdx b/docs/partials/_document-domain-workaround.mdx index b1972f97f4..cd677f5064 100644 --- a/docs/partials/_document-domain-workaround.mdx +++ b/docs/partials/_document-domain-workaround.mdx @@ -1,12 +1,24 @@ :::caution - **Disabling document.domain Injection** + **Re-Enabling document.domain Injection** -In some cases, `document.domain` injection may cause issues. As of Cypress -[v12.4.0](https://on.cypress.io/changelog#12-4-0), disabling `document.domain` -injection is available with the `experimentalSkipDomainInjection` option. Please -read about this -[experiment](/app/references/experiments#Experimental-Skip-Domain-Injection) -for more information +As of Cypress [v14.0.0], [`document.domain`](https://developer.mozilla.org/en-US/docs/Web/API/Document/domain) +will no longer be injected into `text/html` pages by default. -::: +This means you must now use `cy.origin()` when navigating between different _origins_ +in the same test. Previously, `cy.origin()` was only necessary when navigating between +different [superdomains](/app/guides/cross-origin-testing#Parts-of-a-URL) in the same test. + +By setting the `injectDocumentDomain` configuration option to `true`, Cypress will +attempt to inject `document.domain` into `text/html` pages. + +A superdomain is comprised of the trailing two elements of the hostname, delimited by +a `.` (period). Given `https://www.cypress.io`, the superdomain is determined to be +`cypress.io`. When this option is enabled, `cy.origin()` is not necessary when navigating +between `https://www.cypress.io` and `https://docs.cypress.io`, but is necessary +when navigating between `https://www.cypress.io` and `https://www.auth0.com`. + +- This will cause issues with certain sites, especially those that use + [origin-keyed agent cluster](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster)s. +- This option is deprecated, and will be removed in Cypress 15. + :::