10.2.3

Edit

Switch to window

Window selectors

Before starting to automate a desktop or web application (bot clicking, typing, etc), you need to switch to a particular window by its unique parameters:

  • Handle
  • Title
  • Name
  • Class
  • Instance
note

You can search windows by exact match or by a regular expression (REGEXPNAME, REGEXPTITLE, etc.).

Web browser windows

The following window properties can be used to switch to a particular browser window (tab) using Web driver (Chrome, IE, Firefox, Edge):

  • Text string

    • Title: see how to switch to browser window by its title:

      window('Confluence - Chrome')

    • Handle: the window handle value is dynamic so you need to get it for each bot execution using driver().getWindowHandle() or driver().getWindowHandles() methods. See how to switch to browser window by its handle:

      window('CDwindow-(EC7514DEC6898198C75C31A50145CAE7)')

Desktop windows

The following window properties can be used to switch to a particular desktop app window using Desktop driver:

  • Text string

    • Title: see how to switch to desktop app window by its title:

      window('Open file')

    • Handle: see how to switch to desktop app window by its handle:

      window('[HANDLE:0x0000000000020340]')

  • CSS: see how to switch to desktop app window by its title, class, name, instance in CSS notation:

    window('.window-class[title^=Submit]')
window('*[class$=Total Commander]')
window('[name*=Submit]')
window('.window-class[instance=4]')

  • Object

    • NAME, REGEXPNAME

      window('[NAME: New Connection]')
window('[REGEXPNAME: .Connection]')

    • CLASS, REGEXPCLASS

      window('[CLASS: V8Win]')
window('[REGEXPCLASS: V.]')

    • TITLE, REGEXPTITLE

      window('[TITLE: V8Win]')
window('[REGEXPTITLE: V.]')

    • INSTANCE

      window('[INSTANCE: 3]')

Switching to windows and browser tabs

Some web applications have many frames or multiple windows. The Web Driver assigns an alphanumeric ID to each window as soon as the WebDriver object is instantiated. This unique alphanumeric ID is called window handle . RPA driver uses this unique ID to switch control among several windows. In simple terms, each unique window has a unique ID, so that robot can differentiate when it is switching controls from one window to the other.

getWindowHandle

Purpose: to get the window handle of the current window.

Return a string of alphanumeric window handle:

def handle = driver().getWindowHandle()
// output for chrome: CDwindow-(EC7514DEC6898198C75C31A50145CAE7)

getWindowHandles

Purpose: to get the window handle of all the current windows.

Return a set of window handles:

def allHandles = driver().getWindowHandles()
// output for desktop driver: [[HANDLE:0x0000000000010768], [HANDLE:0x0000000000020340], [HANDLE:0x00000000000C075C], [HANDLE:0x0000000000040758], [HANDLE:0x00000000000107B0], [HANDLE:0x0000000000010406]]

switchTo Window

Purpose: WebDriver supports moving between named windows using the switchTo method.

switchTo().window("windowName")

Alternatively, you can pass a window handle to the switchTo().window() method. Knowing this, it’s possible to iterate over every open window like so:

// be careful with the SEARCH_ALL_WINDOWS capability as driver will close all windows when the script finishes execution!
for (String handle : driver().getWindowHandles()) {
    switchTo().window(handle);
}

You can also switch between windows with Iterators:

open('https://www.w3schools.com/tags/att_a_target.asp')
$('.w3-btn.w3-margin-bottom').click()
sleep(2000)

Set handles = driver().getWindowHandles()

firstWinHandle = driver().getWindowHandle()
handles.remove(firstWinHandle)

String winHandle = handles.iterator().next()

if (winHandle!=firstWinHandle) {
    //To retrieve the handle of second window, extracting the handle which does not match to first window handle
    secondWinHandle=winHandle //Storing handle of second window handle

    //Switch control to new window
    switchTo().window(secondWinHandle)
}

switchToExistingWindow Command

Purpose: WebDriver supports switching to existing window (already opened).

With default timeout 100 milliseconds:

    <robotics-flow>
        <robot driver="desktop" name="desktopDriver" close-on-completion="true">
            <capability name="SEARCH_ALL_WINDOWS" value="true"/>
            <script><![CDATA[
                switchToExistingWindow("[REGEXPTITLE:(.*)new (\\d+) - Notepad++]");
            ]]>
            </script>
        </robot>
    </robotics-flow>

With custom timeout specified in milliseconds:

    <robotics-flow>
        <robot driver="desktop" name="desktopDriver" close-on-completion="true">
            <capability name="SEARCH_ALL_WINDOWS" value="true"/>
            <script><![CDATA[
                switchToExistingWindow("[REGEXPTITLE:(.*)new (\\d+) - Notepad++]", 10000);
            ]]>
            </script>
        </robot>
    </robotics-flow>

With custom timeout specified in milliseconds (without Simplified API):

    <robotics-flow>
        <robot driver="desktop" name="desktopDriver" close-on-completion="true">
            <capability name="SEARCH_ALL_WINDOWS" value="true"/>
            <script><![CDATA[
                driver().switchTo().window("[REGEXPTITLE:(.*)new (\\d+) - Notepad++]", 10000);
            ]]>
            </script>
        </robot>
    </robotics-flow>

Switching to frames and popups

Purpose: WebDriver supports moving between named frames using the switchTo method.

switchTo().frame("frameName or id")
tip

See more information about iframes in Handling iFrames.

switchTo PopUp Command

Purpose: WebDriver supports moving between named popUps using the switchTo method. After you’ve triggered an action that opens a popup, you can access the alert and it will return the currently open alert object. With this object you can now accept, dismiss, read its contents or even type into a prompt. This interface works equally well on alerts, confirms, and prompts.

 alert = switchTo().alert()
tip

See more information about alerts in Handling JavaScript alerts.

Other switch commands

  • switchToLastWindow() – switching focus to the last opened window
  • switchToNextWindow() – switching focus to the next opened window after current window
  • switchToPrevWindow() – switching focus to the previously opened window before current window
  • switchToRootWindow() – switching focus to the first opened window

Examples

The example below shows how to manipulate window handles and switch between browser windows.

Expand to see how to switch to windows by their handle

<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config" scriptlang="groovy">
    <robotics-flow>
        <robot driver="chrome" name="web" close-on-completion="true">
            <script><![CDATA[
                import java.util.concurrent.TimeUnit
                timeouts().implicitlyWait(10, TimeUnit.SECONDS)

                // Launch the URL
                open('https://rpa-tutorial.s3.amazonaws.com/trainings/new-window.html')
                sleep(2000)

                // Store and Print the name of the First window on the console
                String handle= driver().getWindowHandle()
                println("========================== ${handle}")

                // Click on the Button
                $(byText('New Browser Tab')).click()
                sleep(2000)


                // Store and Print the name of all the windows open
                Set handles = driver().getWindowHandles()
                println("@@@@@@@@@@@@@@@@@@@@@@@@@@@ ${handles}")

                // Pass a window handle to the other window
                for (String handle1 : driver().getWindowHandles()) {
                    println("%%%%%%%%%%%%%%%%%%%%%%%%%%%% ${handle1}")
                    switchTo().window(handle1)
                    sleep(2000)
                }

            ]]></script>
        </robot>
    </robotics-flow>
    <export include-original-data="false" />
</config>

note

There is no cross browser solution for manipulating with tabs, so we show the example solution for Chrome.

Expand to see how to open a new tab using CTRL + click

<config xmlns="http://web-harvest.sourceforge.net/schema/1.0/config" scriptlang="groovy">
    <robotics-flow>
        <robot driver="chrome" name="web" close-on-completion="true">
            <script><![CDATA[

                timeouts(10 * 1000)
                open("https://wikipedia.org")

                element = $(byText('Wikinews'))

                // hold CTRL and click to open link in a new tab
                actions().moveToElement(element)
                         .keyDown(Keys.CONTROL)
                         .click(element)
                         .keyUp(Keys.CONTROL)
                         .perform()
                sleep(2000)

                tabs = new ArrayList (driver().getWindowHandles())
                switchTo().window(tabs.get(1))
                open('https://finance.google.com')
                driver().close()

                switchTo().window(tabs.get(0))
                open('http://www.w3schools.com')
                sleep(3000)
            ]]></script>
        </robot>
    </robotics-flow>
    <export include-original-data="false" />
</config>

← Apply element selectorsApply CSS selectors →