10.11.0 (#4790)

* 10.11.0 * Update cy.origin dependencies / remove Cypress.require() (#4789) * update documentations around test isolation (#4797) Co-authored-by: Matt Henkes <[email protected]> Co-authored-by: Bill Glesias <[email protected]> Co-authored-by: Ryan Manuel <[email protected]> Co-authored-by: DEBRIS APRON <[email protected]> * Updating changelog * Removing duplicate changelog entry * Update content/_changelogs/10.11.0.md Co-authored-by: Matt Henkes <[email protected]> * Adding "Experimental Breaking Changes" section * Moving one issue in changelog and running prettier * Moving a few items around in the changelog * Updating changelog copy for cy.session support in Webkit Co-authored-by: Emily Rohrbough <[email protected]> Co-authored-by: Matt Henkes <[email protected]> Co-authored-by: Bill Glesias <[email protected]> Co-authored-by: Ryan Manuel <[email protected]> Co-authored-by: DEBRIS APRON <[email protected]> Co-authored-by: Stokes Player <[email protected]>
cypress-io · Oct 25, 2022 · ca6edab · ca6edab · vercel · Oct 25, 2022
1 parent a5b4736
commit ca6edab
Show file tree

Hide file tree

Showing 10 changed files with 315 additions and 201 deletions.
diff --git a/content/_changelogs/10.11.0.md b/content/_changelogs/10.11.0.md
@@ -0,0 +1,66 @@
+## 10.11.0
+
+_Released 10/25/2022_
+
+**Features:**
+
+- [`cy.session()`](/api/commands/session) is now supported when using
+  [WebKit (Experimental)](https://docs.cypress.io/guides/guides/launching-browsers#WebKit-Experimental)
+  and `experimentalSessionAndOrigin` is enabled. Addresses
+  [#24116](https://github.com/cypress-io/cypress/issues/24116),
+  [#23832](https://github.com/cypress-io/cypress/issues/23832).
+- Improves user experience when connecting a project to the Dashboard. Addresses
+  [#23379](https://github.com/cypress-io/cypress/issues/23379),
+  [#23766](https://github.com/cypress-io/cypress/issues/23766),
+  [#23767](https://github.com/cypress-io/cypress/issues/23767).
+  - Users will be prompted to connect a project to the Dashboard when logging in
+    from the Cypress Launchpad after a testing type has been selected.
+  - Users will be prompted to record runs to the Dashboard from both the Cypress
+    App and Cypress Launchpad if a project is connected to the Dashboard and has
+    no recorded runs.
+
+**Bugfixes:**
+
+- When a chromium based browser tab or process crashes, Cypress will no longer
+  hang indefinitely but will fail the current test and move on to the next.
+  [#6170](https://github.com/cypress-io/cypress/issues/6170).
+- Fixed as issue where browser-skipped tests were incorrectly recorded to the
+  Dashboard which resulted in the Dashboard marking the test as "new" or
+  "modified" when it already existed. Fixes
+  [#23517](https://github.com/cypress-io/cypress/issues/23517).
+- Fixed issue connecting to the cloud when a self-signed cert was in the cert
+  chain. Fixes [#24298](https://github.com/cypress-io/cypress/issues/24298).
+- [`cy.origin()`](/api/commands/origin) now supports more than 30 unique origin
+  spec bridges per test. Fixes
+  [#22874](https://github.com/cypress-io/cypress/issues/22874),
+  [#23967](https://github.com/cypress-io/cypress/issues/23967).
+- Fixed an issue where `document.cookie` would not reflect the correct value in
+  cross-origin tests. Fixes
+  [#23531](https://github.com/cypress-io/cypress/issues/23531).
+- Cypress will now restart on changes to the `blockHosts` configuration entry.
+  Fixes [#22634](https://github.com/cypress-io/cypress/issues/22634).
+- When shown the command to record runs to the cloud, the user can select and
+  copy parts of the command (like the record key), instead of only being able to
+  use the "Copy" button to copy the entire command. Fixes
+  [#22091](https://github.com/cypress-io/cypress/issues/22091).
+- Cleaned up inconsistencies in the UI between sentence case and title case.
+  Fixes [#21854](https://github.com/cypress-io/cypress/issues/21854).
+- Fixed an issue where there is a visible "Project ID" section (with no
+  `projectId`) when user has not connected to the Dashboard.
+  [#21806](https://github.com/cypress-io/cypress/issues/21806).
+
+**Experimental Breaking Changes:**
+
+- [`cy.origin()`](/api/commands/origin) now supports using `require()` and
+  dynamic `import()` to include dependencies. `Cypress.require()` has been
+  removed. Addresses
+  [#24293](https://github.com/cypress-io/cypress/issues/24293).
+- The way that Cypress handles
+  [test isolation](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation)
+  has changed. The previous modes of `legacy` and `strict` have been replaced
+  with `on` and `off`. Fixes
+  [#24206](https://github.com/cypress-io/cypress/issues/24206).
+  - The default mode is `on` when
+    [`experimentalSessionAndOrigin`](/guides/references/experiments) is enabled.
+  - The [cy.session()](/api/commands/session) command now inherits the test
+    isolation behavior for the suite it runs in.
diff --git a/content/_data/sidebar.json b/content/_data/sidebar.json
@@ -985,10 +985,6 @@
               "title": "platform",
               "slug": "platform"
             },
-            {
-              "title": "require",
-              "slug": "require"
-            },
             {
               "title": "session",
               "slug": "session"

diff --git a/content/api/commands/origin.md b/content/api/commands/origin.md
@@ -16,29 +16,28 @@ limitation determined by standard web security features of the browser. The
 <strong class="alert-header"><Icon name="exclamation-triangle"></Icon>
 Experimental</strong>
 
-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.
+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()`](/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.
-- It supersedes
-  the [`Cypress.Cookies.preserveOnce()`](/api/cypress-api/cookies#Preserve-Once) and
-  [`Cypress.Cookies.defaults()`](/api/cypress-api/cookies#Defaults) methods.
+- It adds the `cy.session()` and [`cy.origin()`](/api/commands/origin) commands,
+  and [`Cypress.session`](/api/cypress-api/session) API.
+- It adds the concept of
+  [`testIsolation`](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation)
+  which defaults to `on`, such that:
+  - The page is cleared (by setting it to `about:blank`).
+  - Cookies, local storage and session storage in all domains are cleared.
+- It supersedes the
+  [`Cypress.Cookies.preserveOnce()`](/api/cypress-api/cookies#Preserve-Once) and
+  [`Cypress.Cookies.defaults()`](/api/cypress-api/cookies#Defaults) methods.
 - 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.
+Because the page is cleared at the beginning of each test by default,
+[`cy.visit()`](/api/commands/visit) must be explicitly called at the beginning
+of each test.
 
 </Alert>
 
@@ -390,12 +389,12 @@ and reuse it across 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.
+may have to be updated. The most important of these changes is
+[**test isolation**]() which defaults to `on`. This means that after every test,
+the current page is reset to `about:blank` and cookies, local storage and
+session storage in all domains are cleared before each test. 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
@@ -507,27 +506,53 @@ into the callback.
 
 ### Dependencies / Sharing Code
 
-It is not possible to use
+[ES module dynamic `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports)
+and/or
 [CommonJS `require()`](https://nodejs.org/en/knowledge/getting-started/what-is-require/)
-or
-[dynamic ES module `import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#dynamic_imports)
-within the callback. However, [`Cypress.require()`](/api/cypress-api/require)
-can be utilized to include [npm](https://www.npmjs.com/) packages and other
-files. It is functionally the same as using
-[CommonJS `require()`](https://nodejs.org/en/knowledge/getting-started/what-is-require/)
-in browser-targeted code.
+can be used within the callback to include [npm](https://www.npmjs.com/)
+packages and other files.
+
+<Alert type="warning">
+
+Using `import()` and `require()` within the callback requires version 5.15.0 or
+greater of the
+[`@cypress/webpack-preprocessor`](https://github.com/cypress-io/cypress/tree/master/npm/webpack-preprocessor).
+This is included in Cypress by default, but if your project installs its own
+version of `@cypress/webpack-preprocessor` that is set up in your Cypress
+config, make sure it is version 5.15.0 or greater.
+
+If using an older version of the webpack or a different preprocessor, you'll see
+an error that includes the following text:
+
+_Using require() or import() to include dependencies requires using the latest
+version of @cypress/webpack-preprocessor._
+
+</Alert>
+
+#### Example
 
 ```js
+// ES modules
+cy.origin('somesite.com', async () => {
+  const _ = await import('lodash')
+  const utils = await import('../support/utils')
+
+  // ... use lodash and utils ...
+})
+
+// CommonJS
 cy.origin('somesite.com', () => {
-  const _ = Cypress.require('lodash')
-  const utils = Cypress.require('../support/utils')
+  const _ = require('lodash')
+  const utils = require('../support/utils')
 
   // ... use lodash and utils ...
 })
 ```
 
-`Cypress.require()` can be used to share custom commands between tests run in
-primary and secondary origins. We recommend this pattern for setting up your
+#### Custom commands
+
+This makes it possible to share custom commands between tests run in primary and
+secondary origins. We recommend this pattern for setting up your
 [support file](/guides/core-concepts/writing-and-organizing-tests#Support-file)
 and setting up custom commands to run within the `cy.origin()` callback:
 
@@ -561,7 +586,7 @@ before(() => {
   // calls in this spec. put it in your support file to make them available to
   // all specs
   cy.origin('somesite.com', () => {
-    Cypress.require('../support/commands')
+    require('../support/commands')
   })
 })
 
@@ -573,6 +598,8 @@ it('tests somesite.com', () => {
 })
 ```
 
+#### Shared execution context
+
 The JavaScript execution context is persisted between `cy.origin()` callbacks
 that share the same origin. This can be utilized to share code between
 successive `cy.origin()` calls.
@@ -582,7 +609,7 @@ before(() => {
   cy.origin('somesite.com', () => {
     // makes commands defined in this file available to all callbacks
     // for somesite.com
-    Cypress.require('../support/commands')
+    require('../support/commands')
   })
 })
 

diff --git a/content/api/commands/session.md b/content/api/commands/session.md
@@ -7,7 +7,13 @@ Cache and restore [cookies](/api/cypress-api/cookies),
 [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage),
 and
 [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
-in order to reduce test setup times.
+(i.e. session data) in order to recreate a consistent browser context between
+tests.
+
+The `cy.session()` command will inherit the
+[`testIsolation`](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation)
+mode value to determine whether or not the page is cleared when caching and
+restoring the browser context.
 
 <Alert type="warning">
 
@@ -22,20 +28,18 @@ 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.
-- It supersedes
-  the [`Cypress.Cookies.preserveOnce()`](/api/cypress-api/cookies#Preserve-Once) and
-  [`Cypress.Cookies.defaults()`](/api/cypress-api/cookies#Defaults) methods.
+- It adds the concept of
+  [`testIsolation`](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation)
+  which defaults to `on`, such that:
+  - The page is cleared (by setting it to `about:blank`).
+  - Cookies, local storage and session storage in all domains are cleared.
+- It supersedes the
+  [`Cypress.Cookies.preserveOnce()`](/api/cypress-api/cookies#Preserve-Once) and
+  [`Cypress.Cookies.defaults()`](/api/cypress-api/cookies#Defaults) methods.
 - 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 at the beginning of each test,
+Because the page is cleared at the beginning of each test by default,
 [`cy.visit()`](/api/commands/visit) must be explicitly called at the beginning
 of each test.
 
@@ -128,8 +132,11 @@ runs, Cypress will preserve all cookies, `sessionStorage`, and `localStorage`,
 so that subsequent calls to `cy.session()` with the same `id` will bypass
 `setup` and just restore the cached session data.
 
-The page and all active session data (cookies, `localStorage` and
-`sessionStorage`) across all domains are always cleared before `setup` runs.
+The page is cleared before `setup` when `testIsolation='on'` and is not cleared
+when `testIsolation='off'`.
+
+Cookies, local storage and session storage in all domains are always cleared
+before `setup` runs, regardless of the testIsolation configuration.
 
 **<Icon name="angle-right"></Icon> options** **_(Object)_**
 
@@ -331,10 +338,10 @@ describe('account details', () => {
 
 ### Switching sessions inside tests
 
-Because `cy.session()` clears the page and all active session data before
-running `setup`, you can use it to easily switch between sessions without first
-needing to log the previous user out. This allows tests to more accurately
-represent real-world scenarios and helps keep test run times short.
+Because `cy.session()` clears the page and all session data before running
+`setup`, you can use it to easily switch between sessions without first needing
+to log the previous user out. This allows tests to more accurately represent
+real-world scenarios and helps keep test run times short.
 
 ```jsx
 const login = (name) => {
@@ -669,24 +676,46 @@ it('t3', () => {
 
 ## Notes
 
-### When the page and active session data are cleared
+### When the page and session data are cleared
+
+### Test Isolation `on`
+
+The page is cleared and cookies, local storage and session storage (session
+data) in all domains are cleared automatically when `cy.session()` runs and
+`testIsolation` is `on`. This guarantees consistent behavior whether a session
+is being created or restored and allows you to switch sessions without first
+having to explicitly log out.
+
+|                            |               Page cleared (test)               |              Session data cleared               |
+| -------------------------- | :---------------------------------------------: | :---------------------------------------------: |
+| Before `setup`             | <Icon name="check-circle" color="green"></Icon> | <Icon name="check-circle" color="green"></Icon> |
+| Before `validate`          | <Icon name="check-circle" color="green"></Icon> |                                                 |
+| Before `cy.session()` ends | <Icon name="check-circle" color="green"></Icon> |                                                 |
+
+[`cy.visit()`](/api/commands/visit) must be explicitly called afterwards to
+ensure the page to test is loaded.
+
+### Test Isolation `off`
+
+When `testIsolation` is `off`, the page will not clear, however, the session
+data will clear when `cy.session()` runs.
+
+|                            | Page cleared (test) |              Session data cleared               |
+| -------------------------- | :-----------------: | :---------------------------------------------: |
+| Before `setup`             |                     | <Icon name="check-circle" color="green"></Icon> |
+| Before `validate`          |                     |                                                 |
+| Before `cy.session()` ends |                     |                                                 |
 
-The page is cleared and all active session data (cookies, `localStorage`, and
-`sessionStorage`) across all domains are cleared automatically when
-`cy.session()` runs. This guarantees consistent behavior whether a session is
-being created or restored and allows you to switch sessions without first having
-to explicitly log out.
+[`cy.visit()`](/api/commands/visit) does not need to be called afterwards to
+ensure the page to test is loaded.
 
-|                      |              Current page cleared               |           Active session data cleared           |
-| -------------------- | :---------------------------------------------: | :---------------------------------------------: |
-| Before `setup`       | <Icon name="check-circle" color="green"></Icon> | <Icon name="check-circle" color="green"></Icon> |
-| Before `validate`    | <Icon name="check-circle" color="green"></Icon> |                                                 |
-| After `cy.session()` | <Icon name="check-circle" color="green"></Icon> |                                                 |
+NOTE: Turning test isolation off may improve performance of end-to-end tests,
+however, previous tests could impact the browser state of the next test and
+cause inconsistency when using .only(). Be mindful to write isolated tests when
+test isolation is off.
 
-Calling `cy.session()` clears the current page in addition to restoring the
-cached session data. [`cy.visit()`](/api/commands/visit) must be explicitly
-called afterwards to ensure a page is visited if you did not provide a
-`validate` function that called `cy.visit()`.
+When test isolation is `off`, it is encouraged to setup your session in a before
+hook or in the first test to ensure a clean setup.
 
 ### Session caching
 
@@ -880,7 +909,7 @@ that were run when creating and/or validating the session.
 In this image, a saved session is restored, but when `/personal` is visited in
 the `validate` function, the app redirects to `/signin`, which invalidates the
 session. A new session is created by visiting `/signin` where the user is logged
-in, after which, validation succeeds, and the session is made active for the
+in, after which, validation succeeds, and the session is available for the
 remainder of the test.
 
 <DocsImage src="/img/api/session/session-expanded.png" alt="Recreated session (expanded)"></DocsImage>