Introduction

Many web applications open additional browser windows during user interactions. Examples include payment gateways, authentication pages, document previews, reports, and external websites.

To automate these workflows, Selenium allows you to switch between browser windows using Window Handles. Each browser window has a unique identifier, making it possible to move from one window to another and continue automation seamlessly.

In this tutorial, you’ll learn how to switch between browser windows using Selenium with Python, along with practical examples, real-world scenarios, common mistakes, and best practices.

What is Window Switching?

Window Switching is the process of moving Selenium’s control from one browser window to another.

For example:

Original Window
        │
        ▼
Click Link
        │
        ▼
New Browser Window

Selenium uses window handles to identify and switch between these windows.

Why Switch Between Windows?

Window switching is required when:

Opening payment gateways
Viewing reports
Opening help pages
Accessing external websites
Completing authentication workflows

Without switching, Selenium continues interacting with the original browser window.

Methods Used

Common methods include:

driver.current_window_handle
driver.window_handles
driver.switch_to.window()

These methods allow Selenium to identify and move between browser windows.

Example

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait


# Topic: 30. Windows and Tabs - Switching Windows
# Practice site: https://the-internet.herokuapp.com/windows
# Run: pytest -s 30_examples/test_03_switching_windows.py
#
# Keep the original handle before opening a new window. Then switch between
# handles to work with each window.


def test_switch_between_windows():
    driver = webdriver.Chrome()

    try:
        driver.get("https://the-internet.herokuapp.com/windows")

        original_window = driver.current_window_handle
        driver.find_element(By.LINK_TEXT, "Click Here").click()
        WebDriverWait(driver, 10).until(lambda browser: len(browser.window_handles) == 2)

        new_window = [handle for handle in driver.window_handles if handle != original_window][0]

        driver.switch_to.window(new_window)
        assert driver.title == "New Window"

        driver.switch_to.window(original_window)
        assert driver.find_element(By.TAG_NAME, "h3").text == "Opening a new window"
    finally:
        driver.quit()

Understanding the Code

Import Required Libraries

from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait

These modules are required to launch the browser, locate web elements, and wait until the new browser window opens.

Create a Chrome Browser Instance

driver = webdriver.Chrome()

Starts a new Chrome browser session.

Open the Practice Website

driver.get("https://the-internet.herokuapp.com/windows")

Navigates to the Multiple Windows practice page.

Store the Original Window Handle

original_window = driver.current_window_handle

Stores the unique handle of the current browser window.

This handle will later be used to return to the original window.

Open a New Browser Window

driver.find_element(By.LINK_TEXT, "Click Here").click()

Clicks the Click Here link, which opens another browser window.

Wait Until the New Window Opens

WebDriverWait(driver, 10).until(
    lambda browser: len(browser.window_handles) == 2
)

Waits until Selenium detects two browser window handles.

Identify the New Window

new_window = [
    handle
    for handle in driver.window_handles
    if handle != original_window
][0]

Loops through all available window handles and selects the one that is not the original window.

This becomes the handle for the newly opened browser window.

Switch to the New Window

driver.switch_to.window(new_window)

Moves Selenium’s control from the original window to the newly opened browser window.

Verify the New Window

assert driver.title == "New Window"

Checks that the browser title matches New Window, confirming that Selenium successfully switched to the new browser window.

Switch Back to the Original Window

driver.switch_to.window(original_window)

Returns Selenium’s control to the original browser window.

Verify the Original Window

assert driver.find_element(
    By.TAG_NAME,
    "h3"
).text == "Opening a new window"

Verifies that Selenium has successfully returned to the original page.

Close the Browser

driver.quit()

Closes all browser windows and ends the WebDriver session.

Practical Example

Suppose an online banking application opens a secure payment page in a new browser window.

The automation script:

Opens the banking portal.
Clicks Proceed to Payment.
Switches to the payment window.
Verifies the payment page.
Returns to the banking portal.

Automation Testing Example

Consider an HR management system.

Clicking View Employee Contract opens the contract in another browser window.

The automation script:

Opens the employee profile.
Switches to the contract window.
Verifies the contract title.
Returns to the employee profile page.

Real-World Example

Window switching is commonly used in:

Banking applications
Payment gateways
Government portals
HR management systems
Healthcare applications
Enterprise web applications
E-commerce websites

Examples include authentication pages, invoices, payment windows, reports, and external partner websites.

Advantages of Automating Window Switching

Supports multi-window workflows.
Verifies external integrations.
Tests payment systems.
Improves automation coverage.
Simulates real user behavior.

Common Mistakes Beginners Make

Forgetting to Store the Original Window Handle

Always save the original window handle before opening another browser window.

Switching Before the New Window Opens

Use an Explicit Wait to ensure the second window is available before switching.

Assuming a Fixed Window Order

Instead of assuming the new window is always at a particular index, compare window handles to identify the newly opened window.

Forgetting to Switch Back

If additional actions must be performed on the original page, always switch back using its saved window handle.

Best Practices

Store the original window handle before opening a new window.
Wait until the new window appears.
Identify the new window dynamically.
Verify the correct window after switching.
Return to the original window when required.
Close all browser windows after the test.

Conclusion

Switching between browser windows is an essential Selenium skill for automating modern web applications. By storing the original window handle, identifying the newly opened window, and switching between them using driver.switch_to.window(), you can automate complex workflows involving multiple browser windows reliably.

Frequently Asked Questions (FAQs)

What is a window handle?

A window handle is a unique identifier assigned by Selenium to each browser window or tab.

How do I switch to another browser window?

Use:

driver.switch_to.window(window_handle)

Why should I save the original window handle?

Saving the original handle allows you to return to the first browser window after completing operations in the new one.

Can Selenium switch between multiple browser windows?

Yes.

Selenium can switch between any open browser windows or tabs using their window handles.

Where is window switching commonly used?

Window switching is widely used in payment gateways, authentication systems, document viewers, banking applications, HR portals, and enterprise software.

Key Takeaways

Every browser window has a unique window handle.
Save the original window handle before opening another window.
Use driver.window_handles to retrieve all open windows.
Use driver.switch_to.window() to switch between windows.
Identify the new window dynamically instead of assuming its position.
Window switching is an essential Selenium automation skill for multi-window workflows.