Launchers / Automated tests

Ant Launcher (ant.jar)

The ant launcher allows running builds using the ant utility to any target.
The launcher allows to:
  • Scan existing build.xml files and automatically create a corresponding test fo each build target
  • Manage this target builds as tests, so that each one can be used separately in a campaign
  • Manages the environment variables for you as Ant relies on those to execute through its prepared command files ant.bat or ant.sh
This is useful when you want to test a solution that needs to be assembled from its sources, including the tests or not.
This way you can build the solution and then test it. So you are then sure to run your tests against the latest version of your solution.

Note: this launcher does not read the result from potential tests that run as a result of the built. For this just use teh approriate test launchers (e.g. Junit, TestNG...)

Latest tested with: Windows 10-17134, ant 1.10.3
This version of the launcher is initial (v1.0)

Configuration

The XStudio ant.xml file is just a template and must NOT be edited.
It's used by the system to dynamically build the form that the user will be able to fill in from the GUI when creating a custom execution configuration.

Parameter Description
Ant
Project path This sets the location where the project resides. There may be sub-projects in it. Just set the root path of the project with no ending slash

Default value is: C:/My_workspace
JAVA_HOME This indicates where you java run engine resides. This is in case you don't have it already set or need to use a different java version than the default one set on the target test server
There's no default value
ANT_HOME This indicates where the ant build utility is located. This will be completed with /bin/ant.bat or /bin/ant.sh based on the OS you use
Note that this optional as you may already have been set. In case you provide it, XStudio will use it as a path and also set the ANT_HOME environment variable for the duration of the execution.
Default value is: c:\ant\apache-ant-1.10.3
ANT_OPTS This must indicate the OPTIONS that may be needed by ant for its execution
This is optional

There's no default value
ANT_ARGS This must indicate the ARGUMENTS that may be needed by ant for its execution
This is optional

There's no default value
OS This must indicate which OS the build will run on.
it is solely used to define if we will run the ant.bar or the ant.sh

Default value is: Windows Valide values are : Windows and Linux

These values can be changed while creating the campaign session from XStudio.
Note about file path parameters:
Any parameter referring to a file or folder path (for instance Test root path) can be provided either using \ separator (if the tests are going to be executed on a Windows agent) or / separator (if the tests are going to be executed on a linux or MacOSX agent).

On windows, if you provide a path containing an OS-localizable folder such as C:\Program Files, always prefer the English version (i.e. NOT C:\Programmes if you're using a french-localized Windows) or the corresponding native environment variable (i.e. %PROGRAMFILES%).


Specific test attributes

For some launchers, it is possible or necessary to associate attributes to individual test.
There's no specific attribute to set for test runnning ant builds

Specific test case parameters (params)

For some launchers, it is possible or necessary to associate params to individual test case.
There's no specific param to set for test case runnning ant builds

Envrionment variables used

For some test frameworks or tools, it is possible or necessary to set environment variables prior to execution.
For ant the following can be defined in the configuration and will be automatically set by XStudio for the duration of the execution.
  • JAVA_HOME
  • ANT_HOME
  • ANT_OPTS
  • ANT_ARGS

Process

1) The launcher will constitute and run the interpreter with the following templates:
<ANT_HOME>/bin/ant.bat|.sh -debug -noinput -buildfile <testname>.xml -keep-going <com.xqual.ant.goal> (default is 'verify') [<target>] (target is extracted from the test names - see below)

Note: when scanning for ant build files, XStudio creates one test for each target it founds into the build file.
The convention for the test name is as follows:
<build file name> target:<target name> for:<project>
e.g. build target:clean for:jarbundler which allows executing a ant build for teh target clean concerning the project jarbundler
2) The log file XstudioLogFile.txt will be attached to the result
3) The launcher parses the specific XstudioLogFile.txt trace file and use it to provide summarized information back to the testers


Permissions

WARNING: if you're running your tests on Windows, it may be required to run the tests as administrator.
Having an account with Administrators permissions may even not be enough in some cases (especially if you're using Windows 10) and you may need to disable completely the UAC (User Access Control) on your computer.
To do so:
  • Press the Windows + R key combination
  • Type in regedit
  • Go to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System
  • In the right-side pane, look for EnableLUA and set the value 0
  • Close the registry editor
  • Restart your computer

Debug

If your tests are not executed correctly or are reporting only failures, this is very likely because your configuration is incorrect or because you used a wrong naming convention for your tests and test cases.

The best way to quickly find out what's wrong is to look at the traces generated by XStudio (or XAgent).
The traces always include the detailed description of what the launcher performs (command line execution, script execution, API calling etc.) to run a test case. So, if you experiment some problems, the first thing to do is to activate the traces and look at what's happening when you run your tests.

Then, try to execute manually in a cmd box the exact same commands.
This will normally fail the same way.
At this point, you needs to figure out what has to be changed in these commands in order to have them run properly.

When you have something working, compare these commands to what's described in the Process chapter above. This will tell you exactly what you need to change.

Most of the time, this is related to:
  • some incorrect values in some parameters of your configuration,
  • the name of your tests,
  • the name of your test cases,
  • the canonical path of your tests