Katalon TestOps Agent

Build Katalon Agent docker image

Run the following command with the version to build the image

./buid-image.sh 1.7.6

Start the Katalon Agent

Prerequisites

• Node.js >= 10.x
• Run the npm install command in the Katalon Agent's root directory to install the dependencies

Configuration

• Create the agentconfig file in the Katalon Agent's root directory and configure it:

agentName=My Agent
email=<email>
apikey=<api_key>
serverUrl=https://analytics.katalon.com/
organizationId=<organization_id>

• Supported options:

Mandatory Option	Description
agentName	The name of the Katalon Agent displayed on the Katalon TestOps CI page. It should be human-readable and distinguishable among multiple agents.
email	The email of the Katalon account used to log into the Katalon TestOps.
apikey	The API Key used to log into the Katalon TestOps. The API key can be generated and retrieved from here. For more info read the docs.
serverUrl	The Katalon TestOps' URL.
organizationId	The ID of the Katalon TestOps organization to integrate the Katalon Agent into. The agent is shared among members and projects within an organization that the agent linked to.
uuid	The ID used to identify the agent. It is generated by the Katalon Agent on the first run and should not be specified manually or modified for any reason.

Optional Option	Description
xvfbRun	Xvfb-run supported options. Linux only. E.g. xvfbRun=-a -n 0 -s "-screen 0 1024x768x24"
x11Display	x11 DISPLAY environment variable. Linux only. E.g. x11Display=:0.0
proxy	The proxy server. E.g. proxy=http://localhost:3000
proxyExcludedUrls	E.g. proxyExcludedUrls=testops.katalon.io
logLevel	The logging level (ALL < TRACE < DEBUG < INFO < WARN < ERROR < FATAL < MARK < OFF). Default: INFO.
keepFiles	Whether to keep the test project's temporary files. Default: false.

Start the Katalon Agent with Node from CLI

• Navigate to the Katalon Agent directory
• Run the npm start or node cli.js start-agent command to start the agent.

Start the Katalon Agent with the packaged executable from CLI

• Download the suitable package from the Katalon Agent Releases.
• Extract the downloaded package.
• Depending on the platform a start script can be found inside the extracted directory,
  • start.bat on Windows
  • start.sh on Linux and MacOS.
• Open your CLI and execute the start script.

Note: On Linux and MacOS, you might need to add execute permission (chmode u+x <file>) to the following files, if present:

• cli-linux-x64
• cli-macos-x64
• start.sh
• service.sh

Package the Katalon Agent

• Checkout the code
• Make sure the dependencies in the package.json is installed and up-to-date by running npm install command
• Run npm run build command
• The build artifacts are available inside the bin directory.

Generate the configuration file

• The agentconfig file can be generated or updated by running config command with additional arguments.
• E.g. node cli.js config --server-url https://analytics.katalon.com --username <email> --apikey <api_key> --organizationid <organization_id> --agent-name my-agent
• If an agentconfig has been created, the existing configuration will be overridden with the new value.
• Show the usage of the config command with -h option. E.g. node cli.js config -h.

Run the Katalon Agent as a service

• Download the suitable package from the Katalon Agent Releases.
• Extract the downloaded package.
• Depending on the platform a script can be found inside the extracted directory,
  • service.bat on Windows
  • service.sh on Linux and MacOS.
• Open your CLI and execute the script.

Develop the Katalon Agent

Debug with IntelliJ IDEA

• Checkout the code
• Open the Katalon Agent's directory with Intellij IDEA
• Run --> Edit Configurations... -> + (Add New Configuration) --> 'npm'
• Set the following values:
  • package.json: The location of the package.json in Katalon Agent's directory
  • Command: Select start
  • Node interpreter: Select your Node.js location
  • Package manager: Select your npm location
  • Environment: Input NODE_ENV=debug
• Click OK
• Choose the configuration and start debugging

Debug with Visual Studio Code

• Checkout the code
• Open the Katalon Agent's directory with Visual Studio Code
• Select the Run icon in the Activity Bar on the side of VS Code
• Configure the launch.json file following the guide
• Add the following configuration to the launch.json file:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Start Agent",
            "skipFiles": [
              "<node_internals>/**"
            ],
            "program": "${workspaceFolder}\\cli.js",
            "args": [
              "start-agent"
            ],
            "env": {
              "NODE_ENV": "debug"
            },
            "console": "integratedTerminal"
        }
    ]
}

• In Run view, select Start Agent launch configuration and start debugging