Shifting from Desired Capabilities to Options

[bindu.nair]

Hi,

I am encountering an issue after updating to Katalon’s 10.x version. Previously, I used the `DesiredCapabilities` feature to download PDF files from Chrome to a specific location on my machine. With the update, this feature is no longer available.

I was using the following `DesiredCapabilities` settings for this purpose:

My script clicks on a link that should initiate a PDF download. Prior to the update, the PDF would automatically download to the specified location. Now, however, the PDF opens in a new tab instead of downloading, despite my Chrome settings being configured to download files to the “Download” folder.

Could you please provide assistance on how to convert these `DesiredCapabilities` settings to use `Options` in Katalon 10.x, so that the PDFs download directly?

Thanks.

[Monty_Bagati]

Transition from DesiredCapabilities to Options: In Selenium 4, you’ll configure browsers using Options classes instead of DesiredCapabilities. You’ll need to replace instances of DesiredCapabilities with the corresponding Options class. For example, use ChromeOptions for Chrome and FirefoxOptions for Firefox.

create a test listener or use some reusable function and put the below code or shift to 9.x version for using desired capabilities

========

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

import org.openqa.selenium.chrome.ChromeOptions

import org.openqa.selenium.WebDriver

Map<String, Object> prefs = [

“download.default_directory”: “C:\\Downloads”,

“download.prompt_for_download”: false,

“plugins.always_open_pdf_externally”: true

]

ChromeOptions options = new ChromeOptions()

options.setExperimentalOption(“prefs”, prefs)

WebDriver driver = new org.openqa.selenium.chrome.ChromeDriver(options)

DriverFactory.changeWebDriver(driver)

===========

[bindu.nair]

Thank you Monty for your quick response.

I encountered an error with the code you provided, specifically on these lines:

“download.default_directory”: “C:\\Downloads”,

“download.prompt_for_download”: false,

“plugins.always_open_pdf_externally”: true

I used Katalon’s AI to update the code and created a test listener, but the PDF file is still opening in a new Chrome tab. Do you know what might be causing this issue in version 10.x?

class pdfDownload {

/\*\*

 \* Executes before every test case starts.

 \* **@param** testCaseContext related information of the executed test case.

 \*/

@BeforeTestCase

**def** sampleBeforeTestCase() {

	Map<String, Object> prefs = **new** HashMap<String, Object>();

prefs.put(“download.default_directory”, “C:\\Users\\bindu\\Downloads”);

prefs.put(“download.directory_upgrade”,true)

prefs.put(“download.prompt_for_download”, false);

prefs.put(“plugins.always_open_pdf_externally”, true);

prefs.put(“profile.default_content_settings.popups”,0);

prefs.put(“profile.content_settings.exceptions.automatic_downloads.*.setting”,1);

ChromeOptions options = new ChromeOptions();

options.setExperimentalOption(“prefs”, prefs);

WebDriver driver = new ChromeDriver(options);

DriverFactory.changeWebDriver(driver);

}

}

[kazurayam]

@bindu.nair

Does your Test Case script still calls WebUI.openBrowser() keyword?

---

In your Test Listener named pdfDownload, you have the following statement:

WebDriver driver = new ChromeDriver(options);

This statement will open a Chrome browser window with the options set.

But as soon as your Test Case script calls the WebUI.openBrowser() keyword, I think, the already-opened Chrome browser will be forced to close, and a new Chrome browser without the options will open.

Effectively your Test Listener becomes useless.

[kazurayam]

To: @Elly_Tran and Katalon

I checked the Katalon’s official documentation

Set up Desired Capabilities for WebUI Testing in Katalon Studio | Katalon Docs

I think that this document should provide a solution to @bindu.nair: how to specify the download directory in Chrome.

I checked the description for Chrome:

Set up Desired Capabilities for WebUI Testing in Katalon Studio | Katalon Docs

The description for Chrome options is very poor. It doesn’t answer to @bindu.nair

I checked the description for Firefox:

Set up Desired Capabilities for WebUI Testing in Katalon Studio | Katalon Docs

It explains much about browser.download.dir etc.

The document explains more for Firefox but not for Chrome at all. Why?

I hope the Katalon’s documentation to cover a straight forward (copy&paste-able) answer to @bindu.nair

[nghi.phan]

Hi Mr. Kazu,

Thank you for pointing this out! I’m not entirely sure about the reason, but I’ve notified our team to review. Really appreciate your detailed feedback and support!

Bella

[bindu.nair]

Hi @kazurayam @Monty_Bagati

Thank you for pointing out the mistake in calling the browser to open a second time. That was exactly what I was doing wrong.

Below is the test case I am working with. Could you please guide me on how to use the Test Listener Chrome browser window with the options set, to run this test case

Test Case:

WebUI.openBrowser(‘’)
WebUI.navigateToUrl(GlobalVariable.URL)
WebUI.maximizeWindow()
WebUI.setText(findTestObject(‘Object Repository/Login/input_User ID_username’), GlobalVariable.Username)
WebUI.setText(findTestObject(‘Object Repository/Login/input_P_password’), GlobalVariable.Password)
WebUI.setText(findTestObject(‘Object Repository/Login/input_Validation Code_token’), CustomKeywords.‘mfa.readmfa.GetMFATokenFiler’())
WebUI.click(findTestObject(‘Object Repository/Login/button_Continue’))
WebUI.click(findTestObject('Object Repository/Login/a_User Agreement)) //The user agreement is the PDF that needs to be downloaded

Test Listener Code:

class pdfDownload {

@BeforeTestCaseBeforeTestCase

def sampleBeforeTestCase() {

Map<String, Object> prefs = new HashMap<String, Object>();

prefs.put(“download.default_directory”, “C:\\Users\\bindu\\Downloads”);

prefs.put(“download.directory_upgrade”,true)

prefs.put(“download.prompt_for_download”, false);

prefs.put(“plugins.always_open_pdf_externally”, true);

prefs.put(“profile.default_content_settings.popups”,0);

prefs.put(“profile.content_settings.exceptions.automatic_downloads.*.setting”,1);

ChromeOptions options = new ChromeOptions();

options.setExperimentalOption(“prefs”, prefs);

WebDriver driver = new ChromeDriver(options);

DriverFactory.changeWebDriver(driver);

}

}

[Monty_Bagati]

create a keyword instead in katalon and call it in test case wherever required. try this once

[kazurayam]

You do not need a Test Listener; you do not need a Custom Keyword. You can write everything in a Test Case script.

//WebUI.openBrowser(‘’)
Map<String, Object> prefs = new HashMap<String, Object>();
prefs.put(“download.default_directory”, “C:\\Users\\bindu\\Downloads”);
prefs.put(“download.directory_upgrade”,true)
prefs.put(“download.prompt_for_download”, false);
prefs.put(“plugins.always_open_pdf_externally”, true);
prefs.put(“profile.default_content_settings.popups”,0);
prefs.put(“profile.content_settings.exceptions.automatic_downloads.*.setting”,1);
ChromeOptions options = new ChromeOptions();
options.setExperimentalOption(“prefs”, prefs);
WebDriver driver = new ChromeDriver(options);
DriverFactory.changeWebDriver(driver);

WebUI.navigateToUrl(GlobalVariable.URL)
WebUI.maximizeWindow()
WebUI.setText(findTestObject(‘Object Repository/Login/input_User ID_username’), GlobalVariable.Username)
WebUI.setText(findTestObject(‘Object Repository/Login/input_P_password’), GlobalVariable.Password)
WebUI.setText(findTestObject(‘Object Repository/Login/input_Validation Code_token’), CustomKeywords.‘mfa.readmfa.GetMFATokenFiler’())
WebUI.click(findTestObject(‘Object Repository/Login/button_Continue’))
WebUI.click(findTestObject('Object Repository/Login/a_User Agreement)) //The user agreement is the PDF that needs to be downloaded

If you want improve this by any means, do it yourself.

[kazurayam]

Selenium 4 has deprecated the “Desired Capabilities” class. The Selenium project uses the term “Browser Options” instead.

• Browser Options | Selenium

The title of the Katalon document page “Set up Desired Capabilities” is inappropriate for v10.x. The term “Desired Capability” should not be used for v10.x. The title should rather be “Set up Browser Options”.

Also, the GUI should not display “Desired Capability” any longer for v10:

[dineshh]

your issue resolved or still facing any challenges? @bindu.nair

[gmarichal]

I would strongly recommend to encapsulate this logic in a customKeyword so you can call it on every test case you need without the risk of missing a single character and waste time fixing the issue.

Also, CustomKeywords can be exported as test Artifacts, so it can be shared with other projects or teammates who need this solution.

[kazurayam]

Let me go back to the original post by @bindu.nair.

@bindu.nair asked

Could you please provide assistance on how to convert these DesiredCapabilities settings to use Options in Katalon 10.x, so that the PDFs download directly?

However @bindu.nair did not show to us how exactly he/she coded the prefs:

Therefore, nobody can answer to his/her question:

[kazurayam]

@gmarichal

I would strongly recommend to encapsulate this logic in a customKeyword

I think I don’t need to write a custom keyword.

If @bindu.nair set-up the Project Settings>Browser Options (formally known as Desired Capability) > Web UI >Chrome appropriately, he should be able to download a PDF file into a folder he/she preferes.

---

I examined a hands-on, and got a success. Let me copy&paste it.

I wrote a Test Cases/TC2:

import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths

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

import com.kms.katalon.core.testobject.ConditionType
import com.kms.katalon.core.testobject.TestObject
import com.kms.katalon.core.webui.driver.DriverFactory
import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI

/**
 * TC2
 */

TestObject makeTestObject(String id, String xpath) {
	TestObject tObj = new TestObject(id)
	tObj.addProperty('xpath', ConditionType.EQUALS, xpath)
	return tObj
}

String username = 'kazurayam'
Path outdir = Paths.get("/Users/${username}/tmp")
Files.createDirectories(outdir)
Path downloadedFile = outdir.resolve('SDG_Guidelines_AUG_2019_Final.pdf')
if (Files.exists(downloadedFile)) {
	Files.delete(downloadedFile)
}

WebUI.openBrowser('')

WebUI.navigateToUrl('https://www.un.org/sustainabledevelopment/news/communications-material/')
WebUI.maximizeWindow()

TestObject anchor = makeTestObject('guidlines', '//section[@id="content"]//a[contains(., "guidelines")]')
WebUI.verifyElementPresent(anchor, 10)
WebUI.click(anchor)
WebUI.delay(10)

WebUI.closeBrowser()

// make sure if the pdf file has been successfully downloaded
assert Files.exists(downloadedFile)

and I setup the Project settings as follows:

I used Katalon Studio v10.3.2 on macOS 15.6.2.

This code set worked for me. I could download a PDF file and save it into the folder I wanted.

[kazurayam]

By the way, the following Test Case script does the same as TC2 without the project settings using GUI:

import java.nio.file.Files
import java.nio.file.Path
import java.nio.file.Paths

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

import com.kms.katalon.core.testobject.ConditionType
import com.kms.katalon.core.testobject.TestObject
import com.kms.katalon.core.webui.driver.DriverFactory
import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI

/**
 * TC1
 */

// make a Test Object
TestObject makeTestObject(String id, String xpath) {
	TestObject tObj = new TestObject(id)
	tObj.addProperty('xpath', ConditionType.EQUALS, xpath)
	return tObj	
}

// define a folder to save a PDF
String username = 'kazuarayam'
Path outdir = Paths.get("/Users/${username}/tmp")
Files.createDirectories(outdir)

// remove the pdf file that were previously downloaded
Path downloadedFile = outdir.resolve('SDG_Guidelines_AUG_2019_Final.pdf')
if (Files.exists(downloadedFile)) {
	Files.delete(downloadedFile)	
}

// setup ChromeOptions
Map<String, Object> prefs = new HashMap<String, Object>();
prefs.put("download.default_directory", outdir.toString());
prefs.put("download.prompt_for_download", false);
prefs.put("download.directory_upgrade",true)
prefs.put("plugins.always_open_pdf_externally", true);
ChromeOptions options = new ChromeOptions();
options.setExperimentalOption("prefs", prefs);

// opewn Chrome browser
WebDriver driver = new ChromeDriver(options);
DriverFactory.changeWebDriver(driver);

// navigate to a URL
WebUI.navigateToUrl('https://www.un.org/sustainabledevelopment/news/communications-material/')
WebUI.maximizeWindow()

// click a link to download & save a PDF into a custom location
TestObject anchor = makeTestObject('guidlines', '//section[@id="content"]//a[contains(., "guidelines")]')
WebUI.verifyElementPresent(anchor, 10) 
WebUI.click(anchor)
WebUI.delay(10)

WebUI.closeBrowser()

// make sure if the pdf file has been successfully downloaded
assert Files.exists(downloadedFile)

[kazurayam]

By the way, Katalon Studio v10.3.2 often hangs-up when I double-click the Value field in the “Dictionary Property Builder” of “Chrome”<Web UI<Desired Capabilities<Project Settings. I had to terminate Katalon Studio entirely at the OS level, and restart it.

I am not surprised with this issue. I have seen this buggy behaviour since v5 years ago. I am bored with this sort of UI fragility of Katalon Studio.

See

Katalon Studio hangs when double-clicked on the Dictionary Property Builder for Desired Capabilities

I made a GitHub repository of the project that you can reproduce the issue: I used Katalon Studio v１０.３.2 free on macOS 15.2.6 I opend the dialog Project > Settings I navigated to Desired Capabilitites > Web UI > Chrome I chose the Value of prefs. Then a diaglog titled “Dictionary Property Builder” opend. I chose the 1st row of “download.default_directory”, then the row’s background color turned to be blue. I gave double click on the Value field of the row; I intended to edit the value…

[kazurayam]

I found an itchy problem concerning Project Settings of Katalon Studio.

See the following screenshot

In the value of download.default_directory of profs of Chrome’s Desired Capabilities, I wrote a constant string

• /Users/kazurayam/tmp

Here is a constant string kazurayam is hard coded. I don’t like this value hard coded.

Is it possible to write an expression ${GlobalVariable.username} and interpolate it with my os-username at runtime?

I once tried, but Katalon Studio hanged up! So I gave up.

Due to these mess, I would conclude that the GUI for setting the Browser Options (formally know as Desired Capabitilies) in the Project Settings of Katalon Studio is not really useful for me. The GUI is poorly implemented; it is troublesome.

I would prefer coding a custom keyword, as @gmarichal suggested

[gmarichal]

Wow! Nice catchs @kazurayam !

I agree with you, GUI options for setting Capabillities/Options should be updated to reflect the new browser changes.

Maybe it’s on the Katalon Roadmap @nghi.phan ?

[rudy.nutbeij]

try ~/tmp

[kazurayam]

@rudy.nutbeij

try ~/tmp

I don’t think it will work.

“Tilda ~ as the user’s home directory” is a Shell convention.

Java/Groovy language does not understand what ~ means.