Skip to main content

Windows and Frames

In Outomated, the W3C webdriver is responsible for driving the browser. It works by taking commands in form of REST api calls and performing actions on the browser by directly communicating with it.

When a test runs, a browser window is opened and webdriver connects with it. As webdriver receives commands, it sends equivalent actions to the browser window it is connected to. By default all actions are performed at the top level browsing context (means the top frame of a page/document). Webdriver can be connected with only one browser window/tab at a time.

Imagine in a running test, a new url is required to be opened in a new tab or window. We can do so by using a new window opening function, but in order to run further commands on the new window/tab, webdriver has to be switched there so that it can connect to it. Unless done, webdriver remains connected to the older window/tab.

Similar to window or tab, in order to access content in an iframe, we've to switch webdriver to the desired iframe. This is because by default webdriver sends actions to top browsing context only whereas iframe is a child browsing context in a document.

To summarize this concept, whenever we need to work with more than one browser windows, tabs or embedded iframes, webdriver has to be switched to the desired location before tests can interact with them.

Our documentation will teach you how to easily work with multiple windows/tabs and iframe. ZWL has some functions that automatically switches webdriver to new window/tab so you can do more than one task by calling one function. Let's understand how all this work.

Managing multiple windows/tabs#

If your test just need to open a url in a new window/tab and work only there, don't worry about understanding how switching among windows/tabs work. Use following to open a url in a new window/tab and ZWL makes the switch automatically:

openUrlNewWin('https://google.com', 'window')# opens url in a new window and switches webdriver
openUrlNewWin('https://google.com')# opens url in a new tab and switches webdriver

However if you need to switch back to the previous window/tab or manage multiple of them, understand how it works.

Whenever a new window/tab is opened, webdriver assigns them a unique id that can be used to switch to it. Functions that open a new window/tab don't return their unique id by default because it's an additional piece of work. If you need it, there is a separate function for that. See below example that shows different ways of switching to windows:

  • Keep window ids beforehand for easy identification and switching#

    After opening a new window/tab, keep it's id in a variable and later use the variable for switching. This is the preferred way for managing multiple windows.

    openUrl('https://google.com')googleTabId = getCurrentWinId()
openUrlNewWin('https://www.bing.com/')bingTabId = getCurrentWinId()
openUrlNewWin('https://duckduckgo.com/')duckTabId = getCurrentWinId()
assertTrue(containsString(getCurrentUrl(), 'duck')) # current tab is duckduckgo
# switch to google tabswitchWin(googleTabId)assertTrue(containsString(getCurrentUrl(), 'google')) # current tab is google
# switch to bingswitchWin(bingTabId)assertTrue(containsString(getCurrentUrl(), 'bing')) # current tab is bing

  • Iterate through all window ids#

    If you don't want to keep window ids beforehand, get all opened window ids as a list, iterate through them, switch and match the url or title. Using this method is discouraged when there are many opened windows. See how it works below:

    openUrl('https://google.com')openUrlNewWin('https://www.bing.com/')openUrlNewWin('https://duckduckgo.com/')
# For switching to google's tab, get all window ids and # remove the current window id from the list so that we# don't waste time switching to where we already areallWins = getAllWinIds()removeFrom(allWins, getCurrentWinId()) # remove current window idfound = falsefor i = 0 to length(allWins) - 1 {  if (!found) {    switchWin(allWins[i]) # switch to tab    if containsString(getCurrentUrl(), 'google') {      found = true    }  }}
# we're at google's tab, just asserting to prove. It wouldn't be required in a real test.assertTrue(found)

Switching among iframes#

See iframe on mdn if you're not familiar with it or with nested browsing contexts.

Iframes create a nested browsing context, which means if a page has iframes, there are multiple browsing contexts on it. The main content of the page is called top level browsing context (or top frame) and each iframe is called a nested browsing context or nested frames.

To switch among iframes and top level browsing context (to be able to interact with elements in it), there are a few functions you can use. See below:

  • Switch to a nested frame#

    switchFrame(0)# switches to the first iframe using 0 based index,# nested within the current browsing context
# Or
switchFrame(findElement('googleMap', by.testId))# switches to frame selected by given selector# nested within the current browsing context

    switchFrame works by going down the DOM tree from it's current browsing context. It can never switch to frames in upward direction. This means, for instance, if the current frame is the top frame (the main page) and there are 2 nested iframes, using switchFrame(0) or switchFrame(firstFrameElementId) will switch to the 1st nested frame.

  • Switch to top frame or parent frame#

    Once you've switched to a nested frame, now you can either switch back to the top frame or any nested frame inside the current frame. This is because switchFrame looks only within it's current browsing context and down the DOM tree. To switch back to the top frame or parent frame (one step upward direction):

    switchWin() # when no arguments are given, it switches the top frame.
# Or
switchParentFrame()# switches frame one step upward direction. if the current browsing context# is a frame nested within the top frame, this will switch to the top frame.

Resizing windows#

You can resize the browser window and move it to a desired position on the computer's screen. See below:

maximizeWin() # maximize the window
fullScreenWin() # fullscreen the window
setWinPosition(300, 600) # positions the window on screen to 300x600
setWinSize(500, 500) # sets window's size to 500x500

See Api Reference for all available functions.