Introduction

The current_window_handle property is an important Selenium WebDriver property used to retrieve the unique identifier (window handle) of the currently active browser window or tab.

When Selenium opens one or more browser windows, each window is assigned a unique ID called a window handle. Selenium uses these window handles to identify, switch between, and manage multiple browser windows or tabs during automation.

The current_window_handle property returns the handle of the browser window that Selenium is currently controlling.

It is commonly used together with the window_handles property when automating applications that open multiple browser windows such as payment gateways, social media logins, document viewers, and external links.

In this tutorial, you will learn what the current_window_handle property is, why it is used, its syntax, practical examples, real-world applications, common mistakes, best practices, and frequently asked interview questions.

What is current_window_handle?

The current_window_handle property returns the unique window ID (handle) of the currently active browser window.

Each browser window opened by Selenium has its own unique handle. Selenium uses these handles internally to identify and switch between browser windows.

Unlike browser commands such as close() or quit(), the current_window_handle property does not perform any browser action. Instead, it simply returns the unique identifier of the active browser window.

Why Do We Use current_window_handle?

The current_window_handle property is commonly used to:

Store the original browser window.
Identify the currently active browser window.
Switch back to the parent window after working with child windows.
Handle multiple browser windows.
Validate the active browser window.
Perform assertions during automation testing.

Syntax

driver.current_window_handle

The current_window_handle property does not accept any parameters.

Practical Example

The following example demonstrates how to retrieve the current browser window handle.

The automation script opens the Selenium practice website, stores the original window handle, opens a new browser window, retrieves all window handles, and verifies that the original window handle is still active.

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


# Topic: 5. Browser Commands - current_window_handle / window_handles
# Practice site: https://the-internet.herokuapp.com/windows
#
# current_window_handle returns the active window ID.
# window_handles returns every open window in the current session.


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

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

        original_handle = driver.current_window_handle

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

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

        all_handles = driver.window_handles

        assert original_handle in all_handles
        assert len(all_handles) == 2
        assert driver.current_window_handle == original_handle

    finally:
        driver.quit()

Output

Browser launched successfully.

Original window handle stored.

Second browser window opened successfully.

Two browser windows detected.

Current window handle matches the original browser window.

Test Passed.

Understanding the Code

Import Required Modules

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

Imports the required Selenium modules for browser automation, locating elements, and implementing explicit waits.

Launch Chrome Browser

driver = webdriver.Chrome()

Creates a new Chrome browser session.

Open the Practice Website

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

Opens the Selenium practice website that demonstrates multiple browser windows.

Retrieve the Current Window Handle

original_handle = driver.current_window_handle

Retrieves and stores the unique identifier of the currently active browser window.

This handle is later used to return to the original browser window after working with other windows.

Open a New Browser Window

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

Clicks the Click Here link, which opens a second browser window.

Wait Until the New Window Opens

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

Waits until Selenium detects that two browser windows are available.

Using an explicit wait ensures reliable synchronization.

Retrieve All Window Handles

all_handles = driver.window_handles

Retrieves a list containing the unique handles of all open browser windows.

Verify the Original Window Exists

assert original_handle in all_handles

Checks that the original browser window handle is still present among all open browser windows.

Verify Two Windows Are Open

assert len(all_handles) == 2

Confirms that exactly two browser windows are currently open.

Verify the Active Window

assert driver.current_window_handle == original_handle

Verifies that Selenium is still controlling the original browser window.

Close the Browser Session

driver.quit()

Closes all browser windows and ends the WebDriver session.

Browser Execution Flow

Launch Browser
        │
        ▼
Open Practice Website
        │
        ▼
Retrieve Current Window Handle
        │
        ▼
Store Original Window Handle
        │
        ▼
Open Second Browser Window
        │
        ▼
Wait Until Two Windows Exist
        │
        ▼
Retrieve All Window Handles
        │
        ▼
Verify Original Window Exists
        │
        ▼
Verify Active Window
        │
        ▼
Close Browser

Automation Testing Example

Suppose you’re testing an e-commerce application.

Clicking the Pay Now button opens a payment gateway in a new browser window.

The automation script can:

Store the original browser window handle.
Open the payment window.
Complete payment verification.
Close the payment window.
Switch back to the original shopping window using the stored handle.

Without current_window_handle, Selenium would not know which browser window to return to.

Real-World Example

Consider an online banking application.

Clicking Download Statement opens the statement in a new browser window.

The automation script can:

Store the original dashboard window handle.
Open the statement window.
Validate the statement.
Close the statement window.
Return to the original dashboard using the stored window handle.

Common Mistakes Beginners Make

Forgetting to Store the Original Window Handle

Incorrect

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

Without storing the original window handle, returning to the parent window becomes difficult.

Correct

original_handle = driver.current_window_handle

Always store the parent window handle before opening additional browser windows.

Confusing current_window_handle with window_handles

Many beginners assume both properties return the same value.

Incorrect assumption:

current_window_handle == window_handles

Correct:

current_window_handle returns one active window handle.
window_handles returns a list of all browser window handles.

Expecting Window Handles to Be Readable

A window handle is a unique identifier generated by the browser.

Example:

CDwindow-4E61E0F28D70A9E7A26E4F42F69D41D5

The value varies every time the browser is launched.

Best Practices

Always store the original window handle before opening a new browser window.
Use explicit waits when working with multiple browser windows.
Use current_window_handle together with window_handles.
Switch back to the original browser window after completing child window operations.
Never hardcode window handle values.

Conclusion

The current_window_handle property is an essential Selenium WebDriver property used to retrieve the unique identifier of the currently active browser window.

It plays a crucial role in handling multiple browser windows and tabs. Storing the original window handle before opening new windows makes Selenium automation scripts more reliable, maintainable, and easier to manage.

Frequently Asked Questions (FAQs)

What does `current_window_handle` return?

It returns the unique handle of the currently active browser window.

Is `current_window_handle` a method or a property?

It is a property.

Does `current_window_handle` require parentheses?

No.

Use:

driver.current_window_handle

When should I use `current_window_handle`?

Use it whenever your automation script needs to store or identify the current browser window before switching to another window.

What is the difference between `current_window_handle` and `window_handles`?

current_window_handle returns the active browser window handle.
window_handles returns a list of all open browser window handles.

Key Takeaways

The current_window_handle property returns the unique identifier of the active browser window.
The syntax is driver.current_window_handle.
It is a property, not a method.
It is commonly used when handling multiple browser windows.
Store the original window handle before opening new browser windows.
Use it together with window_handles for efficient window management.
Understanding current_window_handle is an important Selenium interview topic.