Using the Shell Agent

Note: Follow this article to create Shell Agent to automation host prior to 1.3.8, if you are using Automation Host 1.3.8 or later, follow these instructions instead.


The Shell Agent offers a high level of flexibility using the Test Automation Scheduler. Benefits include:

  • The ability to schedule automated test executions for tests in any framework and language, including custom frameworks
  • The ability to kick off shell or batch scripts that are executable from your console or terminal.
  • The ability to define which test runs get executed and how the results will be passed into Test Execution by using APIs.


  1. Activate Automation Integration settings in your qTest project and map the automation execution statuses to qTest status values.
  2. Install and Register the Automation Host. Download the link from the qTest Resources Page onto the machine where your automation scripts are deployed.
  3. Install the Automation Agent in your Automation Host. An automation host includes multiple automation agents. An agent integrates ONE qTest project with ONE automation framework and ONE scripting directory.

Configure the Shell Agent

After you have installed the Plugin, you can add a new Shell Agent. Fill in the following details of the Agent Configuration dialog:

  • Agent Name: Define the agent's name. This is the agent name that will be selected in qTest Manager Test Execution when scheduling Test Runs
  • qTest Manager Project: select one of the qTest Manager projects from which qTest Manager users can schedule their Test Runs using this agent. The list includes all projects which are accessible using the agent’s credentials. An agent only integrates with one qTest Manager project, so if you wish to integrate multiple qTest projects with the Shell Agent, you will need to create multiple agents (one for each qTest project)
  • Automation Framework: select Shell Agent
  • Working Directory: Define a directory under which the kick-off scripts will be executed
  • Allocated time: specify how long (in minutes) you expect the script will complete
  • Kick-off scripts: Define the scripts to be kicked off by the Shell Agent. In general, the scripts should execute your automated tests, collect the test results, and report them to qTest Manager using our APIs.  You can define the scripts using 1 of 3 options:
    1. An executable file stored on your local machine. You can use either absolute path or relative path under the Working Directory above to specify the executable file
    2. An executable file stored on a shared network directory. Keep in mind that the shared network directory should be mounted to a logical directory on your local machine since the network directory path is not supported
    3. A command entered directly into the text area of the Agent Configuration dialog

Create Automated Test Cases and Test Runs before scheduling

The new custom Shell Agent has a different approach to creating automated Test Cases and Test Runs compared to the existing built-in agents (e.g. TestNG, jUnit, Cucumber, JBehave, UFT).  The other built-in agents scan your automated test scripts for Test Cases and create them into Test Design.  Instead, the Shell Agent allows you to define which Test Runs get executed and how the results will be passed into Test Execution by using APIs.

Make sure your custom Kick-off script performs these actions: 

  1. Execute automated tests 
  2. Collect test results
  3. Submit automated test logs to qTest using APIs (This will create automated Test Cases, create automated Test Runs, and submit Automated Test Logs)

The automated Test Cases that are created will have a unique value in the Automation Content field which serves as a fingerprint that links to Test Runs for traceability.

Click the orange Play button to kick off your scripts from the Agent.

HINT: there is a difference between the green Play button and the orange Play button:

  • The orange Play button: the agent will run the kick-off scripts for immediate execution. It does not require a scheduled job
  • The green Play button: the agent will retrieve all unexecuted scheduled jobs from your qTest Manager instance and then execute all of them (assumes that the tests have already been scheduled)

Create Automated Test Runs and Schedules

Once the automated Test Cases and Test Runs exist in qTest, you can create additional Test Runs and setup schedules for recurring execution using the UI. You may wish to create additional Test Runs using the original automated Test Cases if you want to collect execution results under a new Test Cycle or Release. This can be done through the UI (e.g. by a Manual Tester) without requiring additional coding.

You may also wish to setup schedules through the UI to execute the automated tests based on a recurring cadence (e.g. every week). The Shell Agent will poll schedule(s) from qTest and automatically execute your Kick-off Scripts. The automated test logs will be collected back to qTest. You can view the existing schedules and their statuses inside the Schedules area of Automation Integration Settings. 

Check out this article for more detailed instructions: Create Automated Test Runs and Schedules 

Pass data to kick-off scripts

When Test Runs are scheduled from qTest Manager UI, you can pass additional data to the agent along with the schedule. You can incorporate this information as parameters in your kick-off scripts as below:

  • If your Kick-off Scripts are entered into the text area of the Agent Configuration dialog, enter a command with the parameters into the Kick-off Scripts text area. The Shell Agent will replace the parameters with their real data when it executes your command.
  • If your Kick-off Scripts reside in an execute file, pass the parameters to the scripts using the command arguments. (You cannot enter the parameters in scripts stored in your executable files).

For example, in the kickoff script area, you might have the following:

  • $QTE.projectId $QTE.projectName $QTE.jobStatus

The available parameters include:






ID of the project which is configured in the Shell plugin



Name of the project which is configured in the Shell plugin



The schedule job's status

In addition to the above, all system fields and custom fields of the scheduled Test Runs and their Test Suite are also stored in the agent’s database. You can retrieve the data using an URL which is available from a local environment variable QTE_SCHEDULED_TX_DATA. Please see the sample scripts below to get the data:

var opts = {
   url: process.env.QTE_SCHEDULED_TX_DATA,
   json: true,
   headers: {
     'Content-Type': 'application/json'
 request.get(opts, function(err, response, body){
     console.log('testRunObject: ' + JSON.stringify(body.QTE.testRuns));
    console.log('testSuiteObject: ' + JSON.stringify(body.QTE.testSuite));

The data will be in JSON format. You can parse the JSON string to extract the information you need. See the sample JSON below.


  • If you manually execute the kick-off scripts without scheduling Test Runs, the above data will not be available.
  • The value of QTE_SCHEDULED_TX_DATA is only available at runtime when the Shell Agent executes scheduled tests. Its value is actually an API endpoint for Automation Host to get scheduled test data from qTest Manager. The data from the URL provided in this variable is ONLY available during that same runtime.
    The URL will not provide data after the job was executed, so in order to debug and set up the Shell Agent, it will need to be executed from qTest Manager. Note that this will be resolved in the next major release when the Universal Agent is introduced.
   "parameters": {
     "QTE": {
       "projectId": 38413,
       "projectName": "D Automation Project",
       "jobStatus": "NOT_RUN",
       "testRuns": [
           "Name": "Login",
           "Run Order": "9",
           "Execution Type": "Functional",
           "Status": "Done",
           "Priority": "Medium",
           "Pid": "TR-161",
           "Planned Start Date": "2017-08-23T02:15:49+00:00",
           "Assigned To": "Luke Dang",
           "Rich text editor ts": "<p>Rich text editor ts 123</p>",
           "Rich text editor tr": "<p>Rich text editor tr</p>",
           "Environment": "Env 1",
           "Id": "10884845",
           "Planned End Date": "2017-08-30T00:00:00+00:00"
       "testSuite": {
         "Description": "<p>projectid test a</p>",
         "Pid": "TS-11",
         "Planned Start Date": "2017-08-23T02:15:49+00:00",
         "Name": "Test Suite a1",
         "Assigned To": "Luke Dang, Linh Dang",
         "Target Release/Build": "Agent tool",
         "Environment": "Env 1",
         "Execution Type": "Functional",
         "Id": "792020",
         "Planned End Date": "2017-08-30T00:00:00+00:00"
   "client_id": 24258,
   "project_id": 38413,
   "job_id": 9887,
   "host_server_id": 480,
   "status": "NOT_RUN",
   "agent_server_id": 886,
   "agent_id": 134,
   "schedule_id": 7012,
   "automation_materials": [
       "test_run_id": 10884845,
       "test_case_id": 7676435,
       "test_case_name": "Login",
       "test_case_version_id": 9032785,
       "automation_content": "Login"
   "start_date": "2017-08-26T03:13:10+00:00"


Powered by Zendesk