Skip to main content

Integrate Jenkins Pipeline (Jenkinsfile) with Katalon Studio Docker Image

This tutorial shows you how to integrate Jenkins Pipeline (Jenkinsfile) with Katalon Studio Docker Image. This image contains up-to-date browsers, including Google Chrome, Mozilla Firefox, and Katalon Studio. Hence when running your Katalon Project with Katalon Studio Docker Image, the pre-installed Katalon Studio and Katalon Runtime Engine in your local machine are not required. Docker Image for Katalon Studio is available here at Docker Hub: katalonstudio/katalon.

  • Jenkins installed. Follow the instructions in this Jenkins document for installation: Getting started.

  • Docker installed. You can refer to the instructions in the Docker document here: Get Docker.

  • An active Katalon Runtime Engine floating license. To learn more about types of licenses, you can refer to this document: Types of license.

Integrate Jenkins with Docker

Install plugins

  1. Install the Docker plugin and Docker Pipeline plugin. Go to Manage Jenkins > Manage Plugins > Available tab and search for the Docker plugin and Docker Pipeline plugin.
  2. Select the plugin and click Install without restart.


Add an environment path


For macOS/Linux, when running builds with Docker from a Jenkinsfile with Pipeline syntax, you need to add an environment path to Jenkins. This PATH helps Jenkins point to the correct Docker installation path. Do as follows:

  1. To find the correct Docker installation path, open Terminal, copy and paste the following command line: which docker. The result will tell you where the Docker is. Here, our Docker installation path is: /usr/local/bin/docker.

    Docker installation path

  2. Go to Dashboard > Manage Jenkins > Configure System > Global properties. Select the Environment variables to add a global variable named PathExtra with this value:
    $PATH:<the correct Docker installation path>
    . For our example, the PathExtra value is: $PATH:</usr/local/bin/docker>.

    Add environment path to Jenkins pipline

Upload your Pipeline script


Make sure you have Docker open, with Docker Plugin and Docker Pipeline activated on Jenkins.

  1. In the Jenkins Dashboard, go to New Item and create a Jenkins Pipeline project.

  2. In the Definition dropdown list, you can choose Pipeline Script or Pipeline Script from SCM, depending on where you store your Jenkinsfile. The Pipeline Script from SCM instructs Jenkins to obtain your Pipeline from Source Control Management (SCM), which will be your locally cloned Git repository. To learn more about defining a Pipeline, you can refer to this Jenkins document: Getting started with Pipeline.

    Here, since we have our Pipeline project stored in Git, we select Pipeline Script from SCM.

    Choose Pipeline Script from SCM

  3. In the SCM field, select Git. Enter your repository URL, select branches to build, repository browser, and additional behaviors, if any. You can clone and download the following sample project here: CI samples.

    Enter Git repository url

  4. Specify the Jenkinsfile path from your Git project in the Script Path box.

    Jenkinsfile path


    To quickly copy the Jenkinsfile path, go to your Jenkinsfile in your Github repository, click More (...), then click Copy Path.

    Quickly Jenkinsfile path in Git project

    You can see our sample Jenkinsfile for MacOS/Linux here: Jenkinsfile. In case you are using Windows, replace the sh command in this sample Jenkinsfile with the bat command:

    steps {
    bat ''

    For example, we want to run the TS_RegressionTest test suite from the CI samples project with the Chrome browser in Windows. We adjust the sample Jenkinsfile as follows:

    pipeline {
    agent any
    stages {
    stage('Test') {
    steps {
    bat 'docker run -t --rm -v "$(pwd)":/tmp/project katalonstudio/katalon -projectPath=/tmp/project -browserType="Chrome" -retry=0 -statusDelay=15 -testSuitePath="Test Suites/TS_RegressionTest" -apiKey=<your-api-key>'

    After cloning our sample Jenkinsfile to your repository, customize the below command lines for your purposes:

    • <your-project-folder>: the direct path to your project folder in the local machine.
    • <your_API_Key>: the API key verifies your credentials. The command-line options of API Key, including -apiKey=<Your_API_Key> and -apikey=<Your_API_Key> are both accepted. To learn more about API keys, you can refer to this document: API key.
    • From version 7.7.0 onwards, if you belong to more than one Organization subscribing to Runtime Engine licenses, you can choose which Organization validates your license usage with the following command line: -orgID=<Katalon_OrgID>.

Build your project

  1. Click Save, then click Build Now to run the Jenkinsfile. While the test is being run, if Docker cannot find the katalonstudio/katalon image locally, it will automatically pull this image.

    Build your Jenkins project

  2. To view the console log, click on your current build on Jenkins and select Console Output.

    View console output

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

    docker log

  3. 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.

    • To display characters with UTF-8 encoding in test reports, you can specify the -Dfile.encoding=UTF8 argument in the jenkins.xml file.

See also