Cypress 19 ๐ฒ Iframes โ cy.iframe and cross-origin frame handling
Cypress does not ship a native cy.iframe() command. The cypress-iframe plugin that provided it is a third-party package, and it broke in Cypress 12 and later with the error TypeError: cy.iframe is not a function. The command that this chapter’s title references is not part of core Cypressโit belongs to a plugin that is no longer compatible with modern versions. This chapter explains the real state of iframe testing in Cypress 19: why the plugin failed, how to build a custom command that replaces it, how same-origin iframes are accessed through contentDocument, and how cross-origin iframes require either disabling web security or a fundamentally different testing strategy.
Key point: Core Cypress has no cy.iframe() command. The cypress-iframe plugin is incompatible with Cypress 12+. Same-origin iframes are accessed by retrieving contentDocument.body and wrapping it with cy.wrap(). Cross-origin iframes require chromeWebSecurity: false in Chrome-based browsers, and even then, Cypress’s own documentation states that iframe support is “somewhat limited” .
Why the cypress-iframe plugin failed
The plugin’s original design. The cypress-iframe package added three commands: cy.frameLoaded(), cy.iframe(), and cy.enter() . cy.iframe(selector) returned a wrapped reference to the iframe’s body, allowing subsequent commands to be chained inside the frame. cy.enter(selector) returned a function that produced the body on demand. The plugin worked by reaching into contentDocument.body and wrapping the result with cy.wrap(), the same technique that custom commands use today .
The Cypress 12 break. When Cypress 12 introduced changes to its internal command architecture and test isolation model, the plugin stopped working. The error cy.iframe is not a function indicates that the plugin’s command registration no longer executed, either because the import failed silently or because the internal APIs the plugin depended on were removed. The plugin’s last published version is 1.0.1, and it has not been updated to address the incompatibility .
The official position. Cypress’s own documentation describes iframe support as “somewhat limited, but does work” for same-origin iframes, and notes that a native “switch into an iframe” command remains an open proposal . The documentation does not recommend the cypress-iframe plugin; it points to a custom command approach instead. The plugin’s historical role is acknowledged, but it is not a supported path forward .
a. Building a custom command for same-origin iframes
A same-origin iframe’s document is accessible through the iframe element’s contentDocument property. A custom command retrieves that document, asserts that it exists, extracts the body, and wraps the body with cy.wrap() so that Cypress commands can be chained from it. This is the replacement for cy.iframe().
// cypress/support/commands.ts
Cypress.Commands.add('getIframeBody', (iframeSelector: string) => {
// Get the iframe element, then its contentDocument
return cy.get(iframeSelector)
.its('0.contentDocument.body') // index 0: jQuery object to native DOM
.should('not.be.empty') // wait for the body to render
.then(cy.wrap); // wrap so Cypress commands can chain
});
// cypress/e2e/iframe.cy.ts
describe('Same-origin iframe', () => {
it('types into an input inside the iframe', () => {
cy.visit('/form');
// Retrieve the iframe body and interact with its content
cy.getIframeBody('#payment-frame').within(() => {
cy.get('input[name="cardNumber"]').type('4242424242424242');
cy.get('button[type="submit"]').click();
});
// Assert on the parent page after the iframe action
cy.get('[data-test="success"]').should('be.visible');
});
});
The .should('not.be.empty') assertion is critical. Cypress retrieves the contentDocument.body immediately, but the iframe’s content may not have rendered yet. The assertion retries until the body contains child elements, preventing the subsequent .within() block from running against an empty document. Without it, the command succeeds but every locator inside the iframe fails with “element not found.”
The .within() block scopes all commands to the wrapped body, which is the closest equivalent to the plugin’s cy.iframe() chain. Commands inside .within() search only the iframe’s DOM; commands outside return to the parent page.
b. Cross-origin iframes and chromeWebSecurity
When an iframe’s src points to a different origin (different protocol, domain, or port), the browser’s same-origin policy blocks JavaScript access to contentDocument. The cy.getIframeBody() command fails because contentDocument is null. Cypress addresses this with the chromeWebSecurity configuration option, which disables web security in Chrome-based browsers and allows access to cross-origin iframes .
// cypress.config.ts
import { defineConfig } from 'cypress';
export default defineConfig({
chromeWebSecurity: false, // โ
allows cross-origin iframe access in Chrome
e2e: {
// other config
},
});
Setting chromeWebSecurity: false has three documented effects: it displays insecure content, allows navigation to any origin without cross-origin errors, and accesses cross-origin iframes embedded in the application . This is the only supported way to interact with a cross-origin iframe’s DOM from Cypress.
The option has strict limitations. It is only supported in Chrome-based browsersโFirefox, Electron, and WebKit ignore it and log a warning . Disabling web security lowers the test environment’s security posture, and Cypress recommends it only when the iframe’s content is under your control or when no other workaround exists . For third-party iframes you do not controlโpayment widgets, social embeds, analytics framesโdisabling web security may still fail due to framebusting code, which requires the experimentalModifyObstructiveThirdPartyCode flag to rewrite .
c. What cy.origin does not do for iframes
A common misconception is that cy.origin() handles cross-origin iframes. It does not. cy.origin() is designed for navigating the test runner’s page to a different origin, not for entering an iframe. Cypress’s documentation explicitly separates the two: for content inside an <iframe>, it points to the iframe FAQ, not to cy.origin() . Calling cy.origin() does not scope subsequent commands to an iframe’s document; it changes the page context entirely.
cy.origin() cannot be called inside an iframe, and cy.iframe() cannot be called inside a cy.origin() callback. They serve different purposes and are not interchangeable. If the iframe is cross-origin and you need to interact with it, chromeWebSecurity: false with a custom command is the only path within the Cypress browser. If the iframe is cross-origin and you only need to verify that it loaded (not interact with its content), asserting on the iframe element’s src attribute is the recommended alternative .
Complete Example Session
// ============================================
// PART 1: CUSTOM COMMAND DEFINITION
// ============================================
// cypress/support/commands.ts
Cypress.Commands.add('getIframeBody', (selector: string) => {
return cy.get(selector)
.its('0.contentDocument.body')
.should('not.be.empty')
.then(cy.wrap);
});
// ============================================
// PART 2: SAME-ORIGIN IFRAME INTERACTION
// ============================================
describe('Iframe testing in Cypress 19', () => {
it('fills a form inside a same-origin iframe', () => {
cy.visit('/checkout');
// ============================================
// PART 3: RETRIEVING THE IFRAME BODY
// ============================================
cy.getIframeBody('#payment-frame').within(() => {
// ============================================
// PART 4: INTERACTING INSIDE THE FRAME
// ============================================
cy.get('input[name="card"]').type('4242424242424242');
cy.get('input[name="expiry"]').type('12/28');
cy.get('input[name="cvc"]').type('123');
cy.get('button[type="submit"]').click();
});
// ============================================
// PART 5: ASSERTING ON THE PARENT PAGE
// ============================================
cy.get('[data-test="payment-success"]').should('be.visible');
});
// ============================================
// PART 6: NESTED IFRAMES
// ============================================
it('reaches a nested iframe', () => {
cy.visit('/editor');
cy.getIframeBody('#outer-frame').within(() => {
// The inner iframe is inside the outer iframe's document
cy.getIframeBody('#inner-frame').within(() => {
cy.get('button').contains('Save').click();
});
});
});
// ============================================
// PART 7: ASSERTING IFRAME CONTENT DIRECTLY
// ============================================
it('reads text from inside the iframe', () => {
cy.visit('/dashboard');
cy.getIframeBody('#status-frame')
.find('.status-text')
.should('have.text', 'Connected');
});
// ============================================
// PART 8: CROSS-ORIGIN WITH chromeWebSecurity
// ============================================
it('interacts with a cross-origin iframe', () => {
// Requires chromeWebSecurity: false in cypress.config.ts
cy.visit('/integrations');
cy.getIframeBody('iframe[src*="widget.example.com"]').within(() => {
cy.get('button').contains('Connect').click();
});
});
// ============================================
// PART 9: VERIFYING A CROSS-ORIGIN IFRAME LOADED
// ============================================
it('checks a third-party iframe without interacting', () => {
cy.visit('/blog');
// When content is not under your control, assert on the src instead
cy.get('iframe[title="YouTube video"]')
.should('have.attr', 'src')
.and('include', 'youtube.com/embed');
});
// ============================================
// PART 10: WAITING FOR SLOW IFRAME CONTENT
// ============================================
it('waits for a slow-loading iframe', () => {
cy.visit('/reports');
// The .should('not.be.empty') inside getIframeBody retries automatically
cy.getIframeBody('#report-frame', { timeout: 10000 }).within(() => {
cy.get('[data-test="report-table"]').should('exist');
});
});
});
The ten parts above cover the complete iframe workflow in Cypress 19: the custom command that replaces cy.iframe(), same-origin interaction, nested frames, direct content assertions, cross-origin access with chromeWebSecurity, the safer alternative of asserting on the src attribute, and timeout handling for slow iframes.
Quick Reference
The Custom Command
| Step | Code | Purpose |
|---|---|---|
| Get iframe | cy.get(selector) | Locate the iframe element |
| Get body | .its('0.contentDocument.body') | Access the inner document |
| Wait for content | .should('not.be.empty') | Retry until rendered |
| Wrap | .then(cy.wrap) | Enable Cypress chaining |
| Scope | .within(() => { ... }) | Commands run inside frame |
Same-Origin vs Cross-Origin
| Aspect | Same-Origin | Cross-Origin |
|---|---|---|
contentDocument access | Allowed | Blocked by browser |
| Custom command works | Yes | No, unless security disabled |
| Required config | None | chromeWebSecurity: false |
| Browser support | All | Chrome-based only |
| Recommended when iframe not controlled | N/A | Assert on src instead |
cypress-iframe Plugin Status
| Command | Status in Cypress 19 |
|---|---|
cy.iframe() | Broken (plugin incompatible) |
cy.frameLoaded() | Broken |
cy.enter() | Broken |
| Replacement | Custom getIframeBody() command |
Best Practices
โ Do This:
// Build a custom command that waits for the body to render
Cypress.Commands.add('getIframeBody', (sel: string) =>
cy.get(sel).its('0.contentDocument.body').should('not.be.empty').then(cy.wrap)
); // โ
// Use .within() to scope commands to the iframe
cy.getIframeBody('#frame').within(() => {
cy.get('button').click(); // โ
});
// For third-party iframes you cannot control, assert on the src
cy.get('iframe').should('have.attr', 'src').and('include', 'youtube'); // โ
// Enable chromeWebSecurity only when cross-origin interaction is required
chromeWebSecurity: false, // โ
(Chrome only)
// Handle slow iframes with a longer timeout
cy.getIframeBody('#slow-frame', { timeout: 15000 }); // โ
โ Don’t Do This:
// Don't install cypress-iframe and expect it to work
import 'cypress-iframe'; // โ cy.iframe is not a function
// Don't access contentDocument without waiting for the body
cy.get('#frame').its('0.contentDocument.body').then(cy.wrap); // โ may be empty
// Don't use cy.origin() for iframe content
cy.origin('https://other.com', () => { /* ... */ }); // โ does not enter iframes
// Don't assume chromeWebSecurity works in Firefox
chromeWebSecurity: false, // โ Chrome-based only
// Don't interact with third-party iframe content without security disabled
cy.getIframeBody('#youtube-frame'); // โ contentDocument is null
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
cy.iframe is not a function | Plugin incompatible with Cypress 12+ | Build custom getIframeBody command |
| Element not found inside iframe | Body retrieved before render | Add .should('not.be.empty') |
contentDocument is null | Cross-origin iframe, security enabled | Set chromeWebSecurity: false (Chrome only) |
| Commands run on parent page | Missing .within() scope | Wrap iframe commands in .within() |
chromeWebSecurity ignored | Running in Firefox or Electron | Use Chrome, or assert on src instead |
| Nested iframe unreachable | Missing one level of getIframeBody | Chain getIframeBody per level |
Real-World Examples
1. Typing into a payment iframe
cy.getIframeBody('#stripe-card').within(() => {
cy.get('input[name="cardnumber"]').type('4242424242424242');
});
2. Clicking a button inside a WYSIWYG editor iframe
cy.getIframeBody('#editor-frame').within(() => {
cy.get('button[aria-label="Bold"]').click();
});
3. Asserting text inside a same-origin iframe
cy.getIframeBody('#preview').find('h1').should('contain', 'Preview');
4. Accessing a nested iframe
cy.getIframeBody('#outer').within(() => {
cy.getIframeBody('#inner').within(() => { cy.get('button').click(); });
});
5. Cross-origin iframe with security disabled
// chromeWebSecurity: false required
cy.getIframeBody('iframe[src*="external.com"]').within(() => {
cy.get('button').click();
});
6. Asserting a third-party iframe loaded
cy.get('iframe[title="Video"]').should('have.attr', 'src').and('include', 'youtube');
7. Waiting for a slow iframe
cy.getIframeBody('#slow-frame', { timeout: 20000 }).within(() => {
cy.get('.content').should('exist');
});
8. Checking an iframe’s src without entering it
cy.get('#oauth-frame').invoke('attr', 'src').should('include', 'auth.example.com');
9. Using .find() instead of .within() for a single assertion
cy.getIframeBody('#status').find('.online').should('be.visible');
10. Building the custom command in TypeScript
Cypress.Commands.add('getIframeBody', (sel: string) =>
cy.get(sel).its('0.contentDocument.body').should('not.be.empty').then(cy.wrap)
);
Visual
The iframe Document Boundary
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ PARENT PAGE vs IFRAME DOCUMENT โ
โ โ
โ Main Document โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ <body> โ โ
โ โ <h1>Checkout</h1> โ โ
โ โ <iframe id="payment"> โ โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ โ IFRAME DOCUMENT โ โ โ
โ โ โ โ โ โ
โ โ โ <input name="card"> โ โ โ
โ โ โ <button>Pay</button> โ โ โ
โ โ โ โ โ โ
โ โ โ cy.get() cannot see this โ โ โ
โ โ โ getIframeBody() can โ โ โ
โ โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ โ
โ โ </iframe> โ โ
โ โ </body> โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ cy.get('input[name="card"]') โ NOT FOUND โ
โ cy.getIframeBody('#payment') โ
โ .find('input[name="card"]') โ FOUND โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Custom Command Pipeline
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ getIframeBody('#frame') โ
โ โ
โ cy.get('#frame') โ
โ โ โ
โ โผ โ
โ .its('0.contentDocument.body') โ
โ โ โ
โ โผ โ
โ .should('not.be.empty') โโโ retries until โ
โ โ body has children โ
โ โผ โ
โ .then(cy.wrap) โโโ enables .within() โ
โ โ and .find() โ
โ โผ โ
โ .within(() => { ... }) โโโ scopes commands โ
โ โ
โ Without .should('not.be.empty'), the command โ
โ succeeds but all locators inside fail. โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Same-Origin vs Cross-Origin
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ ACCESS RULES โ
โ โ
โ Same-origin iframe โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ iframe.src = '/form' โ โ
โ โ contentDocument โ accessible โ โ
โ โ getIframeBody() โ works โ โ
โ โ Browser support โ all โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ
โ Cross-origin iframe โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ iframe.src = 'https://other.com/form' โ โ
โ โ contentDocument โ null (same-origin policy)โ โ
โ โ getIframeBody() โ fails โ โ
โ โ chromeWebSecurity: false โ contentDocument โ โ
โ โ becomes accessible (Chrome only) โ โ
โ โ No workaround in Firefox โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
Native cy.iframe() | Does not exist in core Cypress |
cypress-iframe plugin | Incompatible with Cypress 12+ |
| Replacement | Custom getIframeBody() command |
| Same-origin access | contentDocument.body + cy.wrap() |
| Cross-origin access | chromeWebSecurity: false (Chrome only) |
cy.origin() for iframes | Not applicable; navigates the page, not frames |
| Third-party iframe strategy | Assert on src attribute |
| Nested iframes | Chain getIframeBody per level |
| Waiting for content | .should('not.be.empty') |
| Official stance | “Somewhat limited” |
Key takeaways:
cy.iframe()is not a Cypress command. It belongs to thecypress-iframeplugin, which broke in Cypress 12 and has not been updated. Do not install the plugin; build a custom command instead.- The custom command is four lines.
cy.get(selector).its('0.contentDocument.body').should('not.be.empty').then(cy.wrap)retrieves the iframe body, waits for it to render, and enables chaining. This is the entire replacement. .should('not.be.empty')prevents silent failures. Without it, the command succeeds immediately but every locator inside the iframe fails because the body has no children yet. The assertion retries until the content appears.- Cross-origin iframes require
chromeWebSecurity: false. This option is Chrome-only. Firefox and Electron ignore it. When the iframe is a third-party service you do not control, disabling security may still fail due to framebusting code. cy.origin()does not enter iframes. It changes the test runner’s page context to a different origin. It is for navigation, not for frame access. The two are separate concerns.- Assert on
srcwhen you cannot interact. For third-party iframes you do not control, verifying that the iframe loaded with the correct URL is often the only safe and stable test. It is faster and avoids the security trade-off. - Cypress’s iframe support is acknowledged as limited. The official documentation describes it as “somewhat limited” and notes that a native switch-into-iframe command remains an open proposal. The custom command is the recommended workaround, not a fully featured frame API .
Remember: Iframe testing in Cypress 19 is not a first-class feature. The plugin that once provided cy.iframe() is dead, and the official path is a custom command that reaches into contentDocument.body. For same-origin frames, this works reliably with the right waiting assertion. For cross-origin frames, it requires disabling web security in Chrome, which is a trade-off Cypress itself cautions against. When the iframe is under your control, the custom command is sufficient. When it is not, asserting on the src attribute is often the better testโfaster, safer, and stable across browsers. The limitation is real, and the workarounds are the state of the tool.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!