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	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:

• Do 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:

  
  
  

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.

Refer to Selenium documentation to migrate test scripts that use these classes: Removal of AbstractEventListener + EventFiringWebDriver + WebDriverEventListener.

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:

Integration	Web	Mobile	Plugin
LambdaTest	No 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: You can use older desired capabilities.	N/A
Sauce Labs	No 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

Prerequisites for mobile testing

To support mobile testing in Katalon Studio 10.0.0, verify that the following mobile drivers are already installed on your system:

• Appium UiAutomator2 Driver (version 3.x or higher) for Android

• Appium XCUITest Driver (version 7.x or higher) for iOS

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.

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, when attempting to open a browser session in Incognito mode with BiDi, the session fails to start in Chrome, Edge Chromium, and Chrome Headless. The browser session closes immediately after opening.

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.