For a same-origin iframe, Cypress can reach its document through contentDocument.body. Wait until the body is non-empty, then pass it to cy.wrap() so later Cypress queries and assertions can retry. Cypress cannot normally automate a cross-origin iframe; cy.origin() is for top-level navigation between origins, not for switching into an embedded frame.
Check whether the iframe is same-origin
An iframe is same-origin with its parent only when the two documents share the same origin: scheme, host, and port. Browser same-origin security rules prevent a page from reading another origin’s frame document. When Cypress tries to access a cross-origin frame’s contentDocument, it is inaccessible (the FAQ describes it as returning null).
As an Amazon Associate I earn from qualifying purchases.
This distinction matters for embedded payment forms, video players, identity-provider forms, and comment widgets. Their content may come from a separate service even when the iframe appears inside your application. Cypress’s documented limitation is explicit: it cannot automate or communicate with a cross-origin iframe under normal browser security behavior. Cypress: Cross-origin testing.
Recommended Free Tools
- Same-origin embedded frame: query the frame body using the pattern below.
- Cross-origin embedded frame: do not expect Cypress to query or click inside it using ordinary iframe traversal.
- Top-level navigation to another origin: use
cy.origin()for commands on the newly loaded page; this is a different case.
Query a same-origin iframe with retryable Cypress commands
Use a stable selector for the iframe, especially when the page has more than one. The frame loads asynchronously, so assert that its body is not empty before searching within it:
cy.get('iframe[data-testid="checkout-frame"]')
.its('0.contentDocument.body')
.should('not.be.empty')
.then(cy.wrap)
.find('[data-testid="submit"]')
.click()Replace the iframe selector and inner element selector with selectors from your application. If there is only one iframe, cy.get('iframe') can be used, but a specific selector avoids accidentally targeting a different frame.
cy.get(...)finds the iframe element..its('0.contentDocument.body')reads the first matched frame’s body. Cypress retries the query while it is acquiring the subject..should('not.be.empty')waits for the document body to contain content instead of querying too early..then(cy.wrap)turns the body into a Cypress subject, allowing subsequent Cypress commands such as.find(), assertions, and actions to use normal retry behavior.
This technique depends on same-origin access. Waiting longer does not make a cross-origin document readable.
Reuse the pattern with a helper
If several tests query frames, a small custom command keeps the wait and wrapping logic consistent. Add this to your Cypress support file:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Cypress.Commands.add('getIframeBody', (selector) => {
return cy.get(selector)
.its('0.contentDocument.body')
.should('not.be.empty')
.then(cy.wrap)
})Then use it in a test:
cy.getIframeBody('iframe[data-testid="checkout-frame"]')
.find('[data-testid="submit"]')
.should('be.visible')
.click()Cypress’s migration guide shows this general custom-command approach. The community cypress-iframe plugin also offers helpers such as cy.iframe() and cy.frameLoaded(); it is an optional convenience, not a built-in Cypress command or a requirement for modern same-origin frame access. Cypress migration guide · Cypress FAQ.
Why cy.origin() does not solve embedded iframe access
cy.origin() runs Cypress commands after a top-level navigation to a secondary origin, such as a redirect or link that loads a different site in the main window. It does not change browser access rules for an embedded cross-origin iframe, and Cypress lists commands inside an iframe among the scenarios it cannot handle with cy.origin(). See the cy.origin() API and cross-origin testing guide.
There is also a version detail for top-level navigation: Cypress v14.0.0 stopped injecting document.domain by default. Tests that navigate between different origins in one test must use cy.origin(), including cases involving related subdomains that older behavior might have allowed without it. Cypress documents injectDocumentDomain: true as deprecated and warns it can cause issues, including with origin-keyed agent clusters. This change does not add support for cross-origin embedded frames.
Cross-origin frame workarounds and their limits
Use the parent page or an application-owned test seam
When a third-party frame is inaccessible, test the part your application controls: for example, assert that the parent page renders the integration container or responds correctly to an application-owned success, failure, or cancellation signal. If the product permits it, an application-owned test seam can cover relevant states without claiming Cypress has clicked or inspected the third-party frame.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Consider chromeWebSecurity only as a narrow Chromium workaround
Cypress documents chromeWebSecurity: false as a possible workaround for cross-origin iframe access in Chromium-family browsers. The FAQ says this setting is unsupported in Firefox and WebKit. It changes browser security behavior for the test environment, so it is a configuration trade-off, not general iframe support or a portable solution. Do not assume it enables the same test to work in every browser; confirm the behavior in the specific browser and setup you use. Cypress cross-origin testing guide.
Keep iframe access separate from CSP testing
Querying an application’s iframe and testing whether a site can be framed are different tasks. Cypress’s Content Security Policy reference says frame-ancestors prevents Cypress from loading a test application into an iframe. The reference also says the listed directives are stripped unconditionally and their behavior cannot be tested using Cypress. That restriction is separate from same-origin DOM traversal. See Cypress: Content Security Policy.
Troubleshooting iframe tests
| Symptom | Likely cause | What to do |
|---|---|---|
contentDocument is null or the body cannot be queried |
The iframe is cross-origin, or its document has not rendered yet. | Check the frame’s origin. For a same-origin frame, assert that the body is non-empty before wrapping it. For a cross-origin frame, use a parent-page assertion or an application-owned test seam rather than DOM traversal. |
| The inner element is not found intermittently | The frame body is queried before asynchronous content appears, or the test selected the wrong iframe. | Use a stable, specific iframe selector and the non-empty body assertion. Confirm the target element is in that frame and is rendered after the body loads. |
| Assertions or actions after extracting the body do not behave as expected | The body was not wrapped as a Cypress subject. | Pass the body through .then(cy.wrap) before chaining Cypress queries and actions. |
cy.origin() does not reach a form inside the embedded frame |
cy.origin() handles top-level origin transitions, not embedded-frame switching. |
Use it only after the main page navigates to another origin. For an embedded cross-origin frame, use a supported application-level test approach. |
| A security-setting workaround behaves differently across browsers | chromeWebSecurity: false is documented for Chromium-family browsers and unsupported in Firefox and WebKit. |
Keep the workaround scoped to the browser it supports; do not treat it as cross-browser iframe support. |
| A CSP framing test gives misleading results in Cypress | Cypress strips the listed CSP directives, including the behavior described for frame-ancestors. |
Use a method outside Cypress to verify that policy behavior; Cypress’s CSP reference says that behavior cannot be tested using Cypress. |
Or skip the browser setup
If your goal is to capture a rendered page rather than interact with an iframe in a Cypress test, ScreenshotNeo provides a website screenshot API. For example, request a capture with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Screenshot capture is not a substitute for Cypress interaction with a cross-origin iframe. ScreenshotNeo removes cookie banners, popups, and chat widgets before a shot; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots per month are free with no card, with paid plans starting at $5 for 3,000.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does Cypress have a built-in switch-into-iframe command?
No. Cypress’s FAQ describes accessing a same-origin frame through its document and chaining Cypress queries from the wrapped body; there is no dedicated iframe-switch command.
Can Cypress test a YouTube or Stripe iframe directly?
Not through normal Cypress DOM automation when the embedded frame is cross-origin. Test your application’s integration behavior from the parent page or with an application-owned test seam.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
