Skip to main content

Katalon Docker Image

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​

To pull KDI, open Terminal in your local machine, copy and paste the following command line:

docker pull katalonstudio/katalon

The latest tag applies for the latest Katalon Runtime Engine 8.x version (8.6.9).

The 9-latest tag applies for the latest KRE 9.x version.

After successfully pulling KDI, you should see the katalonstudio/katalon image in your Docker application.

KDI in the Docker app

To check which Chrome and Firefox versions are supported by KDI, copy and paste the following command in the Terminal:
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>"
Run test with Docker

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.

    docker log

  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

    Current userID

  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 OptionDescription
katalon-execute.shThis 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​