Demonstrating how katalon.properties file enhances usability of Katalon Studio

What is this?

This is a simple Katalon Studio project for demonstration purpose. You can check this out onto your PC and execute with your Katalon Studio.

This will show you how I overwrite GlobalVariables in my Katalon project with parameters loaded from katalon.properties files. katalon.properties file can be located in multiple locations and I can choose where to locate them. I can exclude katalon.properties files from Git repository. Hence I can hide my sensitive information (hostname, credentials etc) even if I put the project publicly shared at GitHub.

Target version

This demo was originally tested against the Katalon Studio version 5.3.1.

Problems to solve

Let me assume, I have a single Web Application in multiple environments: the development, the staging, the production-blue, the production-green and more. These environments have 99% same contents and features except the following differences:

Hostname --- e.g. demoaut-mimic.kazurayam.com for development, demoaut.katalon.com for production
Username/Password --- e.g. kazurayam/foobar for development, John Doe/ThisIsNotAPassword for production.

Now I want to:

I want to use Katalon Studio to test Web UI of all these environments using a single set of Test Suites/Test Cases.
I want to store the Katalon project into the GitHub and to expose it public (just as I did here).
Still I want to hide my sensitive information: hostname, username and password. I do not like making them visible anywhere in the repository.
I want to run the test against multiple targets (hostnames) in Continuous Integration process on Jenkins. In order to do this, I need to be able to switch the test target by command line argument without modifying the source code of the test at all.

How to run the demo

git clone this demo project to your PC.
Start Katalon Studio and open the downloaded project.
This demo project depends on an external jar MultiSourcedProperties-1.0.jar which you can download from here or MultiSourcedProperties/releases page. You need to download it and configure the Katalon Studio project to refer to the external lib. Do Project > Settings > External Libraries > Add operation.
You want to create a file %USERPROFILE%\katalon.properties for Windows, $HOME/katalon.properties for Mac. The file should contain following line:

GlobalVariable.hostname=demoaut.katalon.com

Select the Test Suite TS_Run and run it with Firefox.
In the Log Viewer you will find INFO lines like this:

Starting invoke 'com.kms.katalon.core.annotation.BeforeTestSuite' method: 'TL_Run.sampleBeforeTestSuite(...)'
>>> GlobalVariable.hostname default value: ''
>>> GlobalVariable.hostname new value: 'demoaut.katalon.com'

These lines indicates that the GlobalVariable.hostname initially had empty value, and was changed by the Test Listener with new value loaded from katalon.properties file you created.

How I solved it

Here I propose to introduce katalon.properties file as a method to configure a Katalon Studio project runtime. Please check the codes of this demo project as you read through the following descriptions.

In the demo project, I made a set of GlobalVariables for hostname, username and password. I gave value of empty strings("") as default. This will be exposed public via Git.
On my PC, I can create katalon.properties files in java.util.Properties format in various locations as the following list shows. If a single Property is declared in multiple locations, the last wins:
1. <current directory>/katalon.properties is loaded if exists
2. $HOME/katalon.properties on Mac/Linux, %USERPROFILE%\katalon.properties on Windows is loaded if exists
3. If environment variable KATALON_USER_HOME is given, then a katalon.properties file under the directory new File(System.getenv('KATALON_USER_HOME')) is searched and loaded.
4. If JVM System Property katalon.user.home is given, then a katalon.properties file under the directory new File(System.getProperty("katalon.user.home")) is searched and loaded.
I have developed a Groovy class com.kazurayam.KatalonProperties. The code is avaiable in another GitHub repository kazurayam/MultiSourcedProperties. This class is capable of loading properties from multiple locations as described above. This class is contained in the MultiSourcedProperties-1.0.jar.
I made a Test Listener in the demo project. In the method annotated with @BeforeTestSuite, it instanciates a KatalonProperties object which loads ./katalon.profiles and $HOME/katalon.properties on startup. The Test Listener overwrites the GlobalVariable.hostname with the value picked up from external file.
Once overridden, the new value of GlobalVariable.hostname is refered to throughout the Test Suite run.

Here I confess that the design of runtime-configuration using properties file comes from gradle.properties.

Proposal to Katalon Studio

I hope I can specify JVM System Property katalon.user.home as command line arguments for the Katalon Studio in Console Mode. For example, I would type like this if I want to test the production Blue environement:

>cd %KatalonStudioInstalledDir%
>.\katalon.exe -Dkatalon.user.home=C:\Users\myname\tmp\blue -runMode=console -noExit -projectPath="C:\Users\myname\katalon-workspace\KatalonPropertiesDemo\KatalonPropertiesDemo.prj" -testSuitePath="Test Suites/TS_Run" -browserType="Firefox"

Here I typed an argument -Dkatalon.user.home=xxxxxx. I mean this argument adds a JVM System Property named katalon.user.home. This property will be available to any running Groovy code within the project. I learned the argument -Dnnnnn=xxxxx from the good-old java command.

Here I mean the katalon.user.home system property stands for the location of katalon.properties file to be loaded. In this case C:\Users\myname\tmp\blue\katalon.properties file should be loaded by the Test Listener.

Next I want to test the production Green environment by typing like this:

>.\katalon.exe -Dkatalon.user.home=C:\Users\myname\tmp\green -runMode=console -noExit ...

In this case C:\Users\myname\tmp\green\katalon.properties file should be loaded by the Test Listener.

Finally I want to test the staging environment by typing like this:

>.\katalon.exe -Dkatalon.user.home=C:\Users\myname\tmp\staging -runMode=console -noExit ...

In this case C:\Users\myname\tmp\staging\katalon.properties file should be loaded by the Test Listener.

I would like to emphasize that -Dkatalon.user.home=XXXXXXXXX argument would enhance the usability of Katalon Studio significantly. Provided with this feature I can switch the AUT just by typing different location of katalon.properties file as a command line argument, while no modification in the project's code set required at all. This feature will make it easy to run Katalon Studio in Continuous Integration processes in Jenkins targeting multiple hosts. This will make Katalon Studio a good tool applicable to Blue-Green deployment.

I am aware that Katalon Studio v5.3.1 Console Mode Execution does NOT accept the -Dnnnn=xxxx arguments. I home Katalon Team to consider adding this feature.

Related discussions

In the Katalon Discussion Forum I found quite a few discussions on test reuse, passing parameters to automated tests, and hiding credentials.

I hope my study suggests something useful to those who may concern.

kazurayam/KatalonPropertiesDemo