{
  "doc": {
    "id": "api/commands/window",
    "title": "cy.window()",
    "description": "Get the window object of the page that is currently active in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/window.md",
    "version": "29f95bf8bb06f320986f3749f5bf09a35a409eab",
    "updated_at": "2026-09-04T10:49:54.630Z",
    "headings": [
      {
        "id": "api/commands/window#window",
        "text": "window",
        "level": 1
      },
      {
        "id": "api/commands/window#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/window#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/window#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/window#yields",
        "text": "Yields",
        "level": 3
      },
      {
        "id": "api/commands/window#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/window#no-args",
        "text": "No Args",
        "level": 3
      },
      {
        "id": "api/commands/window#yield-the-remote-window-object",
        "text": "Yield the remote window object",
        "level": 4
      },
      {
        "id": "api/commands/window#check-a-custom-property",
        "text": "Check a custom property",
        "level": 4
      },
      {
        "id": "api/commands/window#typescript-custom-window-properties",
        "text": "TypeScript: custom window properties",
        "level": 4
      },
      {
        "id": "api/commands/window#start-tests-when-app-is-ready",
        "text": "Start tests when app is ready",
        "level": 3
      },
      {
        "id": "api/commands/window#options",
        "text": "Options",
        "level": 3
      },
      {
        "id": "api/commands/window#passes-timeout-through-to-should-assertion",
        "text": "Passes timeout through to .should() assertion",
        "level": 4
      },
      {
        "id": "api/commands/window#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/window#cypress-uses-2-different-windows",
        "text": "Cypress uses 2 different windows.",
        "level": 3
      },
      {
        "id": "api/commands/window#rules",
        "text": "Rules",
        "level": 2
      },
      {
        "id": "api/commands/window#requirements",
        "text": "Requirements",
        "level": 3
      },
      {
        "id": "api/commands/window#assertions",
        "text": "Assertions",
        "level": 3
      },
      {
        "id": "api/commands/window#timeouts",
        "text": "Timeouts",
        "level": 3
      },
      {
        "id": "api/commands/window#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/window#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/window#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "chunks": [
    {
      "id": "api/commands/window#syntax",
      "doc_id": "api/commands/window",
      "heading": "Syntax",
      "heading_level": 2,
      "content_markdown": "## Syntax\n\n```\ncy.window()\ncy.window(options)\n```\n\n### Usage\n\n**Correct Usage**\n\n```\ncy.window()\n```\n\n### Arguments\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.window()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.window()` to resolve before [timing out](#Timeouts) |\n\n### Yields\n\n*   `cy.window()` yields the `window` object.\n*   `cy.window()` is a query, and it is _safe_ to chain further commands.\n",
      "section": "api",
      "anchors": [
        "syntax"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 124
    },
    {
      "id": "api/commands/window#arguments",
      "doc_id": "api/commands/window",
      "heading": "Arguments",
      "heading_level": 3,
      "content_markdown": "### Arguments\n\n**options _(Object)_**\n\nPass in an options object to change the default behavior of `cy.window()`.\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log) |\n| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `cy.window()` to resolve before [timing out](#Timeouts) |\n",
      "section": "api",
      "anchors": [
        "arguments"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 79
    },
    {
      "id": "api/commands/window#examples",
      "doc_id": "api/commands/window",
      "heading": "Examples",
      "heading_level": 2,
      "content_markdown": "## Examples\n\n### No Args\n\n#### Yield the remote window object\n\n*   End-to-End Test\n*   Component Test\n\n```\ncy.visit('http://localhost:8080/app')\ncy.window().then((win) => {\n  // win is the remote window\n})\n```\n\n```\ncy.mount(<MyComponent />)\ncy.window().then((win) => {\n  // win is the remote window\n})\n```\n\n#### Check a custom property\n\nIf the application sets a custom property, like:\n\n```\nwindow.tags = {\n  foo: 'bar',\n}\n```\n\nOur test can confirm the property was properly set.\n\n```\ncy.window().its('tags.foo').should('equal', 'bar')\n```\n\n#### TypeScript: custom window properties\n\n`cy.window()` yields an `AUTWindow` object typed as `Window & typeof globalThis & Cypress.ApplicationWindow`. To avoid TypeScript errors when accessing custom properties your application sets on `window`, extend the `Cypress.ApplicationWindow` interface:\n\n```\n// cypress/support/e2e.ts (or a *.d.ts file included by your cypress/tsconfig.json)\ndeclare namespace Cypress {\n  interface ApplicationWindow {\n    // add the properties your app sets on window\n    env: {\n      DISABLE: boolean\n    }\n  }\n}\n```\n\nAfter augmenting the interface, TypeScript will recognize the custom property:\n\n```\ncy.window().then((win) => {\n  win.env.DISABLE = true // no TypeScript error\n})\n```\n\n**Note:** Cypress commands are asynchronous, so you cannot check a property value before the Cypress commands ran.\n\n```\nit('equals bar', () => {\n  let foo\n\n  cy.window().then((win) => {\n    foo = win.tags.foo\n  })\n\n  // variable \"foo\" is still undefined\n  // because the above \"then\" callback\n  // has not been executed yet\n  expect(foo).to.equal('bar') // test fails\n})\n```\n\nInstead, use [`cy.then()`](/llm/markdown/api/commands/then.md) callback to check the value.\n\n```\nit('equals bar', () => {\n  let foo\n\n  cy.window()\n    .then((win) => {\n      foo = win.tags.foo\n    })\n    .then(() => {\n      // variable \"foo\" has been set\n      expect(foo).to.equal('bar') // test passes\n    })\n})\n```\n\n### Start tests when app is ready\n\nIf an application takes a while to start, it might \"signal\" its readiness by setting a property that Cypress can wait for.\n\n```\n// app.js\n// only set property \"appReady\" if Cypress is running tests\nif (window.Cypress) {\n  window.appReady = true\n}\n```\n\nCypress can wait for the property `window.appReady` to be `true` before every test\n\n```\n// spec.cy.js\nbeforeEach(() => {\n  cy.visit('/')\n  cy.window().should('have.property', 'appReady', true)\n})\n```\n\n**When Can The Test Start?**\n\n[This blog post](https://www.cypress.io/blog/2018/02/05/when-can-the-test-start/) explains how to use `cy.window()` to spy on the DOM `prototype` to detect when the application starts adding event listeners to the DOM elements. When this happens for the first time, Cypress knows that the application under test has started and the tests can begin.\n\n### Options\n\n#### Passes timeout through to [`.should()`](/llm/markdown/api/commands/should.md) assertion\n\n```\ncy.window({ timeout: 10000 }).should('have.property', 'foo')\n```\n",
      "section": "api",
      "anchors": [
        "examples"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 548
    },
    {
      "id": "api/commands/window#no-args",
      "doc_id": "api/commands/window",
      "heading": "No Args",
      "heading_level": 3,
      "content_markdown": "### No Args\n\n#### Yield the remote window object\n\n*   End-to-End Test\n*   Component Test\n\n```\ncy.visit('http://localhost:8080/app')\ncy.window().then((win) => {\n  // win is the remote window\n})\n```\n\n```\ncy.mount(<MyComponent />)\ncy.window().then((win) => {\n  // win is the remote window\n})\n```\n\n#### Check a custom property\n\nIf the application sets a custom property, like:\n\n```\nwindow.tags = {\n  foo: 'bar',\n}\n```\n\nOur test can confirm the property was properly set.\n\n```\ncy.window().its('tags.foo').should('equal', 'bar')\n```\n\n#### TypeScript: custom window properties\n\n`cy.window()` yields an `AUTWindow` object typed as `Window & typeof globalThis & Cypress.ApplicationWindow`. To avoid TypeScript errors when accessing custom properties your application sets on `window`, extend the `Cypress.ApplicationWindow` interface:\n\n```\n// cypress/support/e2e.ts (or a *.d.ts file included by your cypress/tsconfig.json)\ndeclare namespace Cypress {\n  interface ApplicationWindow {\n    // add the properties your app sets on window\n    env: {\n      DISABLE: boolean\n    }\n  }\n}\n```\n\nAfter augmenting the interface, TypeScript will recognize the custom property:\n\n```\ncy.window().then((win) => {\n  win.env.DISABLE = true // no TypeScript error\n})\n```\n\n**Note:** Cypress commands are asynchronous, so you cannot check a property value before the Cypress commands ran.\n\n```\nit('equals bar', () => {\n  let foo\n\n  cy.window().then((win) => {\n    foo = win.tags.foo\n  })\n\n  // variable \"foo\" is still undefined\n  // because the above \"then\" callback\n  // has not been executed yet\n  expect(foo).to.equal('bar') // test fails\n})\n```\n\nInstead, use [`cy.then()`](/llm/markdown/api/commands/then.md) callback to check the value.\n\n```\nit('equals bar', () => {\n  let foo\n\n  cy.window()\n    .then((win) => {\n      foo = win.tags.foo\n    })\n    .then(() => {\n      // variable \"foo\" has been set\n      expect(foo).to.equal('bar') // test passes\n    })\n})\n```\n",
      "section": "api",
      "anchors": [
        "no-args"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 353
    },
    {
      "id": "api/commands/window#yield-the-remote-window-object",
      "doc_id": "api/commands/window",
      "heading": "Yield the remote window object",
      "heading_level": 4,
      "content_markdown": "#### Yield the remote window object\n\n*   End-to-End Test\n*   Component Test\n\n```\ncy.visit('http://localhost:8080/app')\ncy.window().then((win) => {\n  // win is the remote window\n})\n```\n\n```\ncy.mount(<MyComponent />)\ncy.window().then((win) => {\n  // win is the remote window\n})\n```\n",
      "section": "api",
      "anchors": [
        "yield-the-remote-window-object"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 52
    },
    {
      "id": "api/commands/window#check-a-custom-property",
      "doc_id": "api/commands/window",
      "heading": "Check a custom property",
      "heading_level": 4,
      "content_markdown": "#### Check a custom property\n\nIf the application sets a custom property, like:\n\n```\nwindow.tags = {\n  foo: 'bar',\n}\n```\n\nOur test can confirm the property was properly set.\n\n```\ncy.window().its('tags.foo').should('equal', 'bar')\n```\n",
      "section": "api",
      "anchors": [
        "check-a-custom-property"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 45
    },
    {
      "id": "api/commands/window#typescript-custom-window-properties",
      "doc_id": "api/commands/window",
      "heading": "TypeScript: custom window properties",
      "heading_level": 4,
      "content_markdown": "#### TypeScript: custom window properties\n\n`cy.window()` yields an `AUTWindow` object typed as `Window & typeof globalThis & Cypress.ApplicationWindow`. To avoid TypeScript errors when accessing custom properties your application sets on `window`, extend the `Cypress.ApplicationWindow` interface:\n\n```\n// cypress/support/e2e.ts (or a *.d.ts file included by your cypress/tsconfig.json)\ndeclare namespace Cypress {\n  interface ApplicationWindow {\n    // add the properties your app sets on window\n    env: {\n      DISABLE: boolean\n    }\n  }\n}\n```\n\nAfter augmenting the interface, TypeScript will recognize the custom property:\n\n```\ncy.window().then((win) => {\n  win.env.DISABLE = true // no TypeScript error\n})\n```\n\n**Note:** Cypress commands are asynchronous, so you cannot check a property value before the Cypress commands ran.\n\n```\nit('equals bar', () => {\n  let foo\n\n  cy.window().then((win) => {\n    foo = win.tags.foo\n  })\n\n  // variable \"foo\" is still undefined\n  // because the above \"then\" callback\n  // has not been executed yet\n  expect(foo).to.equal('bar') // test fails\n})\n```\n\nInstead, use [`cy.then()`](/llm/markdown/api/commands/then.md) callback to check the value.\n\n```\nit('equals bar', () => {\n  let foo\n\n  cy.window()\n    .then((win) => {\n      foo = win.tags.foo\n    })\n    .then(() => {\n      // variable \"foo\" has been set\n      expect(foo).to.equal('bar') // test passes\n    })\n})\n```\n",
      "section": "api",
      "anchors": [
        "typescript-custom-window-properties"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 252
    },
    {
      "id": "api/commands/window#start-tests-when-app-is-ready",
      "doc_id": "api/commands/window",
      "heading": "Start tests when app is ready",
      "heading_level": 3,
      "content_markdown": "### Start tests when app is ready\n\nIf an application takes a while to start, it might \"signal\" its readiness by setting a property that Cypress can wait for.\n\n```\n// app.js\n// only set property \"appReady\" if Cypress is running tests\nif (window.Cypress) {\n  window.appReady = true\n}\n```\n\nCypress can wait for the property `window.appReady` to be `true` before every test\n\n```\n// spec.cy.js\nbeforeEach(() => {\n  cy.visit('/')\n  cy.window().should('have.property', 'appReady', true)\n})\n```\n\n**When Can The Test Start?**\n\n[This blog post](https://www.cypress.io/blog/2018/02/05/when-can-the-test-start/) explains how to use `cy.window()` to spy on the DOM `prototype` to detect when the application starts adding event listeners to the DOM elements. When this happens for the first time, Cypress knows that the application under test has started and the tests can begin.\n",
      "section": "api",
      "anchors": [
        "start-tests-when-app-is-ready"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 171
    },
    {
      "id": "api/commands/window#notes",
      "doc_id": "api/commands/window",
      "heading": "Notes",
      "heading_level": 2,
      "content_markdown": "## Notes\n\n### Cypress uses 2 different windows.\n\nLet's say you want to check the type of the events. You might write code like below:\n\n```\nit('test', (done) => {\n  cy.get('#test-input').then((jQueryElement) => {\n    let elemHtml = jQueryElement.get(0)\n\n    elemHtml.addEventListener('keydown', (event) => {\n      expect(event instanceof KeyboardEvent).to.be.true\n      done()\n    })\n  })\n\n  cy.get('#test-input').type('A')\n})\n```\n\nIt fails. But the interesting thing is that the type of `event` is `KeyboardEvent` when you `console.log(event)`.\n\nIt's because Cypress uses an `iframe` to load the application under test. In other words, the `KeyboardEvent` used in the code above and the `KeyboardEvent` class from which the `event` variable is constructed are different `KeyboardEvent`s.\n\nThat's why the test should be written like this.\n\n```\nit('should trigger KeyboardEvent with .type inside Cypress event listener', (done) => {\n  cy.window().then((win) => {\n    cy.get('#test-input').then((jQueryElement) => {\n      let elemHtml = jQueryElement.get(0)\n\n      elemHtml.addEventListener('keydown', (event) => {\n        expect(event instanceof win['KeyboardEvent']).to.be.true\n        done()\n      })\n    })\n  })\n\n  cy.get('#test-input').type('A')\n})\n```\n",
      "section": "api",
      "anchors": [
        "notes"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 199
    },
    {
      "id": "api/commands/window#cypress-uses-2-different-windows",
      "doc_id": "api/commands/window",
      "heading": "Cypress uses 2 different windows.",
      "heading_level": 3,
      "content_markdown": "### Cypress uses 2 different windows.\n\nLet's say you want to check the type of the events. You might write code like below:\n\n```\nit('test', (done) => {\n  cy.get('#test-input').then((jQueryElement) => {\n    let elemHtml = jQueryElement.get(0)\n\n    elemHtml.addEventListener('keydown', (event) => {\n      expect(event instanceof KeyboardEvent).to.be.true\n      done()\n    })\n  })\n\n  cy.get('#test-input').type('A')\n})\n```\n\nIt fails. But the interesting thing is that the type of `event` is `KeyboardEvent` when you `console.log(event)`.\n\nIt's because Cypress uses an `iframe` to load the application under test. In other words, the `KeyboardEvent` used in the code above and the `KeyboardEvent` class from which the `event` variable is constructed are different `KeyboardEvent`s.\n\nThat's why the test should be written like this.\n\n```\nit('should trigger KeyboardEvent with .type inside Cypress event listener', (done) => {\n  cy.window().then((win) => {\n    cy.get('#test-input').then((jQueryElement) => {\n      let elemHtml = jQueryElement.get(0)\n\n      elemHtml.addEventListener('keydown', (event) => {\n        expect(event instanceof win['KeyboardEvent']).to.be.true\n        done()\n      })\n    })\n  })\n\n  cy.get('#test-input').type('A')\n})\n```\n",
      "section": "api",
      "anchors": [
        "cypress-uses-2-different-windows"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 196
    },
    {
      "id": "api/commands/window#rules",
      "doc_id": "api/commands/window",
      "heading": "Rules",
      "heading_level": 2,
      "content_markdown": "## Rules\n\n### Requirements\n\n*   `cy.window()` requires being chained off of `cy`.\n\n### Assertions\n\n*   `cy.window()` will automatically [retry](/llm/markdown/app/core-concepts/retry-ability.md) until all chained assertions have passed\n\n### Timeouts\n\n*   `cy.window()` can time out waiting for assertions you've added to pass.\n",
      "section": "api",
      "anchors": [
        "rules"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 52
    },
    {
      "id": "api/commands/window#command-log",
      "doc_id": "api/commands/window",
      "heading": "Command Log",
      "heading_level": 2,
      "content_markdown": "## Command Log\n\n**_Get the window_**\n\n```\ncy.window()\n```\n\nThe commands above will display in the Command Log as:\n\nWhen clicking on `window` within the command log, the console outputs the following:\n",
      "section": "api",
      "anchors": [
        "command-log"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 43
    },
    {
      "id": "api/commands/window#history",
      "doc_id": "api/commands/window",
      "heading": "History",
      "heading_level": 2,
      "content_markdown": "## History\n\n| Version | Changes |\n| --- | --- |\n| [0.20.0](/llm/markdown/app/references/changelog.md#0-20-0) | Can call [.focus()](/llm/markdown/api/commands/focus.md) and [.blur()](/llm/markdown/api/commands/blur.md) on `cy.window()` |\n| [0.11.6](/llm/markdown/app/references/changelog.md#0-11-6) | `cy.window()` logs to Command Log |\n",
      "section": "api",
      "anchors": [
        "history"
      ],
      "path": "/llm/json/chunked/api/commands/window.json",
      "token_estimate": 43
    }
  ]
}