From 4d7e8e662e88e2d36206de9a4094d8aa8f868d41 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Mon, 28 Oct 2024 10:08:07 -0400 Subject: [PATCH 1/7] Documents changes to cy.origin, configuration for document.domain injection removal and reversion --- docs/api/commands/origin.mdx | 31 +++++-- docs/app/guides/cross-origin-testing.mdx | 92 ++++++++----------- docs/app/references/changelog.mdx | 3 +- docs/app/references/configuration.mdx | 52 ++++++++++- docs/app/references/experiments.mdx | 53 ----------- docs/app/references/migration-guide.mdx | 39 ++++++++ docs/partials/_document-domain-workaround.mdx | 26 ++++-- 7 files changed, 170 insertions(+), 126 deletions(-) diff --git a/docs/api/commands/origin.mdx b/docs/api/commands/origin.mdx index d98a40bd00..e355afba66 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](TBD) + +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 with +the `injectDocumentDomain` configuration option, to allow a transition period. +In Cypress 15, this configuration option will be removed. + +::: + ## Syntax ```js @@ -64,7 +76,7 @@ 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 +// Origin must be a precise match including scheme, subdomain and port, i.e. https://example.cypress.io cy.origin('cypress.io', () => { cy.visit('/history/founder') cy.get('h1').contains('About our Founder') @@ -77,12 +89,14 @@ cy.get('h1').contains('My cool site under test') ### 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/guides/cross-origin-testing.mdx b/docs/app/guides/cross-origin-testing.mdx index aa4e7d5e0f..fdbda9cc84 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,38 +69,38 @@ 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 +Without `cy.origin()`, you can visit different origins in _different_ tests, +but not in the _same_ test. (ED: should this be removed, as it links to itself?) Please read our [Cross Origin Testing Guide](/app/guides/cross-origin-testing) for more information. #### 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 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 + `window.location.href = '...'`, to a different origin where additional Cypress commands are run. In each of these situations, Cypress will lose the ability to automate your @@ -113,17 +110,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,30 +122,24 @@ 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` - -The URLs below, however, will have different superdomains/origins compared to -`https://www.cypress.io`. +##### Origin -- `http://www.cypress.io` (Different protocol) -- `https://docs.cypress.io:81` (Different port) -- `https://www.auth0.com/` (Different host of different superdomain) +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`: -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. +- `https://www.cypress.io/cloud` +- `https://www.cypress.io/app` -The rules are: +But the following have different origins compared to `https://www.cypress.io`: +- `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 +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. ::: @@ -167,7 +147,7 @@ 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 origins in **different** tests without needing [`cy.origin()`](/api/commands/origin). ::: For practical purposes, this means the following: @@ -176,16 +156,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 https://docs.cypress.io doesn't match the https://www.cypress.io origin 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 +176,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 +286,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 +302,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 +320,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 +365,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 +513,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 +566,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 +576,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 002ff1d687..b6333d19ce 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -10,7 +10,8 @@ _Released 12/3/2024 (PENDING)_ - Removed support for Node.js 16 and Node.js 21. Addresses [#29930](https://github.com/cypress-io/cypress/issues/29930). - Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.28`, -for example: Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2. Addresses [#29601](https://github.com/cypress-io/cypress/issues/29601). +for example: Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2. Addresses [#29601](https://github.com/cypress-io/cypress/issues/29601). +- To better adhere to security practices, `cy.origin()` is now required when navigating between two different origins in the same test. This behavior can be disabled via the `injectDocumentDomain` configuration option, which will be removed in Cypress 15. Addresses [#29590](https://github.com/cypress-io/cypress/issues/29590). - The `experimentalJustInTimeCompile` configuration option for component testing has been replaced with a `justInTimeCompile` option that is `true` by default. This option will only compile resources directly related to your spec, compiling them 'just-in-time' before spec execution. This should result in improved memory management and performance for component tests in `cypress open` and `cypress run` modes, in particular for large component testing suites. `justInTimeCompile` is currently supported for [`webpack`](https://www.npmjs.com/package/webpack) and [`vite`](https://www.npmjs.com/package/vite). Addresses [#30234](https://github.com/cypress-io/cypress/issues/30234). Addressed in [#30402](https://github.com/cypress-io/cypress/pull/30402). diff --git a/docs/app/references/configuration.mdx b/docs/app/references/configuration.mdx index ddc9f06e5b..1733d558e3 100644 --- a/docs/app/references/configuration.mdx +++ b/docs/app/references/configuration.mdx @@ -194,7 +194,7 @@ object: | `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 ```ts @@ -588,6 +588,55 @@ 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 the next +major version of Cypress. + +Set this configuration option is `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](TBD) 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,6 +763,7 @@ DEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-conte | Version | Changes | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | +| [14.0.0](app/references/changelog#14-0-0) | Added support for re-enabling superdomain navigation with the `injectDocumentDomain` configuration 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. | diff --git a/docs/app/references/experiments.mdx b/docs/app/references/experiments.mdx index 2218e0126b..8928ae950f 100644 --- a/docs/app/references/experiments.mdx +++ b/docs/app/references/experiments.mdx @@ -261,59 +261,6 @@ object: | --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------- | | `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. ### Component Testing diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx index 0cb5aff30e..a69a289cd2 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -68,6 +68,45 @@ For users with the existing `experimentalJustInTimeCompile` flag set, you can re ::: +### Changes to `cy.origin()` + +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 enabled, Cypress will warn that this option is deprecated. + + `injectDocumentDomain` will be removed in Cypress 15. + + Enabling `injectDocumentDomain` 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`, this `injectDocumentDomain` must be enabled. + +::: + ## Migrating to Cypress 13.0 This guide details the changes and how to change your code to migrate to Cypress diff --git a/docs/partials/_document-domain-workaround.mdx b/docs/partials/_document-domain-workaround.mdx index b1972f97f4..33357e9e76 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 whe 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. ::: From bc4a1e7d21c24be9150b5ebb43d356c5ff9a495c Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Mon, 28 Oct 2024 13:20:13 -0400 Subject: [PATCH 2/7] lint and broken link fixes --- docs/api/commands/intercept.mdx | 28 ++++++------ docs/api/commands/origin.mdx | 4 +- docs/app/faq.mdx | 2 +- docs/app/guides/cross-origin-testing.mdx | 7 +-- docs/app/references/changelog.mdx | 13 +++--- docs/app/references/configuration.mdx | 37 +++++++-------- docs/app/references/experiments.mdx | 8 ++-- docs/app/references/migration-guide.mdx | 45 +++++++++---------- docs/partials/_document-domain-workaround.mdx | 8 ++-- 9 files changed, 76 insertions(+), 76 deletions(-) diff --git a/docs/api/commands/intercept.mdx b/docs/api/commands/intercept.mdx index fa12c5e47e..205565fbb9 100644 --- a/docs/api/commands/intercept.mdx +++ b/docs/api/commands/intercept.mdx @@ -130,21 +130,21 @@ glob-matched against the request using [`Cypress.minimatch`](/api/utilities/minimatch) with the `{ matchBase: true }` minimatch option applied. -| Option | Description | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| auth | HTTP Basic Authentication (`object` with keys `username` and `password`) | -| headers | HTTP request headers (`object`) | -| hostname | HTTP request hostname | -| https | `true`: only secure (https://) requests, `false`: only insecure (http://) requests | -| method | HTTP request method (matches any method by default) | -| middleware | `true`: match route first and in defined order, `false`: match route in reverse order (default) | -| path | HTTP request path after the hostname, including query parameters | -| pathname | Like `path`, but without query parameters | -| port | HTTP request port(s) (`number` or `Array`) | -| query | Parsed query string (`object`) | +| Option | Description | +| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| auth | HTTP Basic Authentication (`object` with keys `username` and `password`) | +| headers | HTTP request headers (`object`) | +| hostname | HTTP request hostname | +| https | `true`: only secure (https://) requests, `false`: only insecure (http://) requests | +| method | HTTP request method (matches any method by default) | +| middleware | `true`: match route first and in defined order, `false`: match route in reverse order (default) | +| path | HTTP request path after the hostname, including query parameters | +| pathname | Like `path`, but without query parameters | +| port | HTTP request port(s) (`number` or `Array`) | +| query | Parsed query string (`object`) | | resourceType deprecated | The resource type of the request. See ["Request object properties"](#Request-object-properties) for a list of possible values for `resourceType`. | -| times | Maximum number of times to match (`number`) | -| url | Full HTTP request URL | +| times | Maximum number of times to match (`number`) | +| url | Full HTTP request URL | See [examples](#With-RouteMatcher) below. diff --git a/docs/api/commands/origin.mdx b/docs/api/commands/origin.mdx index e355afba66..9ee0486b58 100644 --- a/docs/api/commands/origin.mdx +++ b/docs/api/commands/origin.mdx @@ -30,7 +30,7 @@ doc. :::info -Changes in Cypress [v14.0.0](TBD) +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 @@ -556,7 +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.| +| [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 8a21effffd..c7152c92be 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 fdbda9cc84..fa206e592d 100644 --- a/docs/app/guides/cross-origin-testing.mdx +++ b/docs/app/guides/cross-origin-testing.mdx @@ -124,13 +124,14 @@ chart to help clarify the differences! ##### Origin -An `origin` is comprised of a URL's `scheme`, `hostname`, *and* `port`. Given the URLs +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`: - `https://www.cypress.io/cloud` - `https://www.cypress.io/app` But the following have different origins compared to `https://www.cypress.io`: + - `http://www.cypress.io` (different `scheme`) - `https://docs.cypress.io` (different `hostname` due to the subdomain) - `https://www.auth0.com` (different `hostname`) @@ -139,8 +140,8 @@ But the following have different origins compared to `https://www.cypress.io`: :::danger You **cannot** [visit](/api/commands/visit) -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. +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. ::: diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index b6333d19ce..0454cfe68e 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -9,8 +9,8 @@ _Released 12/3/2024 (PENDING)_ **Breaking Changes:** - Removed support for Node.js 16 and Node.js 21. Addresses [#29930](https://github.com/cypress-io/cypress/issues/29930). -- Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.28`, -for example: Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2. Addresses [#29601](https://github.com/cypress-io/cypress/issues/29601). +- Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.28`, + for example: Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2. Addresses [#29601](https://github.com/cypress-io/cypress/issues/29601). - To better adhere to security practices, `cy.origin()` is now required when navigating between two different origins in the same test. This behavior can be disabled via the `injectDocumentDomain` configuration option, which will be removed in Cypress 15. Addresses [#29590](https://github.com/cypress-io/cypress/issues/29590). - The `experimentalJustInTimeCompile` @@ -23,7 +23,6 @@ for example: Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2. Addresses [#29601]( - The CSS pseudo-class `:dir()` is now supported when testing in Electron. Addresses [#29766](https://github.com/cypress-io/cypress/issues/29766). - **Dependency Updates:** - Upgraded `electron` from `27.3.10` to `32.2.0`. Addresses [#29547](https://github.com/cypress-io/cypress/issues/29547). @@ -102,8 +101,8 @@ _Released 8/27/2024_ - Added new [`experimentalJustInTimeCompile`](/app/references/experiments#Configuration) - configuration option for component testing. This option will only compile resources directly related to your spec, compiling - them 'just-in-time' before spec execution. This should result in improved memory management and performance for component + configuration option for component testing. This option will only compile resources directly related to your spec, compiling + them 'just-in-time' before spec execution. This should result in improved memory management and performance for component tests in `cypress open` and `cypress run` modes, in particular for large component testing suites. [`experimentalJustInTimeCompile`](/app/references/experiments#Configuration) is currently supported for [`webpack`](https://www.npmjs.com/package/webpack) and [`vite`](https://www.npmjs.com/package/vite). Addresses [#29244](https://github.com/cypress-io/cypress/issues/29244). - `.type({upArrow})` and `.type({downArrow})` now also works for date, month, week, time, datetime-local and range input types. Addresses [#29665](https://github.com/cypress-io/cypress/issues/29665). - Added a `CYPRESS_SKIP_VERIFY` flag to enable suppressing Cypress verification checks. Addresses [#22243](https://github.com/cypress-io/cypress/issues/22243). @@ -1420,11 +1419,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 1733d558e3..517bdc988b 100644 --- a/docs/app/references/configuration.mdx +++ b/docs/app/references/configuration.mdx @@ -184,17 +184,18 @@ 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. | -| `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)| +| 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 ```ts @@ -601,15 +602,15 @@ 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](TBD) to understand how to update your tests to remove +[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 +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 +#### 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 @@ -619,9 +620,9 @@ 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 +- Azure AD B2C authentication workflows +- Salesforce +- Google ::: @@ -763,7 +764,7 @@ DEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-conte | Version | Changes | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | -| [14.0.0](app/references/changelog#14-0-0) | Added support for re-enabling superdomain navigation with the `injectDocumentDomain` configuration option | +| [14.0.0](/app/references/changelog#14-0-0) | Added support for re-enabling superdomain navigation with the `injectDocumentDomain` configuration 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. | diff --git a/docs/app/references/experiments.mdx b/docs/app/references/experiments.mdx index 8928ae950f..87d57e6e00 100644 --- a/docs/app/references/experiments.mdx +++ b/docs/app/references/experiments.mdx @@ -257,10 +257,10 @@ 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. | +| 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. | ### Component Testing diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx index a69a289cd2..0c88afaf99 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -19,12 +19,12 @@ on your system. version 16 and 21 will no longer be supported when installing Cypress. The minimum Node.js version supported to install Cypress is Node.js 18+. -### Unsupported Linux Distributions +### Unsupported Linux Distributions Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.28`. This support is inline with Node.js's support for Linux in 18+. -If you're using a Linux distribution based on glibc `<2.28`, for example, Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2, you'll need to +If you're using a Linux distribution based on glibc `<2.28`, for example, Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2, you'll need to update your system to a newer version to install Cypress. ### Updated Browser Support @@ -39,10 +39,10 @@ The `resourceType` option on `cy.intercept` has been deprecated in Cypress 14.0. We anticipate the types of the `resourceType` to change in the future or be completely removed from the API. The future implementation of `resourceType` is dependent on decisions made in the WebDriver BiDi specification for `resourceType`. -If you're using `resourceType` in your tests, please leave feedback on which `resourceType` values are important to you +If you're using `resourceType` in your tests, please leave feedback on which `resourceType` values are important to you in this [GitHub issue](https://github.com/cypress-io/cypress/issues/30447). -### Just in Time Compile Changes for Component Testing +### Just in Time Compile Changes for Component Testing In Cypress 13.14.0, we released an experimental flag, `experimentalJustInTimeCompile`, to enable Just in Time (JIT) compilation for Component Testing. The response from this change @@ -72,38 +72,37 @@ For users with the existing `experimentalJustInTimeCompile` flag set, you can re 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()`. +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 -``` + **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') -}) -``` + **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 enabled, Cypress will warn that this option is deprecated. + If `injectDocumentDomain` is enabled, Cypress +will warn that this option is deprecated. - `injectDocumentDomain` will be removed in Cypress 15. + `injectDocumentDomain` will be removed in Cypress +15. - Enabling `injectDocumentDomain` may cause certain sites to stop working in Cypress. Please read the [configuration notes](/app/references/configuration#injectDocumentDomain) before use. + Enabling `injectDocumentDomain` 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`, this `injectDocumentDomain` must be enabled. + If your test suites require `experimentalWebKitSupport`, +this `injectDocumentDomain` must be enabled. ::: diff --git a/docs/partials/_document-domain-workaround.mdx b/docs/partials/_document-domain-workaround.mdx index 33357e9e76..3c4010ed5a 100644 --- a/docs/partials/_document-domain-workaround.mdx +++ b/docs/partials/_document-domain-workaround.mdx @@ -5,7 +5,7 @@ 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* +This means you must now use `cy.origin()` when navigating between different _origins_ in the same test. Previously, `cy.origin()` was only necessary whe navigating between different [superdomains](/app/guides/cross-origin-testing#Parts-of-a-URL) in the same test. @@ -19,6 +19,6 @@ 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. -::: + [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. + ::: From 9a8aa773031a3bc02870a71c3557569c10641024 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Mon, 28 Oct 2024 15:03:29 -0400 Subject: [PATCH 3/7] lint --- docs/api/commands/origin.mdx | 2 +- docs/app/references/configuration.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/commands/origin.mdx b/docs/api/commands/origin.mdx index 9ee0486b58..8e3d073745 100644 --- a/docs/api/commands/origin.mdx +++ b/docs/api/commands/origin.mdx @@ -556,7 +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. | +| [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/references/configuration.mdx b/docs/app/references/configuration.mdx index 517bdc988b..ae2163e1da 100644 --- a/docs/app/references/configuration.mdx +++ b/docs/app/references/configuration.mdx @@ -764,7 +764,7 @@ DEBUG=cypress:cli,cypress:data-context:sources:FileDataSource,cypress:data-conte | Version | Changes | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | -| [14.0.0](/app/references/changelog#14-0-0) | Added support for re-enabling superdomain navigation with the `injectDocumentDomain` configuration option | +| [14.0.0](/app/references/changelog#14-0-0) | Added support for re-enabling superdomain navigation with the `injectDocumentDomain` configuration 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. | From 644aa612b9a136472c6f1be955f49458f3770b70 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Thu, 19 Dec 2024 10:31:41 -0500 Subject: [PATCH 4/7] address code review comments: typos, clarification --- docs/api/commands/origin.mdx | 6 +++--- docs/app/guides/cross-origin-testing.mdx | 14 ++++++-------- docs/app/references/configuration.mdx | 2 +- docs/app/references/experiments.mdx | 1 + docs/app/references/migration-guide.mdx | 14 ++++++++++---- docs/partials/_document-domain-workaround.mdx | 2 +- 6 files changed, 22 insertions(+), 17 deletions(-) diff --git a/docs/api/commands/origin.mdx b/docs/api/commands/origin.mdx index 8e3d073745..ed958ba602 100644 --- a/docs/api/commands/origin.mdx +++ b/docs/api/commands/origin.mdx @@ -34,9 +34,9 @@ doc. 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 with -the `injectDocumentDomain` configuration option, to allow a transition period. -In Cypress 15, this configuration option will be removed. +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. ::: diff --git a/docs/app/guides/cross-origin-testing.mdx b/docs/app/guides/cross-origin-testing.mdx index fa206e592d..8f2a07dbd2 100644 --- a/docs/app/guides/cross-origin-testing.mdx +++ b/docs/app/guides/cross-origin-testing.mdx @@ -88,20 +88,18 @@ 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 origins in _different_ tests, -but not in the _same_ test. (ED: should this be removed, as it links to itself?) Please read our -[Cross Origin Testing Guide](/app/guides/cross-origin-testing) for more -information. +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 origin with subsequent Cypress commands being run. 2. [`.submit()`](/api/commands/submit) a `` that causes your web server to - redirect you a different origin 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 origin 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 @@ -148,7 +146,7 @@ the use of the [`cy.origin()`](/api/commands/origin) command. :::tip You **can** [visit](/api/commands/visit) -two or origins 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: @@ -163,7 +161,7 @@ it('navigates', () => { ``` ```javascript -// this will error because https://docs.cypress.io doesn't match the https://www.cypress.io origin +// 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://docs.cypress.io') diff --git a/docs/app/references/configuration.mdx b/docs/app/references/configuration.mdx index ad22a90403..6918b3e9ae 100644 --- a/docs/app/references/configuration.mdx +++ b/docs/app/references/configuration.mdx @@ -595,7 +595,7 @@ or [`component`](#component) testing-specific options. This option is deprecated, and will be removed in the next major version of Cypress. -Set this configuration option is `true` to instruct Cypress to +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 diff --git a/docs/app/references/experiments.mdx b/docs/app/references/experiments.mdx index 87d57e6e00..5f3f103cb8 100644 --- a/docs/app/references/experiments.mdx +++ b/docs/app/references/experiments.mdx @@ -261,6 +261,7 @@ object: | ------------------------- | ------- | --------------------------------------------------------------------------------------------------------- | | `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 39b09622c6..34e56dc861 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -75,7 +75,8 @@ For users with the existing `experimentalJustInTimeCompile` flag set, you can re ### Changes to `cy.origin()` -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. +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 @@ -96,18 +97,23 @@ cy.visit('https://docs.cypress.io') cy.origin('https://docs.cypress.io', () => { 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 enabled, Cypress + If `injectDocumentDomain` is set to `true`, Cypress will warn that this option is deprecated. `injectDocumentDomain` will be removed in Cypress 15. - Enabling `injectDocumentDomain` may cause certain + 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`, -this `injectDocumentDomain` must be enabled. + `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. ::: diff --git a/docs/partials/_document-domain-workaround.mdx b/docs/partials/_document-domain-workaround.mdx index 3c4010ed5a..cd677f5064 100644 --- a/docs/partials/_document-domain-workaround.mdx +++ b/docs/partials/_document-domain-workaround.mdx @@ -6,7 +6,7 @@ As of Cypress [v14.0.0], [`document.domain`](https://developer.mozilla.org/en-US 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 whe navigating between +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 From f9805599e404f3a3ef029ee7c27aff8680b762ac Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Fri, 20 Dec 2024 13:29:59 -0500 Subject: [PATCH 5/7] lint --- docs/app/references/experiments.mdx | 10 +++++----- docs/app/references/migration-guide.mdx | 21 ++++++++++++--------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/app/references/experiments.mdx b/docs/app/references/experiments.mdx index 37c05ae14d..86184c65e6 100644 --- a/docs/app/references/experiments.mdx +++ b/docs/app/references/experiments.mdx @@ -257,11 +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`. | +| 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 c3cb1bf4bf..98bcebc624 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -97,25 +97,28 @@ cy.visit('https://docs.cypress.io') cy.origin('https://docs.cypress.io', () => { 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. + 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) + 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`. +`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. + 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.{' '} ::: + ### Vue 2 / Nuxt 2 Component Testing is no longer supported [Vue 2 reached end-of-life on December 31st, 2023](https://v2.vuejs.org/eol/). With Cypress 14, Cypress no longer ships the Vue 2 component testing harness with the Cypress binary. From c7ff618f07b0163ea6eaaa6a07f3d5ac1ccff021 Mon Sep 17 00:00:00 2001 From: Cacie Prins Date: Fri, 20 Dec 2024 15:10:06 -0500 Subject: [PATCH 6/7] Update docs/app/references/configuration.mdx Co-authored-by: Bill Glesias --- docs/app/references/configuration.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/app/references/configuration.mdx b/docs/app/references/configuration.mdx index a379c5ceb0..5e505c8303 100644 --- a/docs/app/references/configuration.mdx +++ b/docs/app/references/configuration.mdx @@ -592,8 +592,7 @@ or [`component`](#component) testing-specific options. ### injectDocumentDomain -This option is deprecated, and will be removed in the next -major version of Cypress. +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) From 3fd87bf4b8b5a7edff3810c6170bdee3a3c4b6e3 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Mon, 23 Dec 2024 16:46:58 -0500 Subject: [PATCH 7/7] update example in cyorigin --- docs/api/commands/origin.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/api/commands/origin.mdx b/docs/api/commands/origin.mdx index ed958ba602..9d8f5f89e9 100644 --- a/docs/api/commands/origin.mdx +++ b/docs/api/commands/origin.mdx @@ -75,16 +75,16 @@ 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') -// Origin must be a precise match including scheme, subdomain and port, i.e. https://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