How to Use Selenium WebDriver in Katalon Studio

Introduction

Selenium WebDriver is a tool for automating web application testing, in particular, to verify that apps work as expected. It aims to provide a friendly API that's easy to explore and understand, and easier to use than the Selenium-RC (1.0) API, which will help make your tests easier to read and maintain.

Katalon Studio uses the Selenium engine for automated testing of web applications. This means that Katalon uses the Selenium WebDriver framework and hides the complexities of dealing with WebDriver from users. You don't have to worry about WebDriver, but instead, work with Katalon keywords only.

You can still use WebDriver directly if you prefer. Or, if you need more flexibilities than Katalon provides, you can simply write scripts working with WebDriver directly. In this article, I'll present a few best practices to benefit from WebDriver, which may be of interest to experienced automation testers who want to work with Selenium directly.

How Katalon Studio Uses Selenium WebDriver

The most important thing to mention is that you do not have to create a WebDriver instance. Katalon does it for you when you call the WebUI.openBrowser keyword.

import org.openqa.selenium.WebDriver
import org.openqa.selenium.chrome.ChromeDriver
import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI

WebUI.openBrowser('')
WebDriver driver = new ChromeDriver()

In the code above, Chrome is used as an example, but you can create any other driver type, such as FirefoxDriver and InternetExplorerDriver. You may also have to set a Java system property with the driver location at the start of your test (as in the code below). To terminate the WebDriver instance, call driver.close().

System.setProperty("webdriver.chrome.driver", "C:\\test\\chromedriver.exe")

In both cases, you get a new browser instance and you can use it in Katalon. The only difference is that (at this point) you cannot use Katalon WebUI keywords with your manually created WebDriver instance. For these purposes, there is a library called DriverFactory.

DriverFactory

Katalon developers were aware that WebDriver methods may be useful for users, so they introduced the DriverFactory library. This library is responsible for manipulation with the WebDriver instance and offers a few useful methods for using WebDriver in Katalon.

One of the biggest benefits of this library is the changeWebDriver() method. As I mentioned earlier, it is not possible to use Katalon keywords with custom WebDriver instances by default, but as soon as you call this method, you'll be able to use them. Katalon will set your driver as a default one, and the full Katalon functionality is provided.

import org.openqa.selenium.WebDriver
import org.openqa.selenium.chrome.ChromeDriver
import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
System.setProperty("webdriver.chrome.driver", "C:\\test\\chromedriver.exe")

WebDriver driver = new ChromeDriver()

// this won't work and exception would be thrown
WebUI.click(testObject)

DriverFactory.changeWebDriver(driver)

// now, it is working as expected
WebUI.click(testObject)

Another great method of the DriverFactory library is getWebDriver(). It is the opposite of the case above - you can get an instance of WebDriver created by Katalon and use WebDriver's methods afterward.

import org.openqa.selenium.WebDriver
import com.kms.katalon.core.webui.driver.DriverFactory
import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI

WebUI.openBrowser('')
WebDriver myDriver = DriverFactory.getWebDriver()

Using this method, you get a WebDriver instance created by the openBrowser() method. Another useful method is DriverFactory.getChromeDriverPath(), which returns the path to Chrome/Firefox/any other driver (just replace the browser name in the method) from the Katalon folder. You can use it instead of hardcoding a path to WebDriver, as above.

There are also other methods and properties of the DriverFactory class. For further information, please visit the API documentation page.

Multiple WebDrivers

Katalon Studio currently does not allow you to use multiple drivers at once. When you call the WebUI openBrowser() twice, it terminates the first browser window and opens the second one. If you need multiple drivers, you can create them by yourself and switch between them.

import org.openqa.selenium.WebDriver
import org.openqa.selenium.chrome.ChromeDriver

import com.kms.katalon.core.webui.driver.DriverFactory

System.setProperty("webdriver.chrome.driver", DriverFactory.getChromeDriverPath())
WebDriver driver1 = new ChromeDriver()
WebDriver driver2 = new ChromeDriver()

DriverFactory.changeWebDriver(driver1)
// first part of test

DriverFactory.changeWebDriver(driver2)
// second part of test

driver1.close()
driver2.close()

Your tests may require multiple browser instances to, for example, test the communication between two separate browsers. You may need to create multiple drivers and switch between them dynamically.

Sample Usage and Benefits of Selenium WebDriver

Operations on Multiple Web Elements

Selenium users are usually familiar with the WebDriver method findElements(), which returns a list of WebElements found by a specified selector. This method may be useful when you need to do something with multiple elements like tally them or click on all of them.

See this code as an example of how to count the total options in a select box using WebDriver.

import org.openqa.selenium.By
import org.openqa.selenium.WebDriver
import org.openqa.selenium.chrome.ChromeDriver

System.setProperty("webdriver.chrome.driver", DriverFactory.getChromeDriverPath())
WebDriver driver = new ChromeDriver()
List optionsList = driver.findElements(By.xpath("//select[@id='selectBox1']/option"))

int numberOfOptions = optionsList.size()

Or, use the foreach loop to manipulate the WebElements list (only the last row from the previous code snippet is changed).

for(WebElement option in optionsList) {
println option.getAttribute("value")
}

Easy Transition From Java Selenium Projects to Katalon

If you already have Selenium projects written in Java, it is easy to start using Katalon without losing your previous work. All your Java code will work also in Katalon. You should only call the changeWebDriver() method to be able to use Katalon's built-in keywords.

Options and Capabilities

You can simply set different options and/or capabilities to your WebDriver (and set them only locally in a test case, only if you need them). You then just pass them to a WebDriver constructor at the time when you create it.

This is a sample code for setting a custom download path (and download without prompt):

import org.openqa.selenium.WebDriver
import org.openqa.selenium.chrome.ChromeDriver
import org.openqa.selenium.chrome.ChromeOptions
import com.kms.katalon.core.webui.driver.DriverFactory

String downloadPath = "C:\\customDownloadFolder\\"

Map<String, Object> chromePrefs = new HashMap<String, Object>()
chromePrefs.put("download.default_directory", downloadPath)
chromePrefs.put("download.prompt_for_download", false)

System.setProperty("webdriver.chrome.driver", DriverFactory.getChromeDriverPath())
ChromeOptions options = new ChromeOptions()
options.setExperimentalOption("prefs", chromePrefs)
WebDriver driver = newChromeDriver(options)

Actions

Actions is a powerful API for emulating complex user gestures from Selenium. If you want to use it, you need an instance of WebDriver as this instance is required in a constructor of the Actions class.

import org.openqa.selenium.WebDriver
import org.openqa.selenium.interactions.Actions
import com.kms.katalon.core.webui.driver.DriverFactory

WebDriver driver = DriverFactory.getWebDriver()
Actions myAction = new Actions(driver)

Conclusion

In this article, I introduced basic ways to work with WebDriver instances in Katalon Studio. From my point of view, the main advantage of this approach is that you can benefit from both sides — Katalon Studio and WebDriver. If something is difficult to do in Katalon, do it in WebDriver! And vice versa. Don't be afraid of using WebDriver; sometimes you can find a much simpler solution.