Skip to main content

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.x10.x
Selenium3.141.594.22
Appium2.2.02.11.1
Smart LocatorRequires extensionNatively supported without execution extension.
Smart WaitRequires extensionNatively supported without execution extension.
BiDi (bidirectional communication)Not supported
  • Default support for execution using Smart Locator and Smart Wait.

  • Disable BiDi by setting "webSocketUrl": false in the desired capabilities.

Note:
  • 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.

Supported browsers when BiDi is enabled:
  • Chrome

  • Edge

  • Firefox

  • Headless browsers

Known limitation:
  • 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 corresponding Options 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 Action > Advanced Search > File Search, and use the Replace… option. See Advanced Search.

  • Also update the desired capabilities in Project > Settings > Desired Capabilities, such as:

    Create DC for FireFox

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.

Here is the list of W3C WebDriver standard capabilities:
  • browserName

  • browserVersion (replaces version)

  • platformName (replaces platform)

  • 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: or cloud:). For mobile testing with Appium, Katalon Studio automatically adds the appium: 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.

Action required:
  • 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

If you're using Katalon Studio version 10.0.0 and previously relied on the method 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:

1. Replace the previous import:
import com.kms.katalon.core.webui.driver.DriverFactory
2. Use the following import and updated method:
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.

Action required:
  • 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:

IntegrationWebMobilePlugin
LambdaTestNo specific settings required.
  • Include user name and access key in the remote URL or in desired capabilities.

  • Place lt:options for other capabilities.

  • Use lt:options for device in mobile native app

Note that you can use older desired capabilities.

N/A
Sauce LabsNo specific settings required.
  • Put all desired capabilities in sauce:options.

N/A
BrowserStack
  • Place browserName in desired capabilities.

  • Place remaining desired capabilities in bstack:options.

  • Place platformName in desired capabilities.

  • Place remaining desired capabilities in bstack:options.

  • Not supported

Trouble:

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

To support mobile testing and resolve issues relating to Swipe action in Katalon Studio 10.0.0, verify that the following mobile drivers are already installed on your system:
  • 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.

Action required:
  • Replace all uses of JSON Wire Protocol with the corresponding W3C Protocol.

Method 1: AppiumDriver and AndroidDriver
Before (Katalon Studio 9.x):
  • AppiumDriver
    import io.appium.java_client.AppiumDriver
    AppiumDriver<?> driver = MobileDriverFactory.getDriver()
  • AndroidDriver
    import io.appium.java_client.android.AndroidDriver
    AndroidDriver<?> driver = MobileDriverFactory.getDriver()
After (Katalon Studio 10.x):
import io.appium.java_client.AppiumDriver
AppiumDriver driver = MobileDriverFactory.getDriver()
Method 2: Replace MobileElement with WebElement

To align with Selenium's standard approach for locating elements, you need to replace MobileElement with WebElement.

Before (Katalon Studio 9.x):
import io.appium.java_client.MobileElement
import io.appium.java_client.MobileBy
import io.appium.java_client.MobileDriver
MobileElement startelement = driver.findElementByXPath("xxx")
After (Katalon Studio 10.x):
import org.openqa.selenium.WebElement
import org.openqa.selenium.By
WebElement startelement = driver.findElement(By.xpath("xxx"))
Method 3: Replace TouchAction with PointerInput for touch interactions

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.

Before (Katalon Studio 9.x):
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();
After (Katalon Studio 10.x):
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.

We are working on an alternative implementation for Desktop app testing in future releases that will be compatible with Selenium 4 and Katalon Studio.
Warning:
  • 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.

Workaround:
  • 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.

You might see the following error:
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.

Workaround:
  • Set unhandledPromptBehavior to ignore so that you can handle simple dialogs manually.

To learn more about simple dialogs, you can refer to HTML Standard documentation: Simple dialogs.

Was this page helpful?