What this usually means
Cypress enforces a same-origin policy by default. If the iframe loads content from a different domain (or even a different subdomain), Cypress cannot directly access its DOM. Even when same-origin, you must explicitly switch context into the iframe's document. Many developers assume Cypress can just query across frames, but it doesn't. The core issue is that Cypress's `cy` commands run in the top window's context. To interact with iframe content, you must obtain a reference to the iframe's `document` or `window` and then use `cy.wrap()` to chain commands. Timing is also critical: if you try to access the iframe before it loads, you'll get null references.
The first ten minutes — establish facts before touching code.
- 1Open Cypress test runner; in the DevTools console, run `document.querySelector('iframe')` to see if the iframe element exists.
- 2Check the iframe's `src` attribute: if it's a different origin (protocol+host+port), Cypress will block access. Use `console.log($iframe[0].contentDocument)` to see if it's null (cross-origin).
- 3Try `cy.get('iframe').its('0.contentDocument.body').should('be.visible')` — if it fails, the iframe is likely cross-origin or not loaded.
- 4Add a `cy.wait(2000)` before accessing iframe content to rule out timing issues (but don't keep this as a fix).
- 5Inspect network tab: is the iframe URL returning a 200? Is there a CORS error?
- 6Use `cy.origin()` (Cypress 10+) if the iframe is cross-origin — but note that `cy.origin()` only works for same-origin frames if the top window navigates; for embedded iframes you need a workaround.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchCypress test file: look for any use of `cy.iframe()` or custom commands that access iframe content.
- searchIframe source URL: compare it to the base URL of the test (window.location.origin).
- searchCypress configuration (cypress.config.js): check `chromeWebSecurity` setting (if false, Cypress disables web security but this is not recommended).
- searchNetwork tab of Cypress runner: confirm iframe request and response headers for CORS.
- searchApplication code: check how the iframe is created (dynamic vs static) and if it sets `sandbox` attributes that restrict script access.
- searchCypress plugins file: if using `cypress-iframe` plugin, verify version compatibility.
Practical causes, not theory. These are the things you will actually find.
- warningCross-origin iframe: the iframe src is on a different domain, subdomain, port, or protocol (http vs https).
- warningTiming: test attempts to access iframe content before it finishes loading.
- warningIframe sandbox attribute: `sandbox` value disables script access to `contentDocument`.
- warningIncorrect reference: using `cy.get('iframe').its('0.contentDocument')` but the iframe is the first of many, or the index is off.
- warningCypress browser restrictions: Cypress runs in a controlled browser that enforces security policies.
- warningThe iframe content itself uses JavaScript that modifies the DOM after load, causing stale references.
Concrete fix directions. Pick the one that matches your root cause.
- buildFor same-origin iframes: use `cy.get('iframe').its('0.contentDocument.body').should('be.visible').then(cy.wrap)` to get a subject and chain commands.
- buildFor cross-origin iframes: if you control the iframe content, use `postMessage` to communicate between frames. Otherwise, use `cy.origin()` if the iframe navigates the top window, or consider testing the iframe content separately.
- buildAdd a custom Cypress command that waits for the iframe to load: `Cypress.Commands.add('getIframeBody', (selector) => { return cy.get(selector).its('0.contentDocument.body').should('not.be.empty').then(cy.wrap); })`.
- buildDisable Chrome web security in Cypress config: set `chromeWebSecurity: false` (use with caution—only for same-origin scenarios where you trust the content).
- buildUse the `cypress-iframe` plugin: `cy.iframe('iframe[selector]').find('button').click()` — but ensure the plugin is installed and configured.
- buildFor dynamic iframes, wait for a specific element inside the iframe rather than the iframe itself: `cy.get('iframe').then($iframe => { const body = $iframe.contents().find('body'); cy.wrap(body).find('#myElement').click(); })`.
A fix you cannot prove is a guess. Close the loop.
- verifiedRun the failing test with `--headed` mode to see the browser and confirm the iframe loads and appears.
- verifiedOpen Cypress DevTools console and execute `$('iframe').contents().find('body')` to verify access works.
- verifiedAdd a debug log inside the iframe's onload event to confirm load timing.
- verifiedCreate a minimal repro test that only accesses the iframe body and asserts its visibility.
- verifiedCheck that the test passes consistently across 3 consecutive runs in the same environment.
- verifiedIf using `chromeWebSecurity: false`, verify that no other cross-origin issues arise in other tests.
Things that make this bug worse or harder to find.
- warningUsing hardcoded `cy.wait(5000)` instead of waiting for a specific condition inside the iframe.
- warningAssuming `cy.origin()` works for embedded iframes—it doesn't; it's for navigation-based cross-origin scenarios.
- warningForgetting that `cy.its('0.contentDocument')` returns `undefined` if the iframe is cross-origin, leading to confusing errors.
- warningCalling `cy.wrap()` on the iframe element instead of its body, then trying to chain commands that expect a DOM element.
- warningIgnoring the iframe's `sandbox` attribute—if it lacks `allow-scripts` or `allow-same-origin`, you can't access its DOM.
- warningNot checking if the iframe URL is relative vs absolute; a relative URL might resolve incorrectly in test environment.
Cross-Origin Iframe Crashes CI Payment Test
Timeline
- 09:15CI pipeline fails on payment test: 'cy.its() can only accept property names of an object or array.'
- 09:18I check the test: it does `cy.get('iframe#stripe').its('0.contentDocument.body').find('button')`.
- 09:22Locally with `--headed`, I see the iframe loads but the test times out.
- 09:30I open DevTools: `document.querySelector('iframe#stripe').contentDocument` returns `null`.
- 09:35I inspect the iframe src: it's `https://js.stripe.com/v3/...` — different origin!
- 09:40I search for 'Cypress cross-origin iframe' and find `cy.origin()` — but that's for navigation, not iframes.
- 09:50I realize I can't access Stripe's iframe DOM due to cross-origin policy. I need to use `postMessage` or test differently.
- 10:00I modify the app to expose a mock Stripe iframe for testing, same origin.
- 10:15Test passes in CI. I also add a custom Cypress command to wait for iframe load.
I was debugging a CI failure that had been flaky for weeks. The payment test would pass locally about 70% of the time, but on GitLab CI it failed almost every run. The error message was cryptic: 'cy.its() can only accept property names of an object or array.' I initially thought it was a syntax issue with the chained command. But when I ran it with --headed locally, I saw the Stripe iframe load perfectly, yet Cypress would time out waiting for the element inside it.
I opened the browser's DevTools inside the Cypress runner. I ran `document.querySelector('iframe#stripe').contentDocument` and got `null`. That's when I realized the iframe was cross-origin. The src was https://js.stripe.com/v3/... — a different domain. Cypress cannot access the DOM of a cross-origin iframe due to browser security. My local passes were likely because I had `chromeWebSecurity: false` in my local config but not in CI.
I found that `cy.origin()` was not the answer—it's for when the top window navigates to a different origin, not for embedded iframes. The real fix was to change our testing approach: we decided to mock the Stripe iframe with a same-origin stub for integration tests, and rely on Stripe's own E2E tests for the real integration. I also added a robust custom command that waits for the iframe to be fully loaded before accessing its body. The lesson: always check the iframe's origin first, and be aware that Cypress's security model is strict.
Root cause
The Stripe iframe was served from a different origin (js.stripe.com), so Cypress could not access its DOM. The local environment had `chromeWebSecurity: false` masking the issue.
The fix
Replaced the real Stripe iframe with a same-origin mock in test environment. Added a custom Cypress command `getIframeBody` that waits for the iframe to be present and its body to be non-empty. Ensured `chromeWebSecurity` is consistent across environments.
The lesson
Always verify iframe origin before writing tests. Use same-origin mocks for third-party iframes. Never rely on `chromeWebSecurity: false` as a crutch—it hides real security issues.
Cypress runs within the browser's security context. When your page embeds an iframe from a different origin, the browser's same-origin policy prevents Cypress (or any script in the top window) from accessing the iframe's DOM. This is a fundamental browser security feature, not a Cypress limitation per se. Cypress's commands like `cy.its('0.contentDocument')` will return `undefined` or throw errors if the iframe is cross-origin.
Even for same-origin iframes, Cypress does not automatically switch context. You must explicitly navigate into the iframe's document. The typical pattern is: `cy.get('iframe').its('0.contentDocument.body').should('be.visible').then(cy.wrap)`. This retrieves the iframe's body and wraps it as a Cypress subject, allowing you to chain further commands like `.find()` or `.click()`.
Cypress introduced `cy.origin()` in version 10 to handle cross-origin scenarios, but it only works for *navigation*—when the top window loads a page from a different origin. It does *not* work for embedded iframes. Many developers mistakenly try to use `cy.origin()` to access iframe content and get confused when it doesn't work. For embedded cross-origin iframes, you have two options: either use `postMessage` to communicate between frames, or test the iframe content in isolation (e.g., by visiting its URL directly).
If you control the iframe content, you can set up a `postMessage` listener in the top window and have the iframe send data. Then Cypress can listen for those messages. This approach requires modifying both the app and the test code, but it's the only secure way to interact with cross-origin iframes without disabling security.
A common pattern is to create a custom Cypress command that encapsulates the iframe access logic, including waiting for the iframe to be fully loaded. Here's a production-tested example: `Cypress.Commands.add('getIframeBody', (iframeSelector) => { return cy.get(iframeSelector, { timeout: 10000 }).should('exist').its('0.contentDocument.body').should('not.be.empty').then(cy.wrap); })`. This command waits up to 10 seconds for the iframe to exist, then verifies that its body is not empty, and finally wraps the body for chaining.
Be careful: `contentDocument` may be null if the iframe is cross-origin or not yet loaded. That's why we use `.should('not.be.empty')` on the body. However, this only works for same-origin iframes. For cross-origin, you would need a different strategy altogether. Also, avoid using `cy.wait()` with arbitrary times—always use assertions that wait for specific conditions.
Frequently asked questions
Can Cypress test elements inside a cross-origin iframe?
No, Cypress cannot directly access the DOM of a cross-origin iframe due to browser same-origin policy. Workarounds include using `postMessage` to communicate with the iframe, mocking the iframe content on a same-origin domain for testing, or testing the iframe's content separately by visiting its URL directly.
What does `cy.its('0.contentDocument')` return for a cross-origin iframe?
It returns `undefined` because the browser blocks access to `contentDocument` for cross-origin iframes. This often leads to errors like 'Cannot read properties of undefined' when you try to chain commands like `.find()` on it.
How do I wait for an iframe to load before interacting with its content?
Use a custom Cypress command that waits for the iframe's body to be non-empty. For example: `cy.get('iframe').its('0.contentDocument.body').should('not.be.empty')`. This will retry until the body is populated. Avoid using fixed `cy.wait()` calls.
Is it safe to set `chromeWebSecurity: false` in Cypress config?
Setting `chromeWebSecurity: false` disables web security in Chrome, allowing access to cross-origin iframes. However, this is not recommended for production test suites because it disables important security checks and may mask real issues. It's better to use mocking or postMessage workarounds.
What is the difference between `cy.origin()` and accessing iframe content?
`cy.origin()` is used for cross-origin *navigation*—when the top window navigates to a different origin. It does not apply to embedded iframes. For iframes, you must use `cy.get()` and access `contentDocument` or use `postMessage`. They solve different problems.