| | |

Cypress 19 ๐ŸŒฒ Iframes โ€” cy.iframe and cross-origin frame handling

โฑ๏ธ Estimated read: 13 min | |

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

StepCodePurpose
Get iframecy.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

AspectSame-OriginCross-Origin
contentDocument accessAllowedBlocked by browser
Custom command worksYesNo, unless security disabled
Required configNonechromeWebSecurity: false
Browser supportAllChrome-based only
Recommended when iframe not controlledN/AAssert on src instead

cypress-iframe Plugin Status

CommandStatus in Cypress 19
cy.iframe()Broken (plugin incompatible)
cy.frameLoaded()Broken
cy.enter()Broken
ReplacementCustom 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

PitfallWhy It HappensFix
cy.iframe is not a functionPlugin incompatible with Cypress 12+Build custom getIframeBody command
Element not found inside iframeBody retrieved before renderAdd .should('not.be.empty')
contentDocument is nullCross-origin iframe, security enabledSet chromeWebSecurity: false (Chrome only)
Commands run on parent pageMissing .within() scopeWrap iframe commands in .within()
chromeWebSecurity ignoredRunning in Firefox or ElectronUse Chrome, or assert on src instead
Nested iframe unreachableMissing one level of getIframeBodyChain 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

ItemValue
Native cy.iframe()Does not exist in core Cypress
cypress-iframe pluginIncompatible with Cypress 12+
ReplacementCustom getIframeBody() command
Same-origin accesscontentDocument.body + cy.wrap()
Cross-origin accesschromeWebSecurity: false (Chrome only)
cy.origin() for iframesNot applicable; navigates the page, not frames
Third-party iframe strategyAssert on src attribute
Nested iframesChain 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 the cypress-iframe plugin, 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 src when 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.

Was this helpful?


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!