Katalon Docker Image (KDI)

Important:

• Docker installed. You can refer to the instructions in the Docker document here: Get Docker.
• An active Katalon Runtime Engine floating license. See: Types of licenses.

This tutorial shows you how to run tests with Katalon Docker Image (KDI).

KDI contains up-to-date browsers, including Google Chrome, Mozilla Firefox, Microsoft Edge, and Katalon Studio. With KDI, you do not need to use the Katalon Studio and Runtime Engine apps installed on your local machine.

KDI for Katalon Studio is available at Docker Hub: katalonstudio/katalon.

Note:

• You can find the source code of the Docker image in our GitHub repository: KDI.
• You can download our GitHub sample project for CI configurations using Docker image: CI samples.

Pull Katalon Docker Image (KDI)

Follow these steps to pull the Katalon Docker Image (KDI).

1. Open a Terminal from your local machine.
2. Copy and paste the following command:

   docker pull katalonstudio/katalon:9-latest-slim

   This opens Docker and pulls the latest Katalon Runtime Engine 9.x version.

   Tip:

   • The 9-latest-slim tag applies to the latest Katalon Runtime Engine, which we recommend for production use.
   • You may also use the 9-latest tag to pull in WebDriverManager and Gradle.
   • The major version number in the tag (9-latest-slim, 9-latest, 8-latest) should match your major version of Katalon Studio (9.7, 8.6).

You should see the katalonstudio/katalon image in your Docker application.

To check which Chrome and Firefox versions are supported by the Katalon Docker Image, run the following command:

docker run -t --rm katalonstudio/katalon cat /katalon/version

Execute Katalon Studio tests with Katalon Docker Image

Important:

• Katalon Docker Image version 7.2.1 onwards.

• Make sure you have Docker open while running the test.

1. Open Terminal, then go to the test project directory you wish to run. For example, we want to run the CI sample test project, we will direct to our CI sample project folder in our local machine.

2. Inside your test project folder, input the following command:

   For macOS:

   docker run -t --rm -v "$(pwd)":/tmp/project katalonstudio/katalon katalonc.sh -projectPath=/tmp/project [Option1] [Option2] ... [OptionN]

   For Window PowerShell:

   docker run -t --rm -v ${pwd}:/tmp/project katalonstudio/katalon katalonc.sh -projectPath=/tmp/project [Option1] [Option2] ... [OptionN]

   For Window CMD:

   docker run -t --rm -v "%cd%":/tmp/project katalonstudio/katalon katalonc.sh -projectPath=/tmp/project [Option1] [Option2] ... [OptionN]

Note:

• The katalonc.sh command starts Katalon Studio and other necessary components.
• All Katalon Studio console mode arguments are accepted except -runMode. You can find more command-line options at Command Syntax.

For example, we want to run the TS_RegressionTest test suite from the CI sample project with the Chrome browser in Katalon Docker Image. We enter the command as follows:

docker run -t --rm -v "$(pwd)":/tmp/project katalonstudio/katalon katalonc.sh -projectPath=/tmp/project -browserType="Chrome" -testSuiteCollectionPath="Test Suites/TS_RegressionTestCollection" -apiKey="<your_API_key>"

Note:

• To avoid syntax errors, you can use the Command Builder to generate commands. To learn more about the command builder, you can refer to this document: Command Builder.

• <your_API_Key>: the API key verifies your credentials. The command-line options of API Key, including -apiKey= and -apikey= are both accepted. To learn more about API keys, you can refer to this document: API key.

1. You can view the console log in Docker during the test.

   
   
   

2. To view your report files, you can go to this directory: <your-project-folder>/Reports or your third-party integration like Katalon TestOps, Azure DevOps, or qTest. Katalon Studio supports exporting test reports in HTML, CSV, PDF, and JUnit.

Proxy Configuration

If you need to configure proxies for Katalon Studio, you can refer to this document: Proxy Options.

These proxy options must be used with the --config parameter, for example:

docker run -t --rm -v "$(pwd)":/tmp/project katalonstudio/katalon katalonc.sh -projectPath=/tmp/project -browserType="Chrome" -retry=0 -statusDelay=15 -testSuitePath="Test Suites/TS_RegressionTest" -apikey="<your_API_key>" --config -proxy.option=MANUAL_CONFIG -proxy.server.type=HTTP -proxy.server.address=192.168.1.221 -proxy.server.port=8888

Prevent user permissions issue on your machine

You can run the test under the current user ID using the KATALON_USER_ID environment variable. This helps avoid permission issues when accessing artifacts generated after the test execution. Follow these steps:

1. Open Terminal, then run

   id -u $USER

   The result will tell you the current user ID. Here, the user ID is: 502

   
   
   

2. To execute the test with the current user ID, enter the following command line:

   docker run -t --rm -e KATALON_USER_ID=<the-current-userID> -v "$(pwd)":/tmp/project katalonstudio/katalon katalonc.sh -projectPath=/tmp/project [Option1] [Option2] ... [OptionN]

   For example, we want to run the test with the userID from step 1, we enter the command as follows:

   docker run -t --rm -e KATALON_USER_ID=502 -v "$(pwd)":/tmp/project katalonstudio/katalon katalonc.sh -projectPath=/tmp/project [Option1] [Option2] ... [OptionN]

Execute Katalon Studio tests with Katalon Docker Image version below 7.2.1

Important:

• Make sure you have Docker open while running the test.

Inside your test project directory, input the following command:

docker run -t --rm -v "$(pwd)":/katalon/katalon/source katalonstudio/katalon katalon-execute.sh [Option1] [Option2] ... [OptionN]

Note:

• All Katalon Studio console mode arguments are accepted except -runMode, -reportFolder, and -projectPath. You can find more command line options at Command Syntax

Command-line Option	Description
katalon-execute.sh	This command starts Katalon Studio and other necessary components.
/katalon/katalon/source	The katalon-execute.sh command looks for the test project inside this directory. If you don't want to use this command line, define the test project directory with the docker run -w argument as follows: docker run -t --rm -v "$(pwd)":/tmp/source -w /tmp/source katalonstudio/katalon katalon-execute.sh [Option1] [Option2] ... [OptionN]

See also

• Integrate Jenkins on Docker hosted in Ubuntu
• Integrate Jenkins Pipeline (Jenkinsfile) with Katalon Studio Docker Image