t.switchToIframe Method

Switches the test execution context to an <iframe> element. Chainable.

t.switchToIframe(selector) → this | Promise<any>

Switches the test’s browsing context to the specified <iframe>.

Parameter	Type	Description
selector	Function | String | Selector | Snapshot | Promise	Identifies an <iframe> on the tested page. See Select Target Elements.

import { ClientFunction } from 'testcafe';

fixture`TestController.switchToIframe`
    .page`https://www.devexpress.com/`;

test('Switching to an iframe', async t => {
    const getLocation = ClientFunction(() => window.location.hostname);

    // NOTE: the ClientFunction will be executed in TOP window's context
    await t.expect(getLocation()).eql('www.devexpress.com');

    await t
        .click('#TOCChatLink')
        .switchToIframe('#chat-widget')
        .typeText('#name', 'My name');

    // NOTE: the ClientFunction will be executed in IFRAME window's context
    await t.expect(getLocation()).eql('secure.livechatinc.com');
});

You can switch to the main window from the <iframe> with the t.switchToMainWindow method.

Wait Until an <iframe> Is Loaded

TestCafe implements wait mechanisms that automatically suspend the test until all required page elements are loaded and ready for interaction. These mechanisms apply to page loads, animations, XHR requests, iframe initializations, etc. TestCafe waits until the target element is ready, or reports an error if this does not happen within a timeout.

This example shows how to allow more time for an iframe to load if the default timeout is not enough.

fixture`TestController.switchToIframe`
    .page`https://js.devexpress.com/Demos/WidgetsGallery/Demo/DataGrid/Overview/jQuery/Light/`;

test('Wait for an iframe to load', async t => {
    const iframeSelector = Selector('#demoFrame', { timeout: 60000 });

    await t.switchToIframe(iframeSelector);
});

In this example, the timeout in the Selector constructor options is set to 60 seconds so that the iframe has one minute to initialize.

Select Target Elements

Use the selector parameter to identify the target of a DOM event.

You can pass any of the following objects as a selector:

• A CSS selector string.

  test('Click submit', async t => {
  
      // Click will be performed on the first element
      // that matches the CSS selector.
      await t.click('#submit-button');
  });
  

• A selector.

  import { Selector } from 'testcafe';
  
  fixture`Parameter as Selector`
      .page`https://devexpress.github.io/testcafe/example/`;
  
  const lastCheckbox = Selector('fieldset p:last-child [type="checkbox"]');
  
  test('Click last checkbox', async t => {
  
      // Click will be performed on the element selected by
      // the 'getLastItem' selector.
      await t.click(lastCheckbox);
  });
  

• A client-side function that returns a DOM element.

  test('Click first child of the body', async t => {
  
      // Click will be performed on the element returned by the function,
      // which is the third child of the document's body.
      await t.click(() => document.body.children[0]);
  });
  

• A DOM node snapshot.

  import { Selector } from 'testcafe';
  
  fixture`Parameter as DOM node snapshot`
      .page`https://devexpress.github.io/testcafe/example/`;
  
  test('Click preferred interface', async t => {
      const preferredInterface = await Selector('#preferred-interface');
  
      // Click will be performed on the element whose snapshot
      // is specified. This is an element with the '#preferred-interface' ID.
      await t.click(preferredInterface);
  });
  

• A Promise returned by a selector.

  import { Selector } from 'testcafe';
  
  const submitButton = Selector('#submit-button');
  
  fixture`Parameter as Promise by Selector`
      .page`https://devexpress.github.io/testcafe/example/`;
  
  test('Click submit', async t => {
      // Click will be performed on the element specified by the selector
      // as soon as the promise is resolved.
      await t.click(submitButton());
  });
  

TestCafe waits for the target element to become visible before it executes an action. If this does not happen within the selector timeout, the test fails.

TestCafe cannot interact with background elements. If a different element overlaps the action target, TestCafe waits for this element to disappear. If this does not happen within the selector timeout, TestCafe performs the action with the element on top of the original target. Learn more about stacking and z-index on MDN.