Automation Agent

Important

Automation-related rights are assigned from Customization > Roles. The logged-in user will have access rights over the Agent feature accordingly.

Understanding Agent Concept

Users can define Agent Alias and add tasks for Agent. On activation, the Agent requests tasks through . Automation Agent checks the schedule(s) set in and executes the automation tests. Users can run Custom Command regardless of the Automation Framework or the Build Framework. The automation agent can be run immediately or can be scheduled on future dates and times. Users can schedule the recurring execution of commands. The execution will be scheduled automatically as per the set occurrences. Agent keeps running the jobs accordingly.

The flow works like this:

  1. Configure Agent in Integration > Automation Agent. Download the Agent. Run a custom command through Automation Agent wizard.

  2. Automation Agent will trigger the execution through a custom command, and the test result file will be generated accordingly.

  3. Import the above result file in using the REST API.

QMetry Agent Configuration

Compatibility: Agent is a Java executable file that needs Open JDK 17.

Automation Agent Key

Use this key to configure the Automation Agent.

To generate an Automation Key, go to Integration, select Automation Agent, and then click Generate new Key.

Screenshot showing the Automation Agent API Key field in QMetry with options to regenerate or copy the key.

Steps to Configure Automation Agent

Configure Automation Agent using UI

  1. Go to Integration, and then select Automation Agent.

  2. Expand the Download & Run Agent section, if not expanded already.

    Screenshot of the “Download & Run Agent” section in QMetry, showing expandable instructions for launching the Automation Agent tool and command line.

  3. Download QMetryAgent.zip by clicking the Automation Agent.

    QTM_Screenshot_Download_QMetry_Agent.png

  4. Extract QMetryAgent.zip to your computer drive.

  5. Open the QMetryAgent folder.

  6. Run <Qmetry Agent Directory>/QmetryAutomationAgent.jar by clicking on it.

    The Automation Agent wizard opens.

    Screenshot of the QMetry Automation Agent configuration window with fields for URL, API Key, Agent Name, Proxy option, and Running on VM checkbox, along with Clear and Start Agent buttons.

The Automation Agent has the following fields:

Table 27. Field Description

Field

Description

URL

The URL of your Test Management application instance.

API Key

Enter Automation Agent Key. To generate the Automation Key, go to Integration > Automation Agent and click the Generate Key as described under Automation Agent Key above.

Agent Name

Enter the name of your preference as Agent Alias to identify the specific agent.

Running on VM

Users who want to run the agent on a virtual machine can do so by setting this configuration. The manual settings are not required.



Interval Time: By default, the interval time between two scheduled jobs will be 180 seconds. You can change the time by modifying the Interval parameter in the QMetryAgent.properties. The minimum value should be 60 seconds.

Click the Start Agent button.

Users can also view logs by clicking on the View Logs button.

QTM_Screenshot_Qmetry_Automation_Agent_View_Logs.png

Once the Agent is configured, it will be added to the list of Registered Agents with the Status Active.

Screenshot of the Registered Agents table in QMetry showing agent alias, operating system, MAC address, status, schedules, and available actions.

Configure Automation Agent using Command Line

Follow the steps mentioned below to configure Automation Agent for Windows and Linux/MacOS.

Configure Automation Agent using Command Line on Windows

  1. Go to Integration > Automation Agent.

  2. Expand the Download & Run Agent section, if not expanded already.

    Screenshot of the “Download & Run Agent” section in QMetry showing expandable instructions to launch the Automation Agent via the Windows command line.

  3. You will find Agent download and installation instructions on the screen. Download QMetryAgent.zip by clicking on the Automation Agent download link.

    Screenshot of the “Download & Run Agent” section in QMetry showing detailed steps to download, extract, and run the Automation Agent via the Windows command line, including start and stop commands for both Windows and Linux/Mac.

    Note

    The downloaded zip file will be in the format QMetryAgent_A.B.C.zip, where A.B.C will be the version of Agent.

  4. Copy the QMetryAgent_A.B.C.zip file to your server. Then, navigate to the directory where this file is kept and extract the zip file to the computer drive.

    Screenshot of the extracted QMetry Automation Agent folder (QMetryAgent_8.15.0) in Windows File Explorer showing configuration files, JAR files, batch files, shell scripts, and VBScript launcher.

  5. Execute the following command to run the agent.

    startAgent.bat

The Automation Agent command line wizard will open. Users need to fill required information.

Fields

Description

URL

The URL of your Test Management application instance.

Key

Enter Automation Agent Key. To generate an Automation Key, go to Integration > Automation Agent and click Generate Key as described under Automation Agent Key above.

Alias

Enter the name of your preference as Agent Alias to identify the specific agent.

Enable Proxy

Users who want to run the agent on a proxy can do so by setting this configuration.

Enable VM

Users who want to run agent on virtual machine, can do so by setting this configuration. The manual settings are not required.

Screenshot of Windows Command Prompt showing QMetry Automation Agent setup steps, including prompts for URL, API Key, Agent Name, Proxy Server, and VM option.

This will enable the agent to start automatically when the system reboots.

To stop the running agent: Run stopAgent.bat by clicking on it.

→ Interval Time: By default, the interval time between two scheduled jobs will be 180 seconds. You can change the time by modifying the "Interval" parameter in the QMetryAgent.properties. The minimum value should be 60 seconds.

Configure Automation Agent using Command Line on Linux / MacOS

  1. Go to Integration > Automation Agent.

  2. Expand the Download & Run Agent section, if not expanded already.

    Screenshot of the “Download & Run Agent” section in QMetry showing expandable instructions to launch the Automation Agent via the Linux or MacOS command line.

  3. You will find Agent download and installation instructions on the screen. Download QMetryAgent.zip by clicking on the Automation Agent download link.

    Screenshot of the “Download & Run Agent” section in QMetry showing detailed steps to download, extract, and run the Automation Agent via Linux or MacOS command line, including start and stop commands with prerequisite shell permission settings.

    Note

    The downloaded zip file will be in the format QMetryAgent_A.B.C.zip where A.B.C will be the version of Agent.

  4. QMetryAgent_A.B.C.zip

    unzip QMetryAgent_A.B.C.zip

    Note

    Replace A.B.C with the actual version of Agent.

    Screenshot of a MacOS terminal showing the user inside the extracted QMetryAgent_8.15.0 directory after running the unzip command.

  5. Execute the following commands.

    chmod +x startAgent.sh
chmod +x stopAgent.sh

    Note

    Replace A.B.C with the actual version of Agent.

    QTM_Screenshot_Agent_Directory_Execute_Commands_Linux_MacOS.png

  6. Run the agent by executing the following command.

    sh startAgent.sh

The Automation Agent command line wizard will open. Users need to fill required information.

Field

Description

URL

The URL of your Test Management application instance.

Key

Enter Automation Agent Key. To generate Automation Key, go to Integration > Automation Agent and click on the Generate Key as described under Automation Agent Key above.

Alias

Enter the name of your preference as Agent Alias to identify the specific agent.

Enable Proxy

Users who want to run the agent on a proxy can do so by setting this configuration.

Enable VM

Users, who want to run the agent on the virtual machine, can do so by setting this configuration. The manual settings are not required.

Screenshot of a MacOS terminal inside the QMetryAgent_8.15.0 directory showing the commands chmod +x startAgent.sh and chmod +x stopAgent.sh being executed to grant script permissions.

Note

This will enable the agent to start automatically when the system reboots.

To stop the running agent:

sh stopAgent.sh

→ Interval Time: By default, the interval time between two scheduled jobs will be 180 seconds. You can change the time by modifying the Interval parameter in the QMetryAgent.properties. The minimum value should be 60 seconds.

Once the Agent is configured, it will be added to the list of Registered Agents with the Status Active.

Screenshot of the Registered Agents list in QMetry showing multiple agents with details such as alias, operating system (Windows, Mac OS X), MAC address, status (Active, Not Registered, Inactive), schedules, and actions.

The screen lists all agents added in with the details of OS, Machine Address, Status (Not Registered, Active, Inactive, Not Applicable), ScheduledIn Progress

Filter Options

You can filter the Registered Agents on the following criteria:

  • Alias

  • OS

  • Status

After configuring the Agent in Integration > Automation Agent, download and run the Agent. Schedule tasks for the Agent to perform automation testing.

The columns on the screen are described below:

  • Alias: This is Agent Alias mentioned by the user while adding Agent.

  • OS: Operating System on the hosting machine on which the command will be executed.

  • MAC Address: The machine address of the hosting machine on which the command will be executed.

  • Status: The Agent status could be Active, Inactive.

    • Active: Agent is executed to request a schedule from the application. When you start the agent, it attains Active status and remains Active till it keeps requesting for schedule from application at the frequency defined.

    • Inactive: As stated above, Agent and its connection with application are checked at a defined interval. If Agent is not communicating with application for more than the defined time and it stops requesting for schedule, then the Agent status is updated as Inactive.

  • Schedules: The column shows the number of pending schedules and in-progress schedules. For example, 4 Scheduled / 2 In-progress.

  • In Progress: This column shows when a scheduled run is currently in execution.

  • Updated At: This is the system date and time when the Agent is added to .

The Actions column includes the Schedule, History, Manage Schedule, and Delete buttons.

  • Schedule Agent: Click on the Schedule button to schedule Agent run.

Automation Testing

Users can run the schedule on the spot or at a specific scheduled date and time.

Note

Agents can be scheduled irrespective of the Approval workflow if the e-Signature feature is enabled.

Execution Command

Users can run Custom Command regardless of the Test Framework or the Build Framework. This is a command-line input, which you provide on the command line interface. Users can trigger and execute more than 255 characters (up to 5000) command through the Automation Agent.

For example,

The following command includes the Project path on your local drive and the test command to trigger the execution in accordance with the language and Framework you use. The result file will be generated in the Project directory accordingly.

cd D:\QMetry\cucumber-maven-example-master && D: && mvn test

Schedule Automation Agent Run

You can schedule Agent to run at your preference.

(A) Run Now

(B) Run Later

  • One Time

  • Recurring

The agent list screen now displays the total count of Scheduled and In Progress tasks for each agent.

Screenshot of the Registered Agents table in QMetry highlighting the Scheduled and In Progress columns, showing the number of scheduled and running executions for each agent.

Scheduling Recurring Test Execution Commands for Multiple Test Suites

You can schedule automation tasks (execution commands) for multiple test suites to recur, run immediately, or execute as a one-time run, all through a single Automation Agent.

(A) Run Now

If you want to execute the Agent job immediately, then select the Run Now option and click Submit.

Screenshot of the Schedule Agent window in QMetry showing the option to enter an execution command, select “Run Now” or “Run Later,” and a list of existing schedules with their status, schedule type, and start date.

(B) Run Later

You can schedule the agent to run on a future date and time. Scheduling executions helps testers set execution schedules to be run one after the other.

  • One Time Occurrence

    To schedule the run only once on a particular day and time, select the Run Later option for Schedule and the One Time option for Occurrences.

    • Schedule: Run Later

    • Occurrences: One Time

    • Schedule date and time: Open the calendar and select the date and time to initiate the Agent job, and click Submit.

    Screenshot of the Schedule Agent window in QMetry showing the “Run Later” option with occurrence set to “One Time” and a date-time picker for scheduling execution. The schedules list below shows recurring and one-time tasks.

    • Schedule Date: This is the scheduled date to execute the command. By default, the field shows current system date in MM-DD-YYYY format. User can modify the date as per requirement. To pick date from calendar, click the calendar icon adjacent to the field.

    • Schedule Time: This is the scheduled time to execute the command. Three separate number fields are provided for Hours, Minutes and Seconds. By default, the drop-down list shows the current system time in HH:MM:SS format. User can modify the time as per requirement by selecting the suitable time to execute the command. Schedules will be sent to the agent at the defined time.

  • Recurring Occurrence

    The Automation Agent supports setting up recurring schedules for multiple test suite executions on the same agent, whether for the same test suite or different. When scheduling an execution command for an agent, all upcoming schedules for the agent are displayed, making it easier for testers to identify overlapping tasks. For multiple execution schedules set for the same time on the same agent, the agent will execute them sequentially on a first-come, first-served basis.

    • Schedule: Run Later

    • Occurrences: Recurring

    • Starting On and Ending On: Select dates using the calendar

    • Schedule time: Enter time in HH: MM format

    • Recur: Select one frequency from the following and its corresponding option to schedule the Agent run recurrently.

      • Daily

      • Weekly

      • Monthly

    Then click Submit.

    Screenshot of the Schedule Agent window in QMetry showing the “Run Later” option with “Recurring” selected. The interface includes options to configure recurrence as Daily, Weekly, or Monthly, along with start and end dates, schedule time, and recurrence frequency.

    Once the Agent is scheduled, the Total Schedules count increases on the Schedule screen.

    The task that is immediate on the schedule gets executed. Other scheduled tasks get executed in sequence in accordance with their scheduled date and time.

Manage Schedule

The Manage Schedule option for the agent allows users to alter the scheduled time and execution commands for the run later or recurring triggers.

Steps

  1. Go to Integration, and then select Automation Agent.

  2. In the Registered Agents section, click the Manage Schedule button to manage the schedule details of that particular Agent.

    Screenshot of the Registered Agents table in QMetry highlighting the gear (settings) icon under the Actions column, used to manage an agent’s schedules.

  3. On the Manage Schedule screen, you can edit or delete an existing Schedule.

    • Edit Schedule: Click the Edit Schedule button to edit the schedule.

    • Delete Schedule: Click the Delete Schedule button to delete the schedule.

    Screenshot of the Manage Schedule page in QMetry showing a list of scheduled tasks with details such as execution command, schedule type, start and end dates, status, and options to edit or delete schedules under the Action column.

Edit Schedule

  1. Click the Edit icon for the scheduled agent that you want to update.

    Screenshot of the Manage Schedule page in QMetry showing a one-time scheduled task with details including schedule type, status, test suite key, release, cycle, platform, and an option to edit the schedule under the Action column.

    The Edit Schedule Agent screen opens.

  2. Make the required changes in the schedule of the agent.

  3. Click Update.

    Screenshot of the Edit Schedule Agent window in QMetry showing execution command, Run Later with Recurring occurrence, start and end dates, schedule time, recurrence frequency, and the Update button highlighted.

Delete Schedule

QTM_Screenshot_Delete_Schedule.png

  1. Go to Integration, and then select Automation Agent.

  2. In the Registered Agents section, click the Manage Schedule icon.

  3. Click the Delete icon to delete the schedule.

View Automation Agent History

  1. Go to Integration, and then select Automation Agent.

  2. In the Registered Agents section, click the History button to view the schedule details of that particular Agent.

    A pop-up screen opens that displays the schedule details of the Agent.

    Screenshot of the Automation Agent page in QMetry showing the transition from Registered Agents to Automation History. The Automation History section lists executed commands with details such as scheduled by, executed on, schedule status (e.g., Completed, Agent Inactive), and an option to download logs.

On the Automation History page, you can perform the following actions:

  • Refresh the page by clicking the Refresh icon at the top right corner, to view the latest execution status of the job.

  • You can download logs by clicking on the Download icon under the Actions column.

The number of pages is displayed at the bottom of the screen. Navigation buttons are provided to allow users to navigate through the pages.

Delete Agent

  1. Go to Integration, and then select Automation Agent.

  2. In the Registered Agents section, click the Delete button for the Agent you want to delete.

    Screenshot of the Registered Agents table in QMetry showing the delete (trash bin) icon under the Actions column, used to remove an automation agent from the system.

Import Automation Test Result File

The Agent job is triggered to execute the command as per the set Schedule. The result file is generated in accordance with the command. Use this file to update the test assets and execution status in .

Note

Make sure you upload the result file in using Postman to update the test execution results in .

To learn more about importing automation test results into , refer to Import Automation Results through REST API.

Other ways to push automation results into :

View Test Assets and Test Results in added/updated in

After automation testing is successfully completed, test assets are added/updated to the Test Cases and Test Suites modules.

The test run results are uploaded to the Test Execution screen.

Test Cases

Open the Test Cases module. The test cases imported through automation testing are displayed with the Automated Testing Type.

Screenshot of the Test Cases page in QMetry showing a list of test cases with details such as entity key, summary, version, created date, created by, and testing type marked as Automated.

Test Suite

Go to the Test Suites module. You can see the Auto-Generated test suite added in as a result of automation testing.

Screenshot of the Test Suites page in QMetry showing a combined view of a suite named “Automation-CUCUMBER-04-10-2019” with tabs for Test Execution, Test Cases, Platforms, Details, Release & Cycles, Attachments, Comments, and Change Log.

Test Execution Screen

The test execution status of test cases and steps is updated on the Test Execution Screen.

  1. Go to the Test Suites module.

  2. Open the test suite imported in as a result of automation testing.

  3. On the Test Execution tab, click the execution icon.

    The Test Execution screen opens, displaying the test execution status of test cases with their test steps.

    Screenshot of the Test Run page in QMetry showing execution results for test cases within a suite. The table lists test case entity key, summary, and execution status with outcomes such as Passed, Failed, and Blocked.
In this section:
© 2025
Publication date: