Skip to main content

Create a local test environment with an Agent

A Katalon Agent manages a local server for executing the scheduled test runs in a local test environment.

Katalon TestOps supports compatible Agents for different executing environments.

When you install the Agent in your local test machine, you have created a local test environment where you can run or execute your tests.

Set up an Agent

Requirements

Important:
  • In the latest release of Katalon TestOps (December 20th 2023), it is necessary to reconfigure your existing Agents once promptly. This ensures your Agents are properly linked to the relevant projects, establishing a clear connection between Agents and their respective Projects and preventing any unexpected errors. To learn how, see: Manage the Agent status.

  • You have a verified Katalon account.

  • You have installed Git SCM.

Download an Agent from Katalon TestOps

To download and install an Agent, follow these steps:

  1. Sign in to Katalon TestOps.
  2. Go to TestOps Settings > Organization Setup.
    Organization setup within the TestOps settings menu.
    This shows the Test Environments page. It also lists the agents you have.
  3. Click on Create Local Test Environment.
    • Alternatively you can click on Agent Setup to go to the same page.
    This shows the Agent Setup page. The Agent setup page in Katalon TestOps.
  4. In Select OS, choose your operating system (Windows, macOS, etc.), then click Download Agent.
    You have downloaded the Agent file (.zip file) to your computer. Unzip it and keep it open for now.
  5. In the Agent Name section, create a name for the Agent (e.g., My Agent).
  6. In the Katalon API Key section, select default or create your own.
  7. Open any command line interface and navigate to the directory containing the Agent executable file.
  8. Go back to the Agent Setup page and copy and paste the command labeled Bash to your command line interface. Hit Enter or Return.
  9. Use the next command labeled Bash to start the agent. Hit Enter or Return.
  10. After the agent successfully starts, assign your agent to a project. To learn how, see: Manage the Agent status.

Set up an Agent in a Windows local machine

To set up an Agent in a Windows local machine, do as follows:
  1. Unzip the Agent file you have downloaded.
  2. Open your command line interface and navigate to the directory containing the Agent executable file.
  3. Copy the command in the Generate configuration section on the Agent Setup page, and then paste it into the command window. Hit Enter to run the command.
  4. Copy the command in the Start an agent section, and paste it into the command window. Hit Enter to run the command.
You have successfully set up your Agent on Windows. The next step is to view or manage your Agent's linked Projects. See: Manage the Agent status.

Set up an Agent in a macOS local machine

To set up an Agent in a macOS local machine, do as follows:
  1. Unzip the Agent file you have downloaded.
  2. Right-click on the Agent file and select New Terminal at Folder.
  3. Copy the command in the Generate configuration section on the Agent Setup page, and paste it into the Terminal. Hit Return on the keyboard to run the command.
    Note:
    • Make sure you have enabled Terminal for Developer Tools in the Security & Privacy settings of your macOS.

  4. Copy the command in the Start an agent section, and paste it into the Terminal. Hit Return to run the command.
You have successfully set up your Agent on Mac. The next step is to view or manage your Agent's linked Projects. See: Manage the Agent status.

Manage the Agent status

Learn how to view or manage your Agents to ensure they are linked to the correct projects.

In the latest release of Katalon TestOps (December 20th 2023), it is necessary to reconfigure your existing Agents once promptly. This ensures your Agents are properly linked to the relevant projects, establishing a clear connection between Agents and their respective Projects and preventing any unexpected errors.
To view your Agents, do so as follows:
  1. Log in to TestOps and go to Settings > Organization Setup > Test Environments.
  2. Click on the Name of your Agent to navigate to its Agent Details page. In the example below, "My Agent" is the name of the Agent.
    Click on the name of the agent to go to its Agent Details page.
    The Agent Details page shows.The Agent Details page in Katalon TestOps.
Link or un-link a Project to an Agent
  1. Navigate down to the Linked Projects section and click on the dropdown menu to assign projects you would like to link this agent to. Once they are linked, you will see them as tags. In the example below, the projects "First Project" and "Second Project" are shown as tags below the dropdown menu.
  2. To remove a linked project, click on the x next to the project name. This action deletes the project tag,which means that the project is now un-linked.
    Note:
    • You can link your projects back any time.

You have linked your agent to a project. Now you can Schedule test runs.

Agent Authentication

Agents use serverurl and apikey in agentconfig to:
  • Activate Katalon Runtime Engine.
  • Send test results to Katalon TestOps.

To locate the serverurl and apikey of your agent, navigate to the Generate configuration section on the Agent Setup page, as shown in the example below.

Configure proxy for Agents

You can set up proxy for the Agent in the agentconfig file, using the proxy option. For example, proxy=http://localhost:8080.

Next steps