Skip to main content

Switch Frame

Switches the browser context to an iframe element or back to the main document. Required before interacting with elements inside iframes.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing the node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If Continue On Error property is true, no error is caught when the project is executed, even if the Catch node is used.

Input​

  • Browser ID - The browser session identifier from the Open Browser node.
  • Selector - The XPath or CSS selector to locate the iframe element (not required when Switch To Root is enabled).

Options​

  • Selector Type - Type of selector used:

    • XPath - Use XPath expression (default)
    • CSS - Use CSS selector

  • Switch To Root - Switch back to the main document from an iframe. When enabled, Selector is not required. Default is false.

  • Wait Timeout (sec) - Maximum time to wait for the iframe element to appear. Default is 5 seconds.

Examples​

Switch to Iframe​

Browser ID: {{browser_id}}
Selector: //iframe[@id='content-frame']
Switch To Root: false

Switch Back to Main Document​

Browser ID: {{browser_id}}
Switch To Root: true

Work with Iframe Content​

1. Switch Frame node (enter iframe):
   Browser ID: {{browser_id}}
   Selector: //iframe[@name='payment-form']
   Switch To Root: false

2. Type Text node (in iframe):
   Browser ID: {{browser_id}}
   Selector: //input[@name='card-number']
   Text: 4111111111111111

3. Switch Frame node (exit iframe):
   Browser ID: {{browser_id}}
   Switch To Root: true

Nested Iframes​

1. Switch Frame (outer iframe):
   Browser ID: {{browser_id}}
   Selector: //iframe[@id='outer']

2. Switch Frame (inner iframe):
   Browser ID: {{browser_id}}
   Selector: //iframe[@id='inner']

3. Click Element (in inner iframe):
   Browser ID: {{browser_id}}
   Selector: //button[@id='submit']

4. Switch Frame (back to main):
   Browser ID: {{browser_id}}
   Switch To Root: true

Understanding Iframes​

Iframes (inline frames) are separate HTML documents embedded within a page. They have their own DOM context, so you must switch to the iframe before interacting with its content.

<!-- Main document -->
<html>
  <body>
    <h1>Main Page</h1>
    <iframe src="embedded.html" id="my-frame">
      <!-- Content from embedded.html -->
    </iframe>
  </body>
</html>

Tips​

  • Always switch to an iframe before interacting with its content
  • Use Switch To Root to return to the main document
  • Browser stays in iframe context until you switch back
  • For nested iframes, switch to each level sequentially
  • Use browser dev tools to identify iframes on the page
  • After switching to root, you can switch to a different iframe

Common Errors​

  • "Browser ID cannot be empty" - Connect to an Open Browser node
  • "Selector cannot be empty" - Provide an XPath or CSS selector for the iframe, or enable 'Switch To Root'
  • "Frame element not found within X seconds" - The iframe doesn't exist or takes longer to load
  • "Timeout cannot be empty" - Provide a timeout value
  • "Element not found" - You may be in the wrong frame context. Ensure you switched to the correct iframe