{
  "doc": {
    "id": "app/core-concepts/test-isolation",
    "title": "Test isolation in Cypress",
    "description": "Learn how Cypress ensures test isolation and how to configure test isolation in end-to-end and component testing.",
    "section": "app",
    "source_path": "/llm/markdown/app/core-concepts/test-isolation.md",
    "version": "f60251bf707b0077a9535579c9f90d615440cc35",
    "updated_at": "2026-10-16T10:56:58.670Z",
    "headings": [
      {
        "id": "app/core-concepts/test-isolation#test-isolation",
        "text": "Test Isolation",
        "level": 1
      },
      {
        "id": "app/core-concepts/test-isolation#test-isolation-in-end-to-end-testing",
        "text": "Test Isolation in End-to-End Testing",
        "level": 2
      },
      {
        "id": "app/core-concepts/test-isolation#test-isolation-enabled",
        "text": "Test Isolation Enabled",
        "level": 3
      },
      {
        "id": "app/core-concepts/test-isolation#test-isolation-disabled",
        "text": "Test Isolation Disabled",
        "level": 3
      },
      {
        "id": "app/core-concepts/test-isolation#quick-comparison",
        "text": "Quick Comparison",
        "level": 3
      },
      {
        "id": "app/core-concepts/test-isolation#test-isolation-in-component-testing",
        "text": "Test Isolation in Component Testing",
        "level": 2
      },
      {
        "id": "app/core-concepts/test-isolation#storage-that-is-not-cleared",
        "text": "Storage That Is Not Cleared",
        "level": 2
      },
      {
        "id": "app/core-concepts/test-isolation#clearing-indexeddb-yourself",
        "text": "Clearing IndexedDB yourself",
        "level": 3
      },
      {
        "id": "app/core-concepts/test-isolation#preserving-cookies-and-storage-across-tests",
        "text": "Preserving Cookies and Storage Across Tests",
        "level": 2
      },
      {
        "id": "app/core-concepts/test-isolation#re-set-a-known-cookie-in-beforeeach",
        "text": "Re-set a known cookie in beforeEach",
        "level": 3
      },
      {
        "id": "app/core-concepts/test-isolation#cache-server-set-cookies-with-cy-session",
        "text": "Cache server-set cookies with cy.session()",
        "level": 3
      },
      {
        "id": "app/core-concepts/test-isolation#disable-test-isolation-for-a-suite",
        "text": "Disable test isolation for a suite",
        "level": 3
      },
      {
        "id": "app/core-concepts/test-isolation#test-isolation-trade-offs",
        "text": "Test Isolation Trade-offs",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "app/core-concepts/test-isolation#test-isolation-in-end-to-end-testing",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Test Isolation in End-to-End Testing",
      "heading_level": 2,
      "content_markdown": "## Test Isolation in End-to-End Testing\n\nCypress supports enabling or disabling test isolation in end-to-end testing to describe if a suite of tests should run in a clean browser context or not.\n\n### Test Isolation Enabled\n\nWhen test isolation is enabled, Cypress resets the browser context _before_ each test by:\n\n*   clearing the dom state by visiting `about:blank`\n*   clearing [cookies](/llm/markdown/api/cypress-api/cookies.md) in all domains\n*   clearing [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) in all domains\n*   clearing [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) in all domains\n\nIndexedDB and other browser storage mechanisms are not cleared, even when test isolation is enabled. See [Storage That Is Not Cleared](#Storage-That-Is-Not-Cleared).\n\nBecause the test starts in a fresh browser context, you must re-visit your application and perform the series of interactions needed to build the dom and browser state for each test.\n\nAdditionally, the [`cy.session()`](/llm/markdown/api/commands/session.md) command will inherit this configuration and will clear the page and current browser context when establishing a browser session. This is so tests can reliably pass when run standalone or in a randomized order.\n\n### Test Isolation Disabled\n\nWhen test isolation is disabled, Cypress will not alter the browser context before the test starts. The page does not clear between tests and cookies, local storage, and session storage will be available across tests in that suite. Additionally, the [`cy.session()`](/llm/markdown/api/commands/session.md) command will only clear the current browser context when establishing the browser session - the current page is not cleared.\n\n### Quick Comparison\n\n| testIsolation | beforeEach test | cy.session() |\n| --- | --- | --- |\n| `true` | \\- clears page by visiting `about:blank`  \n\\- clears cookies in all domains  \n\\- local storage in all domains  \n\\- session storage in all domains | \\- clears page by visiting `about:blank`  \n\\- clears cookies in all domains  \n\\- local storage in all domains  \n\\- session storage in all domains |\n| `false` | does not alter the current browser context |   \n\\- clears cookies in all domains  \n\\- local storage in all domains  \n\\- session storage in all domains |\n",
      "section": "app",
      "anchors": [
        "test-isolation-in-end-to-end-testing"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 441
    },
    {
      "id": "app/core-concepts/test-isolation#test-isolation-enabled",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Test Isolation Enabled",
      "heading_level": 3,
      "content_markdown": "### Test Isolation Enabled\n\nWhen test isolation is enabled, Cypress resets the browser context _before_ each test by:\n\n*   clearing the dom state by visiting `about:blank`\n*   clearing [cookies](/llm/markdown/api/cypress-api/cookies.md) in all domains\n*   clearing [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) in all domains\n*   clearing [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) in all domains\n\nIndexedDB and other browser storage mechanisms are not cleared, even when test isolation is enabled. See [Storage That Is Not Cleared](#Storage-That-Is-Not-Cleared).\n\nBecause the test starts in a fresh browser context, you must re-visit your application and perform the series of interactions needed to build the dom and browser state for each test.\n\nAdditionally, the [`cy.session()`](/llm/markdown/api/commands/session.md) command will inherit this configuration and will clear the page and current browser context when establishing a browser session. This is so tests can reliably pass when run standalone or in a randomized order.\n",
      "section": "app",
      "anchors": [
        "test-isolation-enabled"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 177
    },
    {
      "id": "app/core-concepts/test-isolation#test-isolation-disabled",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Test Isolation Disabled",
      "heading_level": 3,
      "content_markdown": "### Test Isolation Disabled\n\nWhen test isolation is disabled, Cypress will not alter the browser context before the test starts. The page does not clear between tests and cookies, local storage, and session storage will be available across tests in that suite. Additionally, the [`cy.session()`](/llm/markdown/api/commands/session.md) command will only clear the current browser context when establishing the browser session - the current page is not cleared.\n",
      "section": "app",
      "anchors": [
        "test-isolation-disabled"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 87
    },
    {
      "id": "app/core-concepts/test-isolation#quick-comparison",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Quick Comparison",
      "heading_level": 3,
      "content_markdown": "### Quick Comparison\n\n| testIsolation | beforeEach test | cy.session() |\n| --- | --- | --- |\n| `true` | \\- clears page by visiting `about:blank`  \n\\- clears cookies in all domains  \n\\- local storage in all domains  \n\\- session storage in all domains | \\- clears page by visiting `about:blank`  \n\\- clears cookies in all domains  \n\\- local storage in all domains  \n\\- session storage in all domains |\n| `false` | does not alter the current browser context |   \n\\- clears cookies in all domains  \n\\- local storage in all domains  \n\\- session storage in all domains |\n",
      "section": "app",
      "anchors": [
        "quick-comparison"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 135
    },
    {
      "id": "app/core-concepts/test-isolation#test-isolation-in-component-testing",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Test Isolation in Component Testing",
      "heading_level": 2,
      "content_markdown": "## Test Isolation in Component Testing\n\nCypress does not support configuring the test isolation behavior in component testing.\n\nWhen running component tests, Cypress always resets the browser context _before_ each test by:\n\n*   unmounting the rendered component under test\n*   clearing [cookies](/llm/markdown/api/cypress-api/cookies.md) in all domains\n*   clearing [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) in all domains\n*   clearing [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) in all domains\n",
      "section": "app",
      "anchors": [
        "test-isolation-in-component-testing"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 76
    },
    {
      "id": "app/core-concepts/test-isolation#storage-that-is-not-cleared",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Storage That Is Not Cleared",
      "heading_level": 2,
      "content_markdown": "## Storage That Is Not Cleared\n\nCookies, `localStorage`, and `sessionStorage` are the only browser storage mechanisms Cypress clears between tests. Every other storage mechanism persists for the life of the browser, whether test isolation is enabled or disabled, and whether you are running end-to-end tests or component tests.\n\nThe one to be most aware of is [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). Data your application writes to IndexedDB, including data written by libraries that use it under the hood such as offline caches and client-side databases, is still there in the next test. If a test depends on IndexedDB being empty, clear it yourself.\n\nThe same applies to [`cy.session()`](/llm/markdown/api/commands/session.md): a session caches and restores cookies, `localStorage`, and `sessionStorage` only, so IndexedDB data is neither saved with a session nor cleared when one is restored.\n\n### Clearing IndexedDB yourself\n\nDelete the databases your application uses in a `beforeEach` hook, after visiting the page so a `window` is available:\n\ncypress/support/e2e.js\n\n```\nbeforeEach(() => {\n  cy.visit('/')\n  cy.window().then((win) => {\n    return new Cypress.Promise((resolve) => {\n      const request = win.indexedDB.deleteDatabase('my-database')\n\n      // resolve on every outcome so a missing or blocked\n      // database does not hang the test\n      request.onsuccess = resolve\n      request.onerror = resolve\n      request.onblocked = resolve\n    })\n  })\n})\n```\n\nIf you do not know the database names ahead of time, and you only run your tests in Chromium-based browsers or WebKit, you can enumerate them with [`indexedDB.databases()`](https://developer.mozilla.org/en-US/docs/Web/API/IDBFactory/databases). Firefox does not implement that method, so name each database explicitly if you run your tests in Firefox.\n",
      "section": "app",
      "anchors": [
        "storage-that-is-not-cleared"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 328
    },
    {
      "id": "app/core-concepts/test-isolation#clearing-indexeddb-yourself",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Clearing IndexedDB yourself",
      "heading_level": 3,
      "content_markdown": "### Clearing IndexedDB yourself\n\nDelete the databases your application uses in a `beforeEach` hook, after visiting the page so a `window` is available:\n\ncypress/support/e2e.js\n\n```\nbeforeEach(() => {\n  cy.visit('/')\n  cy.window().then((win) => {\n    return new Cypress.Promise((resolve) => {\n      const request = win.indexedDB.deleteDatabase('my-database')\n\n      // resolve on every outcome so a missing or blocked\n      // database does not hang the test\n      request.onsuccess = resolve\n      request.onerror = resolve\n      request.onblocked = resolve\n    })\n  })\n})\n```\n\nIf you do not know the database names ahead of time, and you only run your tests in Chromium-based browsers or WebKit, you can enumerate them with [`indexedDB.databases()`](https://developer.mozilla.org/en-US/docs/Web/API/IDBFactory/databases). Firefox does not implement that method, so name each database explicitly if you run your tests in Firefox.\n",
      "section": "app",
      "anchors": [
        "clearing-indexeddb-yourself"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 156
    },
    {
      "id": "app/core-concepts/test-isolation#preserving-cookies-and-storage-across-tests",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Preserving Cookies and Storage Across Tests",
      "heading_level": 2,
      "content_markdown": "## Preserving Cookies and Storage Across Tests\n\nBecause Cypress clears all cookies, `localStorage`, and `sessionStorage` before each test when test isolation is enabled, state your application writes to those three mechanisms is gone by the next test. There are three approaches for keeping specific state available across tests. State in other storage mechanisms, such as IndexedDB, already persists on its own and needs none of them.\n\n### Re-set a known cookie in `beforeEach`\n\nIf you know the cookie value ahead of time — for example, a cookie-consent acceptance or a feature flag — use [`cy.setCookie()`](/llm/markdown/api/commands/setcookie.md) inside a `beforeEach` hook so the cookie is present at the start of every test:\n\n```\n// cypress/support/e2e.js  (or inside a describe block)\nbeforeEach(() => {\n  cy.setCookie('cookieConsent', 'accepted')\n})\n```\n\n### Cache server-set cookies with `cy.session()`\n\nIf your cookie is generated by the server after a login, use [`cy.session()`](/llm/markdown/api/commands/session.md) to capture the full browser context once and restore it before each subsequent test — without repeating the login flow:\n\n```\n// cypress/support/commands.js\nCypress.Commands.add('login', (username, password) => {\n  cy.session([username, password], () => {\n    cy.visit('/login')\n    cy.get('[data-test=username]').type(username)\n    cy.get('[data-test=password]').type(password)\n    cy.get('form').contains('Log In').click()\n    cy.url().should('contain', '/dashboard')\n  })\n})\n\n// In your spec or support file\nbeforeEach(() => {\n  cy.login('myuser', 'password123')\n  cy.visit('/dashboard')\n})\n```\n\n`cy.session()` restores all cookies (and localStorage / sessionStorage) that were present when the session was first created, so server-set auth cookies are available in every test without a full login round-trip.\n\n### Disable test isolation for a suite\n\nYou can turn off test isolation for a specific `describe` block by setting `testIsolation: false`. State set in a `before` hook then persists across all tests in that suite:\n\n```\ndescribe('Marketing pages', { testIsolation: false }, () => {\n  before(() => {\n    cy.setCookie('cookieConsent', 'accepted')\n    cy.visit('/home')\n  })\n\n  it('shows the home page', () => {\n    // cookieConsent cookie is present; page is already loaded\n  })\n\n  it('shows the about page', () => {\n    cy.visit('/about')\n    // cookieConsent cookie is still present\n  })\n})\n```\n\nDisabling test isolation means tests may affect each other's state. Verify that each test still passes when run in isolation (using `.only()`) before relying on this approach.\n",
      "section": "app",
      "anchors": [
        "preserving-cookies-and-storage-across-tests"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 461
    },
    {
      "id": "app/core-concepts/test-isolation#re-set-a-known-cookie-in-beforeeach",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Re-set a known cookie in beforeEach",
      "heading_level": 3,
      "content_markdown": "### Re-set a known cookie in `beforeEach`\n\nIf you know the cookie value ahead of time — for example, a cookie-consent acceptance or a feature flag — use [`cy.setCookie()`](/llm/markdown/api/commands/setcookie.md) inside a `beforeEach` hook so the cookie is present at the start of every test:\n\n```\n// cypress/support/e2e.js  (or inside a describe block)\nbeforeEach(() => {\n  cy.setCookie('cookieConsent', 'accepted')\n})\n```\n",
      "section": "app",
      "anchors": [
        "re-set-a-known-cookie-in-beforeeach"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 79
    },
    {
      "id": "app/core-concepts/test-isolation#cache-server-set-cookies-with-cy-session",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Cache server-set cookies with cy.session()",
      "heading_level": 3,
      "content_markdown": "### Cache server-set cookies with `cy.session()`\n\nIf your cookie is generated by the server after a login, use [`cy.session()`](/llm/markdown/api/commands/session.md) to capture the full browser context once and restore it before each subsequent test — without repeating the login flow:\n\n```\n// cypress/support/commands.js\nCypress.Commands.add('login', (username, password) => {\n  cy.session([username, password], () => {\n    cy.visit('/login')\n    cy.get('[data-test=username]').type(username)\n    cy.get('[data-test=password]').type(password)\n    cy.get('form').contains('Log In').click()\n    cy.url().should('contain', '/dashboard')\n  })\n})\n\n// In your spec or support file\nbeforeEach(() => {\n  cy.login('myuser', 'password123')\n  cy.visit('/dashboard')\n})\n```\n\n`cy.session()` restores all cookies (and localStorage / sessionStorage) that were present when the session was first created, so server-set auth cookies are available in every test without a full login round-trip.\n",
      "section": "app",
      "anchors": [
        "cache-server-set-cookies-with-cy-session"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 143
    },
    {
      "id": "app/core-concepts/test-isolation#disable-test-isolation-for-a-suite",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Disable test isolation for a suite",
      "heading_level": 3,
      "content_markdown": "### Disable test isolation for a suite\n\nYou can turn off test isolation for a specific `describe` block by setting `testIsolation: false`. State set in a `before` hook then persists across all tests in that suite:\n\n```\ndescribe('Marketing pages', { testIsolation: false }, () => {\n  before(() => {\n    cy.setCookie('cookieConsent', 'accepted')\n    cy.visit('/home')\n  })\n\n  it('shows the home page', () => {\n    // cookieConsent cookie is present; page is already loaded\n  })\n\n  it('shows the about page', () => {\n    cy.visit('/about')\n    // cookieConsent cookie is still present\n  })\n})\n```\n\nDisabling test isolation means tests may affect each other's state. Verify that each test still passes when run in isolation (using `.only()`) before relying on this approach.\n",
      "section": "app",
      "anchors": [
        "disable-test-isolation-for-a-suite"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 152
    },
    {
      "id": "app/core-concepts/test-isolation#test-isolation-trade-offs",
      "doc_id": "app/core-concepts/test-isolation",
      "heading": "Test Isolation Trade-offs",
      "heading_level": 2,
      "content_markdown": "## Test Isolation Trade-offs\n\nDisabling test isolation may improve the overall performance of end-to-end tests, however, it can also cause state to \"leak\" between tests. This can make later tests dependent on the results of earlier tests, and potentially cause misleading test failures. It is important to be extremely mindful of how tests are written when using this mode, and ensure that tests continue to run independently of one another.\n\nThe best way to ensure your tests are independent is to add a `.only()` to your test and verify it can run successfully without the test before it.\n",
      "section": "app",
      "anchors": [
        "test-isolation-trade-offs"
      ],
      "path": "/llm/json/chunked/app/core-concepts/test-isolation.json",
      "token_estimate": 131
    }
  ]
}