Skip to content

Commit 8a0185f

Browse files
mschilemschile
authored
docs: remove experimentalSessionAndOrigin (#4807)
1 parent 293d8f2 commit 8a0185f

File tree

8 files changed

+89
-168
lines changed

8 files changed

+89
-168
lines changed

‎content/_changelogs/11.0.0.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@ _Released MM/DD/YYYY_
44

55
**Breaking Changes:**
66

7+
- `experimentalSessionAndOrigin` flag has been removed and all functionality is
8+
on by default now.
9+
- `testIsolation` defaults to `strict` now.
710
- `Cookies.defaults` and `Cookies.preserveOnce` have been removed. Please update
811
to use [`cy.session()`](/api/commands/session) to preserve session details
912
between tests. Addresses

‎content/api/commands/origin.md

Lines changed: 2 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -13,34 +13,6 @@ limitation determined by standard web security features of the browser. The
1313

1414
<Alert type="warning">
1515

16-
<strong class="alert-header"><Icon name="exclamation-triangle"></Icon>
17-
Experimental</strong>
18-
19-
The `cy.origin()` command is currently experimental and can be enabled by
20-
setting
21-
the [`experimentalSessionAndOrigin`](/guides/references/experiments) flag
22-
to `true` in the Cypress config.
23-
24-
Enabling this flag does the following:
25-
26-
- It adds the [`cy.session()`](/api/commands/session) and `cy.origin()`
27-
commands, and [`Cypress.session`](/api/cypress-api/session) API.
28-
- It adds the following new behaviors (that will be the default in a future
29-
major version release of Cypress) at the beginning of each test:
30-
- The page is cleared (by setting it to `about:blank`).
31-
- All active session data (cookies, `localStorage` and `sessionStorage`)
32-
across all domains are cleared.
33-
- Cross-origin requests will now succeed, however, to interact with a
34-
cross-origin page you must use a `cy.origin` block.
35-
36-
Because the page is cleared before each
37-
test, [`cy.visit()`](/api/commands/visit) must be explicitly called in each test
38-
to visit a page in your application.
39-
40-
</Alert>
41-
42-
<Alert type="warning">
43-
4416
<strong class="alert-header"><Icon name="exclamation-triangle"></Icon>
4517
Obstructive Third Party Code</strong>
4618

@@ -338,9 +310,8 @@ performant. Up until now you could get around this problem by putting login code
338310
in the first test of your file, then performing subsequent tests reusing the
339311
same session.
340312

341-
However, once the `experimentalSessionAndOrigin` flag is activated, this is no
342-
longer possible, since all session state is now cleared between tests. So to
343-
avoid this overhead we recommend you leverage the
313+
However, this is no longer possible, since all session state is now cleared
314+
between tests. So to avoid this overhead we recommend you leverage the
344315
[`cy.session()`](/api/commands/session) command, which allows you to easily
345316
cache session information and reuse it across tests. So now let's enhance our
346317
custom login command with `cy.session()` for a complete syndicated login flow
@@ -383,81 +354,6 @@ and reuse it across tests.
383354

384355
## Notes
385356

386-
### Migrating existing tests
387-
388-
Enabling the `experimentalSessionAndOrigin` flag makes the test-runner work
389-
slightly differently, and some test suites that rely on the existing behaviour
390-
may have to be updated. The most important of these changes is **test
391-
isolation**. This means that after every test, the current page is reset to
392-
`about:blank` and all active session data
393-
(cookies, `localStorage` and `sessionStorage`) across all domains are cleared.
394-
This change is opt-in for now, but will be standardized in a future major
395-
release of Cypress, so eventually all tests will need to be isolated.
396-
397-
Before this change, it was possible to write tests such that you could, for
398-
example, log in to a CMS in the first test, change some content in the second
399-
test, verify the new version is displayed on a different URL in the third, and
400-
log out in the fourth. Here's a simplified example of such a test strategy.
401-
402-
<Badge type="danger">Before</Badge> Multiple small tests against different
403-
origins
404-
405-
```js
406-
it('logs in', () => {
407-
cy.visit('https://supersecurelogons.com')
408-
cy.get('input#password').type('Password123!')
409-
cy.get('button#submit').click()
410-
})
411-
412-
it('updates the content', () => {
413-
cy.get('#current-user').contains('logged in')
414-
cy.get('button#edit-1').click()
415-
cy.get('input#title').type('Updated title')
416-
cy.get('button#submit').click()
417-
cy.get('.toast').type('Changes saved!')
418-
})
419-
420-
it('validates the change', () => {
421-
cy.visit('/items/1')
422-
cy.get('h1').contains('Updated title')
423-
})
424-
```
425-
426-
After switching on `experimentalSessionAndOrigin`, this flow would need to be
427-
contained within a single test. While this practice has always been
428-
[discouraged](/guides/references/best-practices#Having-tests-rely-on-the-state-of-previous-tests)
429-
we know some users have historically written tests this way, often to get around
430-
the same-origin restrictions. But with `cy.origin()` you no longer need these
431-
kind of brittle hacks, as your multi-origin logic can all reside in a single
432-
test, like the following.
433-
434-
<Badge type="success">After</Badge> One big test using `cy.origin()`
435-
436-
```js
437-
it('securely edits content', () => {
438-
cy.origin('supersecurelogons.com', () => {
439-
cy.visit('https://supersecurelogons.com')
440-
cy.get('input#password').type('Password123!')
441-
cy.get('button#submit').click()
442-
})
443-
444-
cy.origin('mycms.com', () => {
445-
cy.url().should('contain', 'cms')
446-
cy.get('#current-user').contains('logged in')
447-
cy.get('button#edit-1').click()
448-
cy.get('input#title').type('Updated title')
449-
cy.get('button#submit').click()
450-
cy.get('.toast').type('Changes saved!')
451-
})
452-
453-
cy.visit('/items/1')
454-
cy.get('h1').contains('Updated title')
455-
})
456-
```
457-
458-
Always remember,
459-
[Cypress tests are not unit tests](https://docs.cypress.io/guides/references/best-practices#Creating-tiny-tests-with-a-single-assertion).
460-
461357
### Serialization
462358

463359
When entering a `cy.origin()` block, Cypress injects itself at runtime, with all

‎content/api/commands/session.md

Lines changed: 0 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -9,36 +9,6 @@ and
99
[`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
1010
in order to reduce test setup times.
1111

12-
<Alert type="warning">
13-
14-
<strong class="alert-header"><Icon name="exclamation-triangle"></Icon>
15-
Experimental</strong>
16-
17-
The `session` API is currently experimental, and can be enabled by setting the
18-
[`experimentalSessionAndOrigin`](/guides/references/experiments) option to
19-
`true` in the Cypress config.
20-
21-
Enabling this flag does the following:
22-
23-
- It adds the `cy.session()` and [`cy.origin()`](/api/commands/origin) commands,
24-
and [`Cypress.session`](/api/cypress-api/session) API.
25-
- It adds the following new behaviors (that will be the default in a future
26-
major update of Cypress) at the beginning of each test:
27-
- The page is cleared (by setting it to `about:blank`). Disable this by
28-
setting
29-
[`testIsolation=legacy`](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation).
30-
- All active session data (cookies, `localStorage` and `sessionStorage`)
31-
across all domains are cleared.
32-
- Cross-origin navigation will no longer fail immediately, but instead, time out
33-
based on [`pageLoadTimeout`](/guides/references/configuration#Timeouts).
34-
- Tests will no longer wait on page loads before moving on to the next test.
35-
36-
Because the page is cleared at the beginning of each test,
37-
[`cy.visit()`](/api/commands/visit) must be explicitly called at the beginning
38-
of each test.
39-
40-
</Alert>
41-
4212
## Syntax
4313

4414
```javascript

‎content/api/commands/visit.md

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -415,23 +415,12 @@ pass.</li></List>
415415

416416
## Visiting cross-origin sites
417417

418-
<Alert type="warning">
419-
420-
<strong class="alert-header"><Icon name="exclamation-triangle"></Icon>
421-
Experimental</strong>
422-
423-
Visiting cross-origin sites will currently throw an error. It can be enabled by
424-
setting
425-
the [`experimentalSessionAndOrigin`](/guides/references/experiments) flag
426-
to `true` in the Cypress config. This will allow you to visit the cross-origin
427-
site without errors. However, to interact with the content on the cross-origin
428-
site, you must use a [`cy.origin()`](/api/commands/origin) block.
418+
After visiting a cross-origin site, to interact with the content, you must use a
419+
[`cy.origin()`](/api/commands/origin) block.
429420

430421
When visiting a cross-origin site, the `onBeforeLoad` and `onLoad` options are
431422
not supported.
432423

433-
</Alert>
434-
435424
## Command Log
436425

437426
**_Visit example application in a `beforeEach`_**
@@ -455,6 +444,7 @@ following:
455444

456445
| Version | Changes |
457446
| --------------------------------------------- | -------------------------------------------------------------------------------- |
447+
| [11.0.0](/guides/references/changelog#11-0-0) | Removed `experimentalSessionAndOrigin` reference |
458448
| [3.5.0](/guides/references/changelog#3-5-0) | Added support for options `qs` |
459449
| [3.3.0](/guides/references/changelog#3-3-0) | Added support for options `retryOnStatusCodeFailure` and `retryOnNetworkFailure` |
460450
| [3.2.0](/guides/references/changelog#3-2-0) | Added options `url`, `method`, `body`, and `headers` |

‎content/guides/core-concepts/writing-and-organizing-tests.md

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -598,18 +598,6 @@ When in `legacy` mode, Cypress handles resetting the state for:
598598

599599
#### Strict Mode
600600

601-
<Alert type="warning">
602-
603-
<strong class="alert-header"><Icon name="exclamation-triangle"></Icon>
604-
Experimental</strong>
605-
606-
`strict` mode is currently experimental and can be enabled by setting
607-
the [`experimentalSessionAndOrigin`](/guides/references/experiments) flag
608-
to `true` in the Cypress config. This is the default test isolation behavior
609-
when using the `experimentalSessionAndOrigin` experiment.
610-
611-
</Alert>
612-
613601
When in `strict` mode, Cypress handles resetting the state for everything
614602
outlined above for `legacy` mode, in addition to clearing the page by visiting
615603
`about:blank` before each test. This clears the dom's state and non-persistent

‎content/guides/references/configuration.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -207,9 +207,8 @@ object:
207207
| `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) |
208208
| `specPattern` | `cypress/e2e/**/*.cy.{js,jsx,ts,tsx}` | A String or Array of glob patterns of the test files to load. |
209209
| `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) |
210-
| `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. |
211210
| `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. |
212-
| `testIsolation` | `legacy` | The [test isolation level](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation) applied to ensure a clean slate between tests. |
211+
| `testIsolation` | `legacy` | The [test isolation level](/guides/core-concepts/writing-and-organizing-tests#Test-Isolation) applied to ensure a clean slate between tests. |
213212

214213
:::cypress-config-example{noJson}
215214

@@ -851,6 +850,7 @@ DEBUG=cypress:cli,cypress:server:specs
851850

852851
| Version | Changes |
853852
| --------------------------------------------- | ------------------------------------------------------------------------------------- |
853+
| [11.0.0](/guides/references/changelog#11-0-0) | Removed `e2e.experimentalSessionAndOrigin` option. |
854854
| [10.4.0](/guides/references/changelog#10-4-0) | Added `e2e.testIsolation` option. |
855855
| [10.0.0](/guides/references/changelog#10-0-0) | Reworked page to support new `cypress.config.js` and deprecated `cypress.json` files. |
856856
| [8.7.0](/guides/references/changelog#8-7-0) | Added `slowTestThreshold` option. |

‎content/guides/references/experiments.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,10 +39,9 @@ creating `e2e` and `component` objects inside your Cypress configuration.
3939
These experiments are available to be specified inside the `e2e` configuration
4040
object:
4141

42-
| Option | Default | Description |
43-
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
44-
| `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. |
45-
| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. |
42+
| Option | Default | Description |
43+
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
44+
| `experimentalStudio` | `false` | Generate and save commands directly to your test suite by interacting with your app as an end user would. |
4645

4746
### Component Testing
4847

@@ -57,7 +56,8 @@ configuration object:
5756

5857
| Version | Changes |
5958
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
60-
| [10.8.0](/guides/references/changelog#10-x-y) | Added `experimentalWebKitSupport`. |
59+
| [11.0.0](/guides/references/changelog#11-0-0) | Removed `experimentalSessionAndOrigin`. |
60+
| [10.8.0](/guides/references/changelog#10-8-0) | Added `experimentalWebKitSupport`. |
6161
| [10.6.0](/guides/references/changelog#10-6-0) | Added support for `experimentalSingleTabRunMode`. |
6262
| [10.4.0](/guides/references/changelog#10-4-0) | Added support for `experimentalModifyObstructiveThirdPartyCode`. |
6363
| [9.6.0](/guides/references/changelog#9-6-0) | Added support for `experimentalSessionAndOrigin` and removed `experimentalSessionSupport`. |

‎content/guides/references/migration-guide.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,80 @@ title: Migration Guide
44

55
<DocsVideo src="https://youtube.com/embed/mIqKNhLlPcU"></DocsVideo>
66

7+
## Migrating to Cypress version 11.0
8+
9+
This guide details the changes and how to change your code to migrate to Cypress
10+
version 11.0.
11+
[See the full changelog for version 11.0](/guides/references/changelog#11-0-0).
12+
13+
### Test Isolation
14+
15+
The `testIsolation` config option defaults to `strict`. This means that after
16+
every test, the current page is reset to `about:blank` and all active session
17+
data (cookies, `localStorage` and `sessionStorage`) across all domains are
18+
cleared. Some test suites that rely on the previous behavior may have to be
19+
updated.
20+
21+
Before this change, it was possible to write tests such that you could, for
22+
example, log in to a CMS in the first test, change some content in the second
23+
test, verify the new version is displayed on a different URL in the third, and
24+
log out in the fourth. Here's a simplified example of such a test strategy.
25+
26+
<Badge type="danger">Before</Badge> Multiple small tests against different
27+
origins
28+
29+
```js
30+
it('logs in', () => {
31+
cy.visit('https://supersecurelogons.com')
32+
cy.get('input#password').type('Password123!')
33+
cy.get('button#submit').click()
34+
})
35+
it('updates the content', () => {
36+
cy.get('#current-user').contains('logged in')
37+
cy.get('button#edit-1').click()
38+
cy.get('input#title').type('Updated title')
39+
cy.get('button#submit').click()
40+
cy.get('.toast').type('Changes saved!')
41+
})
42+
it('validates the change', () => {
43+
cy.visit('/items/1')
44+
cy.get('h1').contains('Updated title')
45+
})
46+
```
47+
48+
After migrating, this flow would need to be contained within a single test.
49+
While the above practice has always been
50+
[discouraged](/guides/references/best-practices#Having-tests-rely-on-the-state-of-previous-tests)
51+
we know some users have historically written tests this way, often to get around
52+
the same-origin restrictions. But with `cy.origin()` you no longer need these
53+
kind of brittle hacks, as your multi-origin logic can all reside in a single
54+
test, like the following.
55+
56+
<Badge type="success">After</Badge> One big test using `cy.origin()`
57+
58+
```js
59+
it('securely edits content', () => {
60+
cy.origin('supersecurelogons.com', () => {
61+
cy.visit('https://supersecurelogons.com')
62+
cy.get('input#password').type('Password123!')
63+
cy.get('button#submit').click()
64+
})
65+
cy.origin('mycms.com', () => {
66+
cy.url().should('contain', 'cms')
67+
cy.get('#current-user').contains('logged in')
68+
cy.get('button#edit-1').click()
69+
cy.get('input#title').type('Updated title')
70+
cy.get('button#submit').click()
71+
cy.get('.toast').type('Changes saved!')
72+
})
73+
cy.visit('/items/1')
74+
cy.get('h1').contains('Updated title')
75+
})
76+
```
77+
78+
Always remember,
79+
[Cypress tests are not unit tests](https://docs.cypress.io/guides/references/best-practices#Creating-tiny-tests-with-a-single-assertion).
80+
781
## Migrating to Cypress version 10.0
882

983
This guide details the changes and how to change your code to migrate to Cypress

0 commit comments

Comments
 (0)