Selenium Frames

A frame, technically an iframe, embeds one HTML document inside another. Payment gateways, video players, and chat widgets commonly load inside frames. Selenium treats content inside a frame as a separate document, invisible to normal locators until you switch focus.

Diagram: A Page With A Nested Frame

[Main Page]
   |
   |-- Header
   |-- Sidebar
   |-- [iframe: Payment Form]
   |       |-- Card Number Field
   |       |-- Expiry Field
   |       |-- Pay Button
   |-- Footer

Without switching into the iframe, driver.findElement() searches only the main page and never finds the Card Number Field.

Switching Into A Frame

By Index

driver.switchTo().frame(0);

Switches to the first frame on the page, counting from zero in the order frames appear in the HTML.

By Name Or ID

driver.switchTo().frame("paymentFrame");

Switches using the frame's name or id attribute, the most reliable method when available.

By WebElement

WebElement frameElement = driver.findElement(By.cssSelector("iframe.payment"));
driver.switchTo().frame(frameElement);

Switches using a located WebElement, useful when a frame has no name or id.

Interacting Inside The Frame

driver.switchTo().frame("paymentFrame");
driver.findElement(By.id("cardNumber")).sendKeys("4111111111111111");
driver.findElement(By.id("payButton")).click();

Once inside the frame, every findElement() call searches only within that frame's content.

Returning To The Main Page

driver.switchTo().defaultContent();

This command exits every frame and returns focus to the top-level page, needed before interacting with elements outside the frame again.

Nested Frames

Some pages place frames inside other frames. Selenium requires switching into each level one at a time.

driver.switchTo().frame("outerFrame");
driver.switchTo().frame("innerFrame");

Calling switchTo().defaultContent() jumps straight back to the main page, skipping both frame levels at once.

Moving To A Parent Frame

driver.switchTo().parentFrame();

This moves up exactly one frame level instead of returning fully to the main page, useful in deeply nested frame structures.

Practical Example

A course enrollment page embeds a third-party payment widget inside an iframe named stripeFrame. A test script switches into that frame, fills the card details, submits payment, and switches back to confirm the enrollment success message on the main page.

driver.switchTo().frame("stripeFrame");
driver.findElement(By.id("cardNumber")).sendKeys("4242424242424242");
driver.findElement(By.id("submitPayment")).click();
driver.switchTo().defaultContent();
String successMsg = driver.findElement(By.id("enrollment-success")).getText();