Integrate UFT with Universal Agent

In this article you will learn how to integrate UFT tests with the Universal Agent.


  1. UFT installed on the same machine with Automation Host. The UFT versions that we tested are between 14.03, 14.51 and 14.53
  2. Git installed in the same machine with Automation Host. Notes: Git is required for this EXAMPLE only. If your actual UFT project is not being hosted in Git, you do not need Git installed in the Automation Host machine.
  3. Activate Automation Integration
  4. Install and Register the Automation Host
  5. Download the script qtp.vbs that will be used to kick off UFT script at and put it into the automation host folder, e.g. C:\qtest\agentctl-2.2.1\build\qautomation\lib\qtp.vbs. Notes: we are using Automation Host 2.2.1 in this example via the folder naming agentctl-2.2.1. If your Automation Host version is newer, make sure you change the folder name agentctl-2.2.1 to the actual folder

Demo Video

Click HERE to watch demo video.

Create UFT Universal Agent

  1. From Launch, open the host machine where you want to create the new agent.
  2. Select the + New Agent button.
  3. The New Agent dialog will
  4. Enter the information below for the new agent.

General Agent Information


  • Agent Name: name of the agent, e.g. UFT Universal Agent
  • qTest Manager Project: select a qTest Manager project from which the agent is going to execute scheduled tests, e.g. qConnect Sample Project
  • Agent Type: select Universal Agent

Pre-Execute Script

We are going to configure a pre-execute script to either clone the sample uft-sample-14.03 from github to the host machine, or pull the latest updates of that project if the sample already exists to the host machine.


  • Pre-Execute Script field is not required. This example shows the ability to pull code from source control like github in Universal Agent via the use of this field. If you are not using git as a source control in your actual project, you can leave this field blank
  • If your machine has only C:\ drive, create a new folder to clone UFT project from GitHub e.g test-projects.
if not exist "C:\test-projects\uft-sample-14.03" (
cd /d "C:\test-projects"
git clone
) else (
cd /d "C:\test-projects\uft-sample-14.03"
git pull --all

Execute Command


  • Select node as the executor.

Working Directory

  • Enter the directory where UFT script(s) are located, e.g. C:\test-projects\uft-sample-14.03

Execute Command

We are going to create a script written in NodeJS to:

  1. scan all the sub folders under Working Directory for .usr scripts and store it in an array
  2. obtain the automation content(s) of scheduled test runs by resolving the value of magic variable TESTCASES_AC. Refer to this article to learn more about MAGIC VARIABLES in Universal Agent
  3. if the value of TESTCASES_AC variable is empty, which means there is no test runs being scheduled to be executed (e.g. when this Universal Agent is executed in the first time), we will let the agent execute the all .usr scripts found in step #1, then collect the execution result to create test runs in qTest Manager and submit test logs to those test runs
  4. if TESTCASES_AC variable has value which are the automation contents of scheduled test runs, we will instruct Universal Agent to only execute .usr script matching automation content

Copy the following script and paste it to the Execute Command editor.

const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');


// this is the path to the qtp.vbs script
// NOTE: 
// 1. change the path to qtp.vbs script to reflect the actual path in your host machine
// 2. use / as path separator (as below) or if you prefer \ on Windows then please add \\ instead, 
//    e.g. 'c:\\qtest\\agentctl-2.2.1\\build\\qautomation\\lib\\qtp.vbs'
let qtpScriptPath = 'c:/qtest/agentctl-2.2.1/build/qautomation/lib/qtp.vbs';

// process.env.WORKING_DIR holds the value of Working Directory you configured in Universal Agent
let workingDir = process.env.WORKING_DIR || '';
workingDir = workingDir.replace(/\\/g, "/");
console.log('--- Working directory: ', workingDir);
if (!fs.existsSync(workingDir)) {
  console.log("No working directory found.");

// results folder contains all currently executed results to submit logs to qTest
// NOTE: by default, the result fill be located at ${working directory}/test-results
let resultsFolder = path.resolve(`${workingDir}`, 'test-results');

// create test results folder. If it already exists, deletes it and re-create it again.
if (fs.existsSync(resultsFolder)) {
  execSync(`rmdir /s /q "${resultsFolder}"`);

// Automation content is the identifier of an automated Test Run in qTest Manager.
// In the context of UFT, each Test Run's automation content contains the name of the usr script, e.g. LoginFlights
// We will try to get all automation content(s) of all the test run(s) stored in magic variable TESTCASES_AC, 
// The value of TESTCASES_AC is under comma separated string, or empty if there is no test runs scheduled to be executed.
// Example value of TESTCASES_AC: LoginFlights.usr,Sample1.usr,Sample2.usr
let testcases_AC = $TESTCASES_AC;
testcases_AC = testcases_AC ? testcases_AC.split(',') : [];

// this array stored all the .usr files in a specific folder
let usrFiles = [];

// this function recursively scans all .usr files inside a folder and its sub-sfolder
// then store full path of every found .usr file in the array `usrFiles`
function scanUFTProjects(dir) {
  let files = fs.readdirSync(dir);
  for (let i = 0; i < files.length; i++) {
    let filePath = path.join(dir, files[i]);
    let stat = fs.lstatSync(filePath);

    if (stat.isDirectory()) {
      // scan the folder recursively
    } else if (filePath.indexOf(UFT_PROJECT_EXTENSION) >= 0) {
      // it's the .usr file, add it to usrFiles array

// This function kicks off a specific UFT script (the .usr file). What it does is to launch a
// separate process to executes qtp.vbs script defined in the variable `qtpScriptPath`
function executeTest(usrFile) {
  let projectName = path.basename(usrFile, UFT_PROJECT_EXTENSION);
  let uftProjectPath = path.resolve(usrFile, '..');
  let resultFolder = path.resolve(resultsFolder, projectName);
  if (!fs.existsSync(resultFolder)) {

  // compose the command to be executed
  command = `cscript "${qtpScriptPath}" /run-path:"${uftProjectPath}" /result-path:"${resultFolder}"`;
  // execute the test
  console.log(`*** Executing command: ${command} ***`);
  execSync(command, { stdio: 'inherit' });

console.log(`--- Scanning all uft projects from working directory.`);
console.log(`--- Found ${usrFiles.length} uft projects.`);
if (usrFiles.length <= 0) {
  console.log('No UFT projects found in working directory.');

 * Kicks off UFT test. What it does is to resolve the value of `testcases_AC` variable and validate:
 * Case 1: if that variable has value, meaning there is/are test run(s) being scheduled in qTest Manager
 *   -- for each scheduled test run, finds and executes the .usr script whose name matches the test run's automation content
 * Case 2: the value of testcases_AC is empty, meaning no test runs being scheduled when the Universal Agent is executed in the first time
 *   -- executes all the .usr scripts found inside the working directory
if (testcases_AC && testcases_AC.length > 0) {
  for (let testcase_AC of testcases_AC) {
    let scheduledProject = testcase_AC + UFT_PROJECT_EXTENSION;
    // find the .usr script that matches the automation content
    let foundTests = usrFiles.filter(p => p.indexOf(scheduledProject) >= 0);
    // if found, execute it
    if (foundTests.length > 0) {
} else {
  // there is no test runs being scheduled, execute every UFT script 
  // whose path is stored in the `usrFiles` array, one by one
  for (let usrFile of usrFiles) {
console.log('*** Execution completed ***');

Path to Results

  • Enter C:\test-projects\uft-sample-14.03\test-results

Result Parser

  • Select Unified Functional Testing (UFT) as the Result Parser.


  • If you want the Universal Agent to submit test results to qTest Manager, you must specify values for both Path to Results and Result Parser. Otherwise, you must do that yourself through Execute Command.

The screenshot below shows how the new UFT Universal Agent is configured.


Select SAVE to finish creating the agent. The agent will be available the next time the host machine polls to qTest Launch.

Execute UFT Universal Agent

  1. Access the host machine where the UFT Universal Agent was created.
  2. Locate the agent in the Agents list and select the Run now button.
  3. The Universal Agent execution dialog will display.
  4. Select the Execute button to kick off the agent execution and you will see the logs shown in the Console Log section. If the execution is successful, you'll see the test run logs being submitted to qTest Manager.

Next, access to qTest Manager. Select qConnect Sample Project then go to Test Execution module. You'll see the test results submitted to qTest Manager as Test Runs under a Test Suite naming Automation YYYY-MM-DD, as shown below.


Now we are going to schedule test execution for some specific test runs with the UFT agent and verify it only executes tests that match the scheduled test runs.

Schedule Test Execution for specific Test Runs

From qTest Manager, select the project qConnect Sample Project then click on Test Execution tab. Do the followings:

  1. Select the newly created test suite, in our example, it is Automation 2019-01-04.
  2. From the test run list on the right, select the first test run
  3. Click on MORE button, then select Schedule


Elite user

You will be navigated to qTest Launch. On the Select Cases screen, enter the following:

  • Schedule Name: Execute test with UFT Universal Agent
  • qTest Manager Project: make sure the project that the test case belongs to is selected. In our sample it is qConnect - Sample Project 
  • Host - Agent: select the UFT agent we created previously


Click RUN NOW to finish test scheduling.

Premium user

On SCHEDULE AUTOMATION TEST EXECUTION dialog, enter the followings:

  1. Name: name of the schedule, e.g. Execute test with UFT Universal Agent
  2. Agent: select the UFT agent we created previously
  3. Click OK button to complete test execution scheduling for the selected test run.


Now go back to Automation Host UI. Click Poll Now button.


At this stage, the Automation Host does the followings:

  • immediately polls to qTest Manager to load schedule jobs and
  • execute the job execution for the test in UFT project that match the automation content of the scheduled test run

When the execution completes, click on View Log icon to view execution log.


A log screen will display that shows the last execution logs. Verify that the log reported only 1 test has been executed.



You have successfully scheduled test execution for specific test in your UFT project using Universal Agent, and have it report the test execution to qTest Manager.



Powered by Zendesk