|
| 1 | +--- |
| 2 | +title: 'Test Isolation' |
| 3 | +--- |
| 4 | + |
| 5 | +<Alert type="info"> |
| 6 | + |
| 7 | +## <Icon name="graduation-cap"></Icon> What you'll learn |
| 8 | + |
| 9 | +- What is test isolation |
| 10 | +- How it impacts E2E Testing vs Component Testing |
| 11 | +- Test isolation trade-offs |
| 12 | + |
| 13 | +</Alert> |
| 14 | + |
| 15 | +## What is Test Isolation? |
| 16 | + |
| 17 | +<Alert type="success"> |
| 18 | + |
| 19 | +<Icon name="check-circle" color="green"></Icon> **Best Practice:** Tests should |
| 20 | +always be able to be run independently from one another **and still pass**. |
| 21 | + |
| 22 | +</Alert> |
| 23 | + |
| 24 | +As stated in our mission, we hold ourselves accountable to champion a testing |
| 25 | +process that actually works, and have built Cypress to guide developers towards |
| 26 | +writing independent tests from the start. |
| 27 | + |
| 28 | +We do this by cleaning up state _before_ each test to ensure that the operation |
| 29 | +of one test does not affect another test later on. The goal for each test should |
| 30 | +be to **reliably pass** whether run in isolation or consecutively with other |
| 31 | +tests. Having tests that depend on the state of an earlier test can potentially |
| 32 | +cause nondeterministic test failures which make debugging challenging. |
| 33 | + |
| 34 | +Cypress will start each test with a clean test slate by restoring and clearing |
| 35 | +all: |
| 36 | + |
| 37 | +- [aliases](/api/commands/as) |
| 38 | +- [clock mocks](/api/commands/clock) |
| 39 | +- [intercepts](/api/commands/intercept) |
| 40 | +- [routes](/api/commands/route) |
| 41 | +- [spies](/api/commands/spy) |
| 42 | +- [stubs](/api/commands/stub) |
| 43 | +- [viewport changes](/api/commands/viewport) |
| 44 | + |
| 45 | +In additional to a clean test slate, Cypress also believes in running tests in a |
| 46 | +clean browser context such that the application or component under test behaves |
| 47 | +consistently when ran. This behavior is described as `testIsolation`. |
| 48 | + |
| 49 | +The test isolation is a global configuration and can be overridden for |
| 50 | +end-to-end testing at the `describe` level with the |
| 51 | +[`testIsolation`](/guides/references/configuration#Global) option. |
| 52 | + |
| 53 | +## Test Isolation in End-to-End Testing |
| 54 | + |
| 55 | +Cypress supports enabling or disabling test isolation in end-to-end testing to |
| 56 | +describe if a suite of tests should run in a clean browser context or not. |
| 57 | + |
| 58 | +### Test Isolation Enabled |
| 59 | + |
| 60 | +When test isolation is enabled, Cypress resets the browser context _before_ each |
| 61 | +test by: |
| 62 | + |
| 63 | +- clearing the dom state by visiting `about:blank` |
| 64 | +- clearing [cookies](/api/cypress-api/cookies) in all domains |
| 65 | +- clearing |
| 66 | + [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) |
| 67 | + in all domains |
| 68 | +- clearing |
| 69 | + [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) |
| 70 | + in all domains |
| 71 | + |
| 72 | +Because the test starts in a fresh browser context, you must re-visit your |
| 73 | +application and perform the series of interactions needed to build the dom and |
| 74 | +browser state for each test. |
| 75 | + |
| 76 | +Additionally, the [`cy.session()`](/api/commands/session) command will inherent |
| 77 | +this configuration and will clear the page and current browser context when |
| 78 | +establishing a browser session. This is so tests can reliably pass when run |
| 79 | +standalone or in a randomized order. |
| 80 | + |
| 81 | +### Test Isolation Disabled |
| 82 | + |
| 83 | +When test isolation is disabled, Cypress will not alter the browser context |
| 84 | +before the test starts. The page does not clear between tests and cookies, local |
| 85 | +storage and session storage will be available across tests in that suite. |
| 86 | +Additionally, the [`cy.session()`](/api/commands/session) command will only |
| 87 | +clear the current browser context when establishing the browser session - the |
| 88 | +current page is not cleared. |
| 89 | + |
| 90 | +### Quick Comparison |
| 91 | + |
| 92 | +| testIsolation | beforeEach test | cy.session() | |
| 93 | +| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | |
| 94 | +| `true` | - clears page by visiting `about:blank`<br>- clears cookies in all domains<br>- local storage in all domains<br>- session storage in all domains | - clears page by visiting `about:blank`<br>- clears cookies in all domains<br>- local storage in all domains<br>- session storage in all domains | |
| 95 | +| `false` | does not alter the current browser context | <br>- clears cookies in all domains<br>- local storage in all domains<br>- session storage in all domains | |
| 96 | + |
| 97 | +## Test Isolation in Component Testing |
| 98 | + |
| 99 | +Cypress does not support configuring the test isolation behavior in component |
| 100 | +testing. |
| 101 | + |
| 102 | +When running component tests, Cypress always resets the browser context _before_ |
| 103 | +each test by: |
| 104 | + |
| 105 | +- unmounting the rendered component under test |
| 106 | +- clearing [cookies](/api/cypress-api/cookies) in all domains |
| 107 | +- clearing |
| 108 | + [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) |
| 109 | + in all domains |
| 110 | +- clearing |
| 111 | + [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) |
| 112 | + in all domains |
| 113 | + |
| 114 | +## Test Isolation Trade-offs |
| 115 | + |
| 116 | +It is important to note that disabling test isolation may improve the overall |
| 117 | +performance of end-to-end tests, however, it can also cause state to "leak" |
| 118 | +between tests. This can make later tests dependent on the results of earlier |
| 119 | +tests, and potentially cause misleading test failures. It is important to be |
| 120 | +extremely mindful of how tests are written when using this mode, and ensure that |
| 121 | +tests continue to run independently of one another. |
| 122 | + |
| 123 | +The best way to ensure your tests are independent is to add a `.only()` to your |
| 124 | +test and verify it can run successfully without the test before it. |
0 commit comments