diff --git a/content/_changelogs/11.0.0.md b/content/_changelogs/11.0.0.md index e7ea147337..8d98cee796 100644 --- a/content/_changelogs/11.0.0.md +++ b/content/_changelogs/11.0.0.md @@ -4,6 +4,9 @@ _Released MM/DD/YYYY_ **Breaking Changes:** +- `experimentalSessionAndOrigin` flag has been removed and all functionality is + on by default now. +- `testIsolation` defaults to `strict` now. - `Cookies.defaults` and `Cookies.preserveOnce` have been removed. Please update to use [`cy.session()`](/api/commands/session) to preserve session details between tests. Addresses diff --git a/content/api/commands/origin.md b/content/api/commands/origin.md index b690b87838..385a54ab13 100755 --- a/content/api/commands/origin.md +++ b/content/api/commands/origin.md @@ -13,34 +13,6 @@ limitation determined by standard web security features of the browser. The - -Experimental - -The `cy.origin()` command is currently experimental and can be enabled by -setting -the [`experimentalSessionAndOrigin`](/guides/references/experiments) flag -to `true` in the Cypress config. - -Enabling this flag does the following: - -- It adds the [`cy.session()`](/api/commands/session) and `cy.origin()` - commands, and [`Cypress.session`](/api/cypress-api/session) API. -- It adds the following new behaviors (that will be the default in a future - major version release of Cypress) at the beginning of each test: - - The page is cleared (by setting it to `about:blank`). - - All active session data (cookies, `localStorage` and `sessionStorage`) - across all domains are cleared. -- Cross-origin requests will now succeed, however, to interact with a - cross-origin page you must use a `cy.origin` block. - -Because the page is cleared before each -test, [`cy.visit()`](/api/commands/visit) must be explicitly called in each test -to visit a page in your application. - - - - - Obstructive Third Party Code @@ -338,9 +310,8 @@ performant. Up until now you could get around this problem by putting login code in the first test of your file, then performing subsequent tests reusing the same session. -However, once the `experimentalSessionAndOrigin` flag is activated, this is no -longer possible, since all session state is now cleared between tests. So to -avoid this overhead we recommend you leverage the +However, this is no longer possible, since all session state is now cleared +between tests. So to avoid this overhead we recommend you leverage the [`cy.session()`](/api/commands/session) command, which allows you to easily cache session information and reuse it across tests. So now let's enhance our custom login command with `cy.session()` for a complete syndicated login flow @@ -383,81 +354,6 @@ and reuse it across tests. ## Notes -### Migrating existing tests - -Enabling the `experimentalSessionAndOrigin` flag makes the test-runner work -slightly differently, and some test suites that rely on the existing behaviour -may have to be updated. The most important of these changes is **test -isolation**. This means that after every test, the current page is reset to -`about:blank` and all active session data -(cookies, `localStorage` and `sessionStorage`) across all domains are cleared. -This change is opt-in for now, but will be standardized in a future major -release of Cypress, so eventually all tests will need to be isolated. - -Before this change, it was possible to write tests such that you could, for -example, log in to a CMS in the first test, change some content in the second -test, verify the new version is displayed on a different URL in the third, and -log out in the fourth. Here's a simplified example of such a test strategy. - -Before Multiple small tests against different -origins - -```js -it('logs in', () => { - cy.visit('https://supersecurelogons.com') - cy.get('input#password').type('Password123!') - cy.get('button#submit').click() -}) - -it('updates the content', () => { - cy.get('#current-user').contains('logged in') - cy.get('button#edit-1').click() - cy.get('input#title').type('Updated title') - cy.get('button#submit').click() - cy.get('.toast').type('Changes saved!') -}) - -it('validates the change', () => { - cy.visit('/items/1') - cy.get('h1').contains('Updated title') -}) -``` - -After switching on `experimentalSessionAndOrigin`, this flow would need to be -contained within a single test. While this practice has always been -[discouraged](/guides/references/best-practices#Having-tests-rely-on-the-state-of-previous-tests) -we know some users have historically written tests this way, often to get around -the same-origin restrictions. But with `cy.origin()` you no longer need these -kind of brittle hacks, as your multi-origin logic can all reside in a single -test, like the following. - -After One big test using `cy.origin()` - -```js -it('securely edits content', () => { - cy.origin('supersecurelogons.com', () => { - cy.visit('https://supersecurelogons.com') - cy.get('input#password').type('Password123!') - cy.get('button#submit').click() - }) - - cy.origin('mycms.com', () => { - cy.url().should('contain', 'cms') - cy.get('#current-user').contains('logged in') - cy.get('button#edit-1').click() - cy.get('input#title').type('Updated title') - cy.get('button#submit').click() - cy.get('.toast').type('Changes saved!') - }) - - cy.visit('/items/1') - cy.get('h1').contains('Updated title') -}) -``` - -Always remember, -[Cypress tests are not unit tests](https://docs.cypress.io/guides/references/best-practices#Creating-tiny-tests-with-a-single-assertion). - ### Serialization When entering a `cy.origin()` block, Cypress injects itself at runtime, with all diff --git a/content/api/commands/session.md b/content/api/commands/session.md index 4be6ecefac..b3b67941ea 100644 --- a/content/api/commands/session.md +++ b/content/api/commands/session.md @@ -9,36 +9,6 @@ and [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) in order to reduce test setup times. - - - -Experimental - -The `session` API is currently experimental, and can be enabled by setting the -[`experimentalSessionAndOrigin`](/guides/references/experiments) option to -`true` in the Cypress config. - -Enabling this flag does the following: - -- It adds the `cy.session()` and [`cy.origin()`](/api/commands/origin) commands, - and [`Cypress.session`](/api/cypress-api/session) API. -- It adds the following new behaviors (that will be the default in a future - major update of Cypress) at the beginning of each test: - - The page is cleared (by setting it to `about:blank`). Disable this by - setting - [`testIsolation=legacy`](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation). - - All active session data (cookies, `localStorage` and `sessionStorage`) - across all domains are cleared. -- Cross-origin navigation will no longer fail immediately, but instead, time out - based on [`pageLoadTimeout`](/guides/references/configuration#Timeouts). -- Tests will no longer wait on page loads before moving on to the next test. - -Because the page is cleared at the beginning of each test, -[`cy.visit()`](/api/commands/visit) must be explicitly called at the beginning -of each test. - - - ## Syntax ```javascript diff --git a/content/api/commands/visit.md b/content/api/commands/visit.md index 197d5c64a7..201b740a9e 100644 --- a/content/api/commands/visit.md +++ b/content/api/commands/visit.md @@ -415,23 +415,12 @@ pass. ## Visiting cross-origin sites - - - -Experimental - -Visiting cross-origin sites will currently throw an error. It can be enabled by -setting -the [`experimentalSessionAndOrigin`](/guides/references/experiments) flag -to `true` in the Cypress config. This will allow you to visit the cross-origin -site without errors. However, to interact with the content on the cross-origin -site, you must use a [`cy.origin()`](/api/commands/origin) block. +After visiting a cross-origin site, to interact with the content, you must use a +[`cy.origin()`](/api/commands/origin) block. When visiting a cross-origin site, the `onBeforeLoad` and `onLoad` options are not supported. - - ## Command Log **_Visit example application in a `beforeEach`_** @@ -455,6 +444,7 @@ following: | Version | Changes | | --------------------------------------------- | -------------------------------------------------------------------------------- | +| [11.0.0](/guides/references/changelog#11-0-0) | Removed `experimentalSessionAndOrigin` reference | | [3.5.0](/guides/references/changelog#3-5-0) | Added support for options `qs` | | [3.3.0](/guides/references/changelog#3-3-0) | Added support for options `retryOnStatusCodeFailure` and `retryOnNetworkFailure` | | [3.2.0](/guides/references/changelog#3-2-0) | Added options `url`, `method`, `body`, and `headers` | diff --git a/content/guides/core-concepts/writing-and-organizing-tests.md b/content/guides/core-concepts/writing-and-organizing-tests.md index b0c148a9c5..c96cc7d28d 100644 --- a/content/guides/core-concepts/writing-and-organizing-tests.md +++ b/content/guides/core-concepts/writing-and-organizing-tests.md @@ -598,18 +598,6 @@ When in `legacy` mode, Cypress handles resetting the state for: #### Strict Mode - - - -Experimental - -`strict` mode is currently experimental and can be enabled by setting -the [`experimentalSessionAndOrigin`](/guides/references/experiments) flag -to `true` in the Cypress config. This is the default test isolation behavior -when using the `experimentalSessionAndOrigin` experiment. - - - When in `strict` mode, Cypress handles resetting the state for everything outlined above for `legacy` mode, in addition to clearing the page by visiting `about:blank` before each test. This clears the dom's state and non-persistent diff --git a/content/guides/references/configuration.md b/content/guides/references/configuration.md index ee1dd53c9d..7c9a9b6bd8 100644 --- a/content/guides/references/configuration.md +++ b/content/guides/references/configuration.md @@ -207,9 +207,8 @@ object: | `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) | -| `experimentalSessionAndOrigin` | `false` | Enables cross-origin and improved session support, including the [`cy.origin()`](/api/commands/origin) and [`cy.session()`](/api/commands/session) commands. This enables `testIsolation=strict` by default. Only available in end-to-end testing. | | `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` | `legacy` | The [test isolation level](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation) applied to ensure a clean slate between tests. | +| `testIsolation` | `legacy` | The [test isolation level](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation) applied to ensure a clean slate between tests. | :::cypress-config-example{noJson} @@ -851,6 +850,7 @@ DEBUG=cypress:cli,cypress:server:specs | Version | Changes | | --------------------------------------------- | ------------------------------------------------------------------------------------- | +| [11.0.0](/guides/references/changelog#11-0-0) | Removed `e2e.experimentalSessionAndOrigin` option. | | [10.4.0](/guides/references/changelog#10-4-0) | Added `e2e.testIsolation` option. | | [10.0.0](/guides/references/changelog#10-0-0) | Reworked page to support new `cypress.config.js` and deprecated `cypress.json` files. | | [8.7.0](/guides/references/changelog#8-7-0) | Added `slowTestThreshold` option. | diff --git a/content/guides/references/experiments.md b/content/guides/references/experiments.md index 35866e4a88..8a2028976a 100644 --- a/content/guides/references/experiments.md +++ b/content/guides/references/experiments.md @@ -39,10 +39,9 @@ creating `e2e` and `component` objects inside your Cypress configuration. These experiments are available to be specified inside the `e2e` configuration object: -| Option | Default | Description | -| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `experimentalSessionAndOrigin` | `false` | Enables cross-origin and improved session support, including the [`cy.origin()`](/api/commands/origin) and [`cy.session()`](/api/commands/session) commands. This enables `testIsolation=strict` by default. | -| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. | +| Option | Default | Description | +| -------------------- | ------- | --------------------------------------------------------------------------------------------------------- | +| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. | ### Component Testing @@ -57,7 +56,8 @@ configuration object: | Version | Changes | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| [10.8.0](/guides/references/changelog#10-x-y) | Added `experimentalWebKitSupport`. | +| [11.0.0](/guides/references/changelog#11-0-0) | Removed `experimentalSessionAndOrigin`. | +| [10.8.0](/guides/references/changelog#10-8-0) | Added `experimentalWebKitSupport`. | | [10.6.0](/guides/references/changelog#10-6-0) | Added support for `experimentalSingleTabRunMode`. | | [10.4.0](/guides/references/changelog#10-4-0) | Added support for `experimentalModifyObstructiveThirdPartyCode`. | | [9.6.0](/guides/references/changelog#9-6-0) | Added support for `experimentalSessionAndOrigin` and removed `experimentalSessionSupport`. | diff --git a/content/guides/references/migration-guide.md b/content/guides/references/migration-guide.md index 766a621539..04669859c6 100644 --- a/content/guides/references/migration-guide.md +++ b/content/guides/references/migration-guide.md @@ -4,6 +4,80 @@ title: Migration Guide +## Migrating to Cypress version 11.0 + +This guide details the changes and how to change your code to migrate to Cypress +version 11.0. +[See the full changelog for version 11.0](/guides/references/changelog#11-0-0). + +### Test Isolation + +The `testIsolation` config option defaults to `strict`. This means that after +every test, the current page is reset to `about:blank` and all active session +data (cookies, `localStorage` and `sessionStorage`) across all domains are +cleared. Some test suites that rely on the previous behavior may have to be +updated. + +Before this change, it was possible to write tests such that you could, for +example, log in to a CMS in the first test, change some content in the second +test, verify the new version is displayed on a different URL in the third, and +log out in the fourth. Here's a simplified example of such a test strategy. + +Before Multiple small tests against different +origins + +```js +it('logs in', () => { + cy.visit('https://supersecurelogons.com') + cy.get('input#password').type('Password123!') + cy.get('button#submit').click() +}) +it('updates the content', () => { + cy.get('#current-user').contains('logged in') + cy.get('button#edit-1').click() + cy.get('input#title').type('Updated title') + cy.get('button#submit').click() + cy.get('.toast').type('Changes saved!') +}) +it('validates the change', () => { + cy.visit('/items/1') + cy.get('h1').contains('Updated title') +}) +``` + +After migrating, this flow would need to be contained within a single test. +While the above practice has always been +[discouraged](/guides/references/best-practices#Having-tests-rely-on-the-state-of-previous-tests) +we know some users have historically written tests this way, often to get around +the same-origin restrictions. But with `cy.origin()` you no longer need these +kind of brittle hacks, as your multi-origin logic can all reside in a single +test, like the following. + +After One big test using `cy.origin()` + +```js +it('securely edits content', () => { + cy.origin('supersecurelogons.com', () => { + cy.visit('https://supersecurelogons.com') + cy.get('input#password').type('Password123!') + cy.get('button#submit').click() + }) + cy.origin('mycms.com', () => { + cy.url().should('contain', 'cms') + cy.get('#current-user').contains('logged in') + cy.get('button#edit-1').click() + cy.get('input#title').type('Updated title') + cy.get('button#submit').click() + cy.get('.toast').type('Changes saved!') + }) + cy.visit('/items/1') + cy.get('h1').contains('Updated title') +}) +``` + +Always remember, +[Cypress tests are not unit tests](https://docs.cypress.io/guides/references/best-practices#Creating-tiny-tests-with-a-single-assertion). + ## Migrating to Cypress version 10.0 This guide details the changes and how to change your code to migrate to Cypress