Introduction to Desired Capabilities

Desired Capabilities are key/value pairs that tell the browser properties such as browser name, browser version, and the path of the browser driver in the system to determine the browsers' behaviors at runtime. Desired capabilities which can be used to configure such additional driver instances as FirefoxDriver, ChromeDriver, InternetExplorerDriver, Selenium WebDriver are useful in the following cases:

  • Setting the browser and device properties in mobile testing
  • Adding extra settings to browsers in web testing

Katalon Studio allows you to define these Desired Capabilities in Project Settings. You need to identify which environment you want to customize its behaviors before defining desired capabilities in a Katalon project. After selecting the environment, you can manage its desired capabilities with:

  • Add: to add a new row to the Desired Capabilities list.
    • Provide the name of the property that you'd like to configure and its type.
    • Define value for the property. Refer to Value Types for details regarding how to input value for different types.
  • Delete: to delete selected records.
  • Clear: to clear all existing records.

Below is the list of supported environments as well as how to configure them in project settings:

Web Testing

  • Define Desired Capabilities for local execution using Chrome, Firefox, IE, Safari, Edge or Edge (Chromium).
  • Project > Settings > Desired Capabilities > WebUI > Chrome/Firefox/IE/Safari/Edge/Edge(Chromium).

Chrome/Chrome (headless)

The Desired Capabilities available for Chrome is listed here. You can locate Chrome settings file at this path: <Project_folder>\settings\internal\

Please refer to some common examples below regard to how to manage Desired Capabilities for Chrome in Katalon Studio:

  1. To start Chrome maximized by default: --start-maximized


  2. To disable notification bars : --disable-infobars


  3. To start Chrome in incognito (private) mode : --incognito


Code sample can be found in this project:

Firefox/Firefox (headless)

You can locate Firefox settings file at this path: <Project_folder>\settings\internal\

You can access the useful Desired Capabilities for Firefox through:

  1. Open Firefox browser

  2. On the address bar type in 'about:config'

  3. Search for 'browser' keys

  4. Create a key called 'firefox_profile' in Katalon Studio settings and add your settings there.

Some common Desired Capabilities:

  1. Start Firefox at default page: browser.startup.homepage


  2. Never ask for file download for file MIME type mentioned. The list of MIME type can be found here.


Code sample can be found in this project:

Internet Explorer

Internet Explorer driver supports some important capabilities which can be used to smooth execution of test on Internet Explorer. Some of these capabilities help us to disable JavaScripts, ignore the security domain setting for IE, persistent hovering, require window focus etc. These capabilities ease the way the for automation testing using Selenium Web Driver on Internet Explorer. More details on the Internet Explorer can be found here.

The most common use of Internet Explorer desired capabilities is to configure Internet Explorer without having to complete the instructions from this page. You can pass some desired capabilities to Internet Explorer so you don't need to configure your IE anymore.

  • ignoreProtectedModeSettings determines whether to skip the protected mode check. If set, tests may become flaky or unresponsive, and browsers may hang. If not set, and protected mode settings are not the same for all zones, an exception will be thrown on driver construction. Only "best effort" support is provided when using this capability.
  • ignoreZoomSetting indicates whether to skip checking that the browser's zoom level is set to 100%. Value is set to false by default.
  • enablePersistentHover determines whether persistent hovering is enabled (true by default). Persistent hovering is achieved by continuously firing mouse over events at the last location the mouse cursor has been moved to.
  • requireWindowFocus determines whether to require the IE window to focus before performing any user interaction operations (mouse or keyboard events). This capability is false by default but delivers much more accurate native events interactions.

Code sample can be found in this project:

Mobile Testing

Through using Desired Capabilities, we can communicate with Appium server by sending a POST request. For example, a user would like to run mobile test with a preferred platform, browser, orientation of the app, etc. If the user has already set the desired capability preferences setting, Appium server will start a session with the capabilities that user has set initially.

Desired capabilities is a JSON object (having keys and values pair). Within each desired capability, there are few inbuilt capabilities. We need to set the capability name as 'key' and capability value as 'value'. The capabilities keys are case-sensitive.

  • Project > Settings > Desired Capabilities > Mobile > Android/iOS.

After clicking on Android, it will display a screen with a dropdown with Device Name and Add, Delete, Clear buttons. Steps to add a property for execution are as following:

You need to select the device when configuring Desired Capabilities.


  • Device Name: the device to apply Desired Capabilities settings on.

Click Add button of command toolbar above the Desired Capabilities list.

Desired Capabilities for Mobile

A new row will be added to the list.

Desired Capabilities for Mobile

Provide the name of the property that you'd like to configure, do the same for Type and Value.

Example 1

The example below shows the desired capabilities settings for Android to enable Unicode input.

Desired Capabilities for Mobile

Example 2

The example below shows the desired capabilities settings for Android to enable device orientation.

Desired Capabilities for Mobile

Example 3

The example below shows the desired capabilities settings for Android to enable screenshot path.

Design Capabilities for Mobile

The source code is available here. For further instructions and help, please refer to Execution Settings guideline and join us on Katalon Forum.

Windows Desktop App Testing

  • Define Desired Capabilities for execution on WinAppDriver of desktop applications testing.
  • Project > Settings > Desired Capabilities > Windows.

Change updates

From version 7.0 onwards, Windows desktop application testing is available.

From version 7.5 onwards, Native Windows Recorder is available for Katalon Studio Enterprise users.

From version 7.7 onwards, Desired Capabilities for Native Windows Recorder are available.

These settings are applied to a test execution on a Windows desktop app. You are allowed to configure the WinAppDriver URL and Desired Capabilities for Windows to start a Windows Application Driver.

  • WinAppDriver URL: a URL to the WinAppDriver server. By default, Katalon Studio is set to
  • Desired Capabilities: Katalon Studio supports the same capabilities as WinAppDriver does. For Native Windows Recorder, only appArguments and appWorkingDir are supported (available in version 7.7).
    • appArguments: Support passing arguments to the Application Under Test. You can also use this desired capabilities to record action without opening a Windows.
    • appWorkingDir: Support overriding the Application Under Test's working directory.

The example below shows you:

  • The desired capabilities set for a Windows Application Under Test;

  • How to use them in the Native Windows Recorder.

Remote Server

  • Define Desired Capabilities for execution on a remote web server.
  • Project > Settings > Desired Capabilities > Remote.

There will be cases you need to connect and execute your tests on remote environments such as Selenium Grid and Katalium Server or cloud services such as Kobiton, SauceLabs or BrowserStacks. Katalon Studio does support this remote execution.

Please refer to some documents below as examples how to pass in desired capabilities from these providers:

  1. Kobiton
  2. SauceLabs
  3. BrowserStack
  4. Katalium Server

Note that this Remote option is applied for all executions which support this kind of remote execution, so you can apply them in this option as well.

Code sample can be found in this project:

Starting with Katalon Studio version 6.3.0, when Appium is set as Remote server type, the Appium Driver option is available for you to choose between Android Driver and iOS Driver. Then this selection is used for launching the correct Appium Driver to connect to Cloud Devices.

Custom Desired Capabilities

  • Define a custom option for execution.
  • Project > Settings > Desired Capabilities > Custom.

If you want to make a list of your own custom Desired Capabilities for some environments, then it's suggested to use 'Custom' settings in this case.

Custom execution is slightly different from other execution settings. Follow these steps to create a custom execution with its desired capabilities:

  1. Click Add on the command toolbar to add a custom execution to the custom execution list.

  2. Change the name if needed, then click on the More icon under the Value column.

  3. In the Custom Execution Configuration Builder dialog, specify the Driver Name for your custom execution.

    You can have at most one web driver and one mobile driver here since there may be a potential conflict if you use multiple web or mobile drivers in the same test execution.

  4. Click on the More icon under the Preferences column.

  5. The Driver Builder dialog is displayed for you to set desired capabilities for the selected Driver. The steps to add new Desired Capabilities here is similar to other settings above. Click OK when you finish.

Location of Desired Capabilities files

Defined configuration settings are saved in separated files under the "\settings\internal" location (or "\settings\external\execution" in case of custom execution), as below:

Driver Settings' file
Chrome (Headless) (headless).properties
Firefox (Headless) com.kms.katalon.core.webui.firefox (headless).properties
Edge (Chromium) com.kms.katalon.core.webui.edge
Remote Web

Passing Desired Capabilities at Runtime

Desired capabilities added to project settings apply at a global level. Configuring desired capabilities programmatically helps you scope down the application in a specific test case.

Use the sample code below to pass desired capabilities to a specific test script, which also overrides the desired capabilities predefined in project settings.

import com.kms.katalon.core.configuration.RunConfiguration
RunConfiguration.setWebDriverPreferencesProperty(key, value)

Example 1

The example below shows how to pass the desired capability to a test case. The desired capability is window-sized 100x100.

  1. Open the test case in Script mode.

  2. Use the sample code but change the key, value into window-size=100,100.

import com.kms.katalon.core.configuration.RunConfiguration
RunConfiguration.setWebDriverPreferencesProperty("args", ["window-size=100,100"])
  1. Continue writing the script, then run the test in browser.


Make sure the browser is updated by clicking Tools > Update WebDrivers > Choose browser.


The test passes successfully with window-size 100x100.

Example 2

Suppose you want to override desired capabilities of a browser before it's started. In that case, you need to define the value in the project settings first, then refer to the sample code to override that value.

The example below shows how to override Chrome window-sized 1200x600 and run the test in Chrome window-sized 100x100 instead.

  1. Click Project > Settings > Desired Capabilities > Web UI > Chrome.


  2. Insert window-size=1200,600 value > Apply and Close.


  3. Open the test case in Script mode, use the sample code above but change the key, value into window-size=100,100. Run the test in Chrome browser.



The test passes successfully with Chrome window-size 100x100 (overriding Chrome window-size 1200x600).

If you run the test in a different browser (not Chrome), the test passes without overriding desired capabilities predefined in project settings (see Example 1).