Skip to main content

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.

  • Docker latest and latest-slim tags now point to the latest version 10.x.

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.

KDI in the Docker app

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>"
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]

Known limitations for ARM64-based platforms​

Starting from Katalon Studio version 10.0.0, Katalon Docker Image supports ARM64 platforms, including macOS (M1, M2) and Linux (Ubuntu ARM64). However, a few limitations exist when working with these platforms:

  • Docker slim tags (for example, 9.6.0-slim and 9-latest-slim) aren't supported yet for ARM64.

  • Chrome and Edge Chromium browsers aren't supported on ARM64 platforms. Executing tests with Chrome and Edge Chromium on these Docker images isn't supported yet.

See also​

Was this page helpful?