Migrate Katalon Studio from 9.x to 10.0.0
In version 10.0.0, Katalon Studio adopts Selenium 4 and the W3C WebDriver standard. This upgrade introduces significant changes in how browsers are configured and interacted with in test scripts, particularly the shift from using DesiredCapabilities
to Options
.
Katalon Studio 9.x vs. 10.x general comparison
9.x | 10.x | |
Selenium | 3.141.59 | 4.22 |
Appium | 2.2.0 | 2.11.1 |
Smart Locator | Requires extension | Natively supported without execution extension. |
Smart Wait | Requires extension | Natively supported without execution extension. |
BiDi (bidirectional communication) | Not supported |
|
Katalon Studio's BiDi support is currently limited to Smart Locator and Smart Wait.
Smart Locator and Smart Wait enhancement with BiDi
In Katalon Studio 10.x, Smart Locator and Smart Wait are now natively supported without requiring an extension, but these features are available only when using browsers that support BiDi.
Chrome
Edge
Firefox
Headless browsers
Katalon Studio 10.x does not support BiDi on remote web driver, TestCloud (desktop and mobile), and Safari.
Upgrade with actions required
When upgrading from 9.x to 10.x, you need to perform some additional steps to successfully migrate your existing test cases and configurations.
Transition from DesiredCapabilities
to Options
In Selenium 4, DesiredCapabilities
is deprecated in favor of Options
classes for configuring browsers. This change aligns with the W3C WebDriver protocol that Selenium 4 adheres to.
Action required:
- Replace all uses of
DesiredCapabilities
with the correspondingOptions
classes (for example,ChromeOptions
,FirefoxOptions
).Example:
Before (Katalon Studio 9.x):
DesiredCapabilities caps = DesiredCapabilities.firefox();
caps.setCapability("platform", "Windows 10");
caps.setCapability("version", "92");
caps.setCapability("build", myTestBuild);
caps.setCapability("name", myTestName);
WebDriver driver = new RemoteWebDriver(new URL(cloudUrl), caps);After (Katalon Studio 10.x):
FirefoxOptions browserOptions = new FirefoxOptions();
browserOptions.setPlatformName("Windows 10");
browserOptions.setBrowserVersion("92");
Map<String, Object> cloudOptions = new HashMap<>();
cloudOptions.put("build", myTestBuild);
cloudOptions.put("name", myTestName);
browserOptions.setCapability("cloud:options", cloudOptions);
WebDriver driver = new RemoteWebDriver(new URL(cloudUrl), browserOptions);To easily update your test scripts, use the Advanced Search feature to find and replace
DesiredCapabilities
. You can access it via , and use the Replace… option. See Advanced Search.
Also update the desired capabilities in
, such as:
W3C standard capability validation and backward compatibility
With the adoption of Selenium 4, Katalon Studio follows the W3C WebDriver standard, which is now the default protocol for configuring browser capabilities. If your project includes capabilities that do not comply with this standard, the session may fail to start.
browserName
browserVersion
(replacesversion
)platformName
(replacesplatform
)acceptInsecureCerts
pageLoadStrategy
proxy
timeouts
unhandledPromptBehavior
For an up-to-date list of standard capabilities, you can refer to the WebDriver documentation: Capabilities.
Action required:
Any capabilities not listed above must include a vendor prefix (for example,
appium:
orcloud:
). For mobile testing with Appium, Katalon Studio automatically adds theappium:
prefix to the required capabilities at runtime. However, Katalon Studio does not modify user-configured capabilities in project settings.
Example:
User-configured capabilities:
{
"app": "c0425be7-5f0e-426b-8ffe-c0bc9f21c89f",
"deviceName": "Google Pixel 7 Pro",
"vendor:option": {
"deviceVersion": "15",
"deviceId": "google_pixel_7_pro",
"usingTunnel": false
},
"platformName": "ANDROID",
"platformVersion": "android-15",
"isRealMobile": true
}Formatted user-configured capabilities following W3C:
{
"appium:app": "c0425be7-5f0e-426b-8ffe-c0bc9f21c89f",
"appium:deviceName": "Google Pixel 7 Pro",
"vendor:option": {
"deviceVersion": "15",
"deviceId": "google_pixel_7_pro",
"usingTunnel": false
},
"platformName": "ANDROID",
"appium:platformVersion": "android-15",
"appium:isRealMobile": true
}
For non-mobile (Selenium) tests, if any user-configured capabilities do not follow W3C standards, the test will fail, and Katalon Studio will display an error message.
Removal of SmartWaitWebDriver
In Katalon Studio 10.x, the SmartWaitWebDriver
class has been removed. This class was used to automatically manage waiting for elements before interacting with them. However, with Selenium 4, these capabilities are now handled natively through WebDriver decorators.
Remove any references to
SmartWaitWebDriver
from your test scripts.Use standard WebDriver methods, which now include enhanced waiting functions.
Example:
Before (Katalon Studio 9.x):
import com.kms.katalon.core.webui.driver.DriverFactory
import com.kms.katalon.core.webui.driver.SmartWaitWebDriver
import org.openqa.selenium.WebDriver
// Step 1: Initialize the WebDriver using DriverFactory
WebDriver driver = DriverFactory.getWebDriver()
// Step 2: Wrap the WebDriver with SmartWaitWebDriver to enable Smart Wait
SmartWaitWebDriver smartWaitDriver = new SmartWaitWebDriver(driver)
// Step 3: Navigate to a web page
smartWaitDriver.get("https://example.com")
// Step 4: Perform interactions (SmartWait ensures elements are ready before interacting)
smartWaitDriver.findElementById("someElementId").click()
// Step 5: Close the browser after the test
DriverFactory.closeWebDriver()After (Katalon Studio 10.x):
import com.kms.katalon.core.webui.driver.DriverFactory
import org.openqa.selenium.WebDriver
// Step 1: Initialize the WebDriver using DriverFactory
WebDriver driver = DriverFactory.getWebDriver()
// Step 3: Navigate to a web page
driver.get("https://example.com")
// Step 4: Perform interactions (SmartWait ensures elements are ready before interacting)
driver.findElementById("someElementId").click()
// Step 5: Close the browser after the test
DriverFactory.closeWebDriver()
Removal of AbstractEventListener
, EventFiringWebDriver
, and WebDriverEventListener
The AbstractEventListener
, EventFiringWebDriver
, and WebDriverEventListener
classes will no longer function in Selenium 4. If you are using these classes, update your test cases to remove or replace them with the new Selenium 4 features, which include improved support for event handling via decorators.
To migrate test scripts that use these classes, refer to Selenium documentation: Removal of AbstractEventListener + EventFiringWebDriver + WebDriverEventListener.
Refactoring of DriverFactory
DriverFactory.getChromeDriverPath()
, you might encounter the following error:groovy.lang.MissingMethodException: No signature of method: static com.kms.katalon.core.webui.driver.DriverFactory.getChromeDriverPath() is applicable for argument types: () values: []
This issue occurs because, starting from version 10.0.0, the DriverFactory
class has been refactored. The getChromeDriverPath()
method has been moved to the ChromeDriverUtil
class.
Action required:
import com.kms.katalon.core.webui.driver.DriverFactory
import com.kms.katalon.core.webui.driver.chrome
String chromeDriverPath = ChromeDriverUtil.getChromeDriverPath()
Remote browser testing support
Selenium 4 is fully supported on popular cloud-based remote testing services. If you're using a remote testing service such as LambdaTest, Sauce Labs, or BrowserStack, ensure your capabilities comply with the W3C WebDriver standard.
For cloud services that only support Selenium 4, convert your existing
DesiredCapabilities
to the new W3C-compliant format.Follow the specific instructions provided by your cloud service to ensure compatibility.
This table outlines the required configurations and compatibility for each remote testing service when using Selenium 4:
Integration | Web | Mobile | Plugin |
LambdaTest | No specific settings required. |
Note that you can use older desired capabilities. | N/A |
Sauce Labs | No specific settings required. |
| N/A |
BrowserStack |
|
|
|
If you encounter issues with element detection when migrating to BrowserStack for mobile testing, see this troubleshooting document: Unable to detect all elements during mobile testing on BrowserStack.
Transition to W3C standard for mobile testing
Thanks to the adoption of Selenium 4 and Appium java client 9.2.3, there are significant upgrades for mobile testing. These upgrades improve compatibility with the W3C WebDriver standard. However, they also require some adjustments to existing scripts.
Prerequisites for mobile testing
Appium UiAutomator2 Driver (version 3.7.0 or higher) for Android.
Appium XCUITest Driver (version 7.21.1 or higher) for iOS.
Java client version 9 refactoring
With Appium java client 9.2.3, Katalon Studio fully supports the W3C WebDriver standard. This means that JSON Wire Protocol (JWP)-based servers are no longer supported.
Replace all uses of JSON Wire Protocol with the corresponding W3C Protocol.
- AppiumDriver
import io.appium.java_client.AppiumDriver
AppiumDriver<?> driver = MobileDriverFactory.getDriver() - AndroidDriver
import io.appium.java_client.android.AndroidDriver
AndroidDriver<?> driver = MobileDriverFactory.getDriver()
import io.appium.java_client.AppiumDriver
AppiumDriver driver = MobileDriverFactory.getDriver()
To align with Selenium's standard approach for locating elements, you need to replace MobileElement
with WebElement
.
import io.appium.java_client.MobileElement
import io.appium.java_client.MobileBy
import io.appium.java_client.MobileDriver
MobileElement startelement = driver.findElementByXPath("xxx")
import org.openqa.selenium.WebElement
import org.openqa.selenium.By
WebElement startelement = driver.findElement(By.xpath("xxx"))
The TouchAction
class has been replaced by the PointerInput
class to support the W3C WebDriver standard. This change allows for more precise control over touch interactions, making it easier to simulate gestures such as swipe, tap, and drag.
import io.appium.java_client.MultiTouchAction;
import io.appium.java_client.TouchAction;
import io.appium.java_client.touch.offset.PointOption;
MultiTouchAction multiTouch = new MultiTouchAction(driver);
TouchAction action1 = new TouchAction(driver)
.press(PointOption.point(100, 500))
.waitAction(WaitOptions.waitOptions(Duration.ofMillis(500)))
.moveTo(PointOption.point(100, 100))
.release()
.perform();
import org.openqa.selenium.interactions.Pause;
import org.openqa.selenium.interactions.PointerInput;
import org.openqa.selenium.interactions.Sequence;
/* This line creates a new PointerInput object called finger. The Kind.TOUCH indicates that this input will simulate touch events (like a finger on a touchscreen). The second parameter, "finger", is an identifier for this input. */
PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
/* A Sequence is created to define a series of actions that will be performed in order. The 2 indicates that this sequence is for the second pointer input (if there are multiple). */
Sequence sequence = new Sequence(finger, 2);
/* Move the pointer immediately (0 milliseconds delay) to coordinates (100, 500) relative to the viewport. */
sequence.addAction(finger.createPointerMove(Duration.ofMillis(0), PointerInput.Origin.viewport(), 100, 500));
/* Simulate pressing down on the screen at (100, 500). */
sequence.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()));
/* Move the pointer to (100, 100) over 500 milliseconds, simulating a drag gesture. */
sequence.addAction(finger.createPointerMove(Duration.ofMillis(500), PointerInput.Origin.viewport(), 100, 100));
/* Simulate lifting the finger off the screen at (100, 100). */
sequence.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
/* Execute the sequence of touch actions. */
driver.perform(Collections.singletonList(sequence));
Known limitations and issues
Windows Desktop app testing unavailable in Katalon Studio 10.0.0
Windows Desktop app testing has been temporarily removed due to compatibility issues between Selenium 4 and WinAppDriver.
If your projects rely on Windows Desktop app testing, we recommend staying on Katalon Studio version 9.x. For more details, see FAQs.
Browserstack.getCurrentRemoteBrowser()
not supported
For remote testing on BrowserStack, the Browserstack.getCurrentRemoteBrowser()
function is currently outdated and does not operate with the setup specified for Selenium 4.
Katalon Compact Utility (KCU) not supported with BiDi
You can record with KCU when BiDi is not enabled during the recording session. However, the test will fail during execution unless you add the desired capability: webSocketUrl=false
. This turns off BiDi to ensure successful execution.
Refer to the image below for the desired capability setup details:
BiDi not working with Incognito mode in Chrome/Edge Chromium
Incognito mode works normally with BiDi in Firefox, allowing tests to execute as expected. However, the browser session fails to start in Chrome, Edge Chromium, and Chrome headless.
Set
webSocketUrl = false
in desired capabilities to disable BiDi if Incognito mode is required.
BiDi not working with custom Chrome/Edge Chromium profiles
When setting the project configuration (capabilities) to open a custom Chrome or Edge Chromium profile with BiDi enabled, the browser session closes immediately after opening.
This behavior is caused by an issue with BiDi Mapper initialization, where the browser encounters a TrustedHTML assignment problem.
org.openqa.selenium.SessionNotCreatedException: Could not start a new session. Response code 500. Message: unknown error: Failed to initialize BiDi Mapper: TypeError: Failed to set the 'innerHTML' property on 'Element': This document requires 'TrustedHTML' assignment.
Simple dialogs (alert/prompt) handler behavior
The unhandledPromptBehavior
capability, which defaults to "dismiss and notify" per W3C standards, dismisses simple dialogs automatically.
Set
unhandledPromptBehavior
toignore
so that you can handle simple dialogs manually.
To learn more about simple dialogs, you can refer to HTML Standard documentation: Simple dialogs.