Create TestNG Agent from Launch

Updated: starting from qTest Launch 1.3 and Automation Host version 2.1.0, you can integrate your TestNG project with Universal Agentfollowing these instructions.

In this article, we will walk you through how to add a new TestNG Agent to a specific agent host from qTest Launch.

Follow this article to learn how to access to a specific host in qTest Launch in order to create a new Agent.

Prerequisites

  1. Activate Automation Integration

  2. Install and Register the Automation Host

Step 1

Download the sample TestNG automation project at https://github.com/QASymphony/testng-sample and save it to your local machine.

  • On Windows. D:\testng-sample

  • On Linux or Mac. /usr/local/testng-sample

Structure of TestNG project:

  • Dependency libraries are under /resources/libs folder

  • The TestNG XML file: testNgSuite.xml

  • The automation project being packaged in .jar file, and located at /target/OpenURL-1.0.jar 

Step 2

Execute the command below to compile automation project and package it:

mvn clean compile package test

Step 3

Access to qTest Launch then locate a host that you want to create a new agent and open its detail dialog. On the host detail dialog, click on Agents tab then Click on + New Agent button. You will be presented with the New Agent dialog, as shown below:

General Information

  • Agent Name: name of the new agent, e.g. New Agent

  • qTest Manager Project: select a project that the new agent will be associated with, e.g. qConnect - Sample Project

  • Agent Type: TestNG Agent

Test Scripts

  • Directory (required): specify the path to your TestNG source code that you have downloaded in step 1

  • Scripting libs (optional): provide paths to the dependency libraries (files or folders) in your TestNG source code that you have downloaded in step 1. You can input one or multiple paths, separated by a comma. If all of your libraries are in a folder, simply put its path here

  • Include (required): define patterns to scan for tests in the automation project (methods/classes) using ANT Style Pattern Matcher. Use a comma as a separator between patterns.

  • Exclude: define patterns to ignore tests (method/classes) when scanning using ANT Style Pattern Matcher

HINT: ANT Style Pattern Matcher uses the following rules:

  • ? matches one character.

  • * matches zero or more characters.

  • ** matches zero or more 'directories' in a path.

Test Scripts example on Windows

Test Scripts example on Linux or Mac

Execution

TestNG Agent supports 3 execution modes to Build and run your test project: Command, Ant, Maven. You need to provide different information depending on the execution mode you choose.

Execution mode: Maven

  • Executable home: input the path to the directory where Maven is installed

  • Goal: input the goal defined in your POM file to deploy your project

  • POM file: provide the path to your POM file, which is located under the home directory of your test source code. Please note that this is the relative path under your scripting directory. 

    • IMPORTANT: refer to our important notes when you choose to execute your actual test project with Maven

  • TestNG test file: input the name of TestNG XML file here. NOTE: This file should be located under the home directory of your source code and you can only input one file. You can simply input its relative path into this field

  • Command arguments: provide any additional arguments to execute the target

Screenshots below shows an example of Maven execution mode information.

Windows:

Linux or Mac

Execution mode: Ant

  • Executable home: path to the directory where Ant is installed

  • Target: specify which target to be executed. This is the name of the target which has been defined in your Build file.

  • Build file: the path to your Build file in which the above target is defined. This file is located under the home directory defined in Test Scripts section of your test source code

    • IMPORTANT: refer to our important notes when you choose to execute your actual TestNG project with Ant

  • TestNG test file: input the file name TestNG XML file here. NOTE: this file should be located under the root directory of your source code and you can only input one file. You can simply input its relative path in this field.

  • Command arguments: provide additional arguments to execute the target

Screenshots below shows an example of Ant execution mode configuration

Windows:

Linux or Mac

Execution mode: Command

  • Executable home: input the path where JAVA/JDK is installed

  • Command: the command to execute your scripts

  • TestNG test file: input the file name TestNG XML file

  • Command arguments: target directory where all built outputs are located plus any needed arguments

Below are examples of Command execution mode configuration.

Windows:

  • Executable mode: Command

  • Executable home: C:\Program Files\Java\jdk1.8.0_144

  • Command: java

  • TestNG test file: testNgSuite.xml

  • Command arguments: -cp “D:\testng-sample\target\*”

Linux or Mac

  • Executable mode: Command

  • Executable home: /usr/local/jdk1.8.0_144

  • Command: java

  • TestNG test file: testNgSuite.xml

  • Command arguments: -cp “/usr/local/testng-sample/target/*”

IMPORTANT NOTES

1. While the agent is executing your tests, it is recommended that you do not modify TestNG XML file as the changes may lose after the execution is done.

2. If a failure occurs during test submission, the Failure Log will be included as a text file attachment in the Test Log Details.

3. If you choose to execute your actual TestNG project with Maven, make sure to add the plugin maven-sure-fire-plugins and maven-compiler-plugin to your pom.xml file, as well specify the actual path to your TestNG Test Suite XML file, as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    ... 
    <!-- Configure maven surefire plugin for TestNG Agent to collect the logs and submit to qTest -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>2.19.1</version>
                <configuration>
                    <suiteXmlFiles>
                        <suiteXmlFile>/relative/path/to/your/testNgSuite.xml</suiteXmlFile>
                    </suiteXmlFiles>
                    <testFailureIgnore>true</testFailureIgnore>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <encoding>iso-8859-1</encoding>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
    <!-- End configuration -->
</project>

* Refer to the pom.xml file in our sample TestNG project for more details: https://github.com/QASymphony/testng-sample/blob/master/pom.xml 

4. If you choose to execute your actual TestNG project with Ant, make sure to add these configurations to your build.xml file

4.1 Added these properties under <project> tag, as shown below, in bold.

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE project []>
<project name="..." default="all" basedir=".">

    <!-- ========== Select xml file to be run =================================== -->
    <property name="testng.xml.file" value="testNgSuite.xml" />
    <!-- ======================================================================= -->

    <property name="test.dest" value="${basedir}/target"/>
    <property name="jars" value="resources/libs"/>
    <property name="version" value="1.0" />
    ...     <!-- other configuration -->
</project>

4.2 Add these targets to the build.xml file, as shown below:

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE project []>
<project name="..." default="all" basedir=".">
    ...
    <!-- cleaning the destination folders -->
    <target name="clean">
        <delete dir="${test.dest}"/>
    </target>
    <!-- ====== For setting the classpath ====  -->
    <target name="classpath">
        <path id="classpath">
            <fileset dir="${jars}">
                <include name="**/*.jar"/>
            </fileset>
            <pathelement location="target/classes"/>
            <pathelement location="target/test-classes"/>
            <pathelement location="src/test/resources"/>
        </path>
    </target>
    <!-- ============ Initializing other stuff ===========  -->
    <target name="init" depends="classpath">
        <taskdef name="testng" classpath="${jars}/testng-6.8.7.jar" classname="org.testng.TestNGAntTask" />
    </target>

    <!-- ============ Compile ===========  -->
    <target name="compile" depends="init,clean,classpath">
        <mkdir dir="${test.dest}"/>
        <mkdir dir="${test.dest}/classes"/>
        <javac srcdir="src/main/java" destdir="${test.dest}/classes" classpathref="classpath" includeantruntime="false"/>
    </target>

    <!-- ============ Compile test  ===========  -->
    <target name="compile-test" depends="compile">
        <mkdir dir="${test.dest}/test-classes"/>
        <javac srcdir="src/test/java" destdir="${test.dest}/test-classes" classpathref="classpath" includeantruntime="false"/>
    </target>
    <!-- ============ Package jar file  ===========  -->
    <target name="jar" depends="compile,compile-test">
        <mkdir dir="${test.dest}"/>
        <jar destfile="${test.dest}/${ant.project.name} ${version}.jar" basedir="${test.dest}/classes" />
    </target>
    ...
    <!-- ============ Run Tests ===========  -->
    <target name="all" depends="jar">
        <!-- Assume test.path contains the project library dependencies -->
        <testng classpathref="classpath" 
                outputDir="${test.dest}/testng-reports"
                haltOnFailure="false">
            <!-- Extra project classpath, which is not included in above "test.path" -->
            <!-- Tell Ant where the project and test classes are -->
            <classpath location="${test.dest}/classes" />
            <classpath location="${test.dest}/test-classes" />
            <xmlfileset dir="${basedir}" includes="${testng.xml.file}"/>
        </testng>
    </target>
</project>
Refer to the build.xml file in our sample TestNG project for more details: https://github.com/QASymphony/testng-sample/blob/master/build.xml