Handle Browser Tabs With Selenium

1. Overview

In this tutorial, we’ll look at how we can handle browser tabs with Selenium. There are cases when clicking on a link or button will open the page in a new tab. In these cases, we must handle the tabs properly to continue with our tests. This tutorial covers opening pages in new tabs, switching between tabs, and closing tabs. For our examples, we’ll use https://testpages.herokuapp.com.

2. Setup

Based on the WebDriver setup, we’ll create a SeleniumTestBase class that takes care of the WebDriver setup and teardown. Our test classes will extend this class. We’ll also define a helper class for tab handling with Selenium. This helper class will contain methods for opening, switching, and closing tabs. These methods will be shown and explained in the following sections. We’ll initialize an instance of that helper class in the SeleniumTestBase. All examples use JUnit5.

The initialization is done in the init() method, which needs to be annotated with @BeforeAll:

@BeforeAll
public static void init() {
    setupChromeDriver();
}

The teardown or cleanup method will close the entire browser after all tests:

@AfterAll
public static void cleanup() {
    if (driver != null) {
        driver.quit();
    }
}

3. Basics

3.1. Link Target Attribute

A typical case where we need to handle tabs is when a new tab is opened when clicking on a link or button. Links on a website with the target attribute set to _blank will be opened in a new tab, e.g.:

<a href="/" >Baeldung.com</a>

Such a link opens the target in a new tab, e.g., https://www.baeldung.com.

3.2. Window Handle

In Selenium, each tab has a window handle which is a unique string. For Chrome tabs, the string starts with CDwindow, followed by 32 hex characters, e.g., CDwindow-CDE9BEF919431FDAA0FC9CB7EBBD4E1A. We need the window handle when switching to a specific tab. Therefore, we need to store the window handles during our tests.

4. Tab Handling

4.1. Open Tab

With Selenium >= 4.0, it is possible to open a new tab without using Javascript or browser hotkeys. The WebDriver provides the following method to open a new tab:

driver.switchTo().newWindow(WindowType.TAB);

As mentioned in the previous section, there are links with the target attribute set. In these cases, we don’t need to open the tab ourselves, but we need to take care of switching to and closing them. Although such a link opens the page in a new tab, it doesn’t switch to the new tab. We need to take care of that ourselves. One approach is to compare the window handles before clicking the link with the window handles after clicking the link. There should be one new window handle that represents the newly opened tab.

We can retrieve the set of window handles and the window handle of the active tab with the following methods of the WebDriver:

driver.getWindowHandles();
driver.getWindowHandle()

With the help of these methods, we can implement a helper method in the TabHelper class. It opens a link in a new tab and switches to that tab. The tab switch will only be performed if a new tab has been opened.

String openLinkAndSwitchToNewTab(By link) {
    String windowHandle = driver.getWindowHandle();
    Set<String> windowHandlesBefore = driver.getWindowHandles();

    driver.findElement(link).click();
    Set<String> windowHandlesAfter = driver.getWindowHandles();
    windowHandlesAfter.removeAll(windowHandlesBefore);

    Optional<String> newWindowHandle = windowHandlesAfter.stream().findFirst();
    newWindowHandle.ifPresent(s -> driver.switchTo().window(s));

    return windowHandle;
}

Finding the window handle is done by retrieving the window handles before and after the click on the link. The set of window handles before the click will be removed from the set of window handles after the click. The result will be the window handle of the new tab or an empty set. The method also returns the window handle of the tab before the switch.

4.2. Switch Tabs

Whenever we have multiple tabs open, we need to switch between them manually. We can switch to a specific tab with the following statement where destinationWindowHandle represents the window handle of the tab we want to switch to:

driver.switchTo().window(destinationWindowHandle)

A helper method can be implemented that takes the destination window handle as an argument and switches to the respective tab. Additionally, the method returns the window handle of the active tab before switching:

public String switchToTab(String destinationWindowHandle) {
    String currentWindowHandle = driver.getWindowHandle();
    driver.switchTo().window(destinationWindowHandle);
    return currentWindowHandle;
}

4.3. Close Tabs

After our tests or whenever we don’t need a specific tab anymore, we need to close it. Selenium provides a statement to close the current tab or the entire browser if it is the last open tab:

driver.close();

We can use this statement to close all tabs we don’t need anymore. With the following method, we can close all tabs except a specific tab:

void closeAllTabsExcept(String windowHandle) {
    for (String handle : driver.getWindowHandles()) {
        if (!handle.equals(windowHandle)) {
            driver.switchTo().window(handle);
            driver.close();
        }
    }
    driver.switchTo().window(windowHandle);
}

In this method, we loop through all window handles. If the window handle is different from the provided window handle, we’ll switch to it and close it. In the end, we’ll make sure to switch again to our desired tab.

We can use this method to close all tabs except the currently open tab:

void closeAllTabsExceptCurrent() {
    String currentWindow = driver.getWindowHandle();
    closeAllTabsExcept(currentWindow);
}

We can now use this method in our SeleniumTestBase class after each test to close all remaining tabs. This is especially useful in case a test fails to clean up the browser before starting the next test not to influence the results. We’ll call the method in a with @AfterEach annotated method:

@AfterEach
public void closeTabs() {
    tabHelper.closeAllTabsExceptCurrent();
}

4.4. Handle Tabs with Hot Keys

With Selenium, it was possible to handle tabs with browser hotkeys. Unfortunately, this seems not to work anymore because of changes to the ChromeDriver.

5. Tests

We can verify that the tab handling with our TabHelper class works as intended with a few simple tests. As mentioned in the introduction of this article, our test class needs to extend SeleniumTestBase:

class SeleniumTabsLiveTest extends SeleniumTestBase {
    //...
}

For these tests, we are declaring a few constants for URLs and locators in our test class, as shown below:

By LINK_TO_ATTRIBUTES_PAGE_XPATH = By.xpath("//a[.='Attributes in new page']");
By LINK_TO_ALERT_PAGE_XPATH = By.xpath("//a[.='Alerts In A New Window From JavaScript']");

String MAIN_PAGE_URL = "https://testpages.herokuapp.com/styled/windows-test.html";
String ATTRIBUTES_PAGE_URL = "https://testpages.herokuapp.com/styled/attributes-test.html";
String ALERT_PAGE_URL = "https://testpages.herokuapp.com/styled/alerts/alert-test.html";

In our first test case, we are opening a link in a new tab. We are verifying that we have two tabs open and can switch between them. Note that we always store the respective window handle. The following code represents this test case:

void givenOneTab_whenOpenTab_thenTwoTabsOpen() {
    driver.get(MAIN_PAGE_URL);

    String mainWindow = tabHelper.openLinkAndSwitchToNewTab(LINK_TO_ATTRIBUTES_PAGE_XPATH);
    assertEquals(ATTRIBUTES_PAGE_URL, driver.getCurrentUrl());

    tabHelper.switchToTab(mainWindow);
    assertEquals(MAIN_PAGE_URL, driver.getCurrentUrl());
    assertEquals(2, driver.getWindowHandles().size());
}

In our second test, we want to verify that we can close all tabs except our first open tab. We need to provide the window handle of that tab. The following code shows this test case:

void givenTwoTabs_whenCloseAllExceptMainTab_thenOneTabOpen() {
    driver.get(MAIN_PAGE_URL);
    String mainWindow = tabHelper.openLinkAndSwitchToNewTab(LINK_TO_ATTRIBUTES_PAGE_XPATH);
    assertEquals(ATTRIBUTES_PAGE_URL, driver.getCurrentUrl());
    assertEquals(2, driver.getWindowHandles().size());

    tabHelper.closeAllTabsExcept(mainWindow);

    assertEquals(1, driver.getWindowHandles().size());
    assertEquals(MAIN_PAGE_URL, driver.getCurrentUrl());
}

6. Conclusion

In this article, we learned how we handle browser tabs with Selenium. We covered how we can distinguish different tabs with their respective window handles. Opening tabs, switching tabs, and closing them when we are finished are covered in this article.