backup-page-ANT 2017-06-16T13:01:05+00:00

ANT

Introduction

Apache Ant or ANT is a command-line tool for driving software processes; one of its major applications is to compile and run Java applications.

ANT can be used to run a Provar test suite via the command line or using a Continuous Integration (CI) server (e.g. Jenkins). This is achieved by configuring and executing Provar Compile and Run tasks in ANT. Refer to Continuous Integration Introduction for more information.

ANT can be used to run a single Test Case or an entire Test Folder.

Use the following links to navigate to the relevant section:

Prerequisites

For this help page some knowledge is assumed of ANT build files, tasks and file sets.

Your machine should also have:

  • Java 1.7 JDK. The JAVA_HOME environment variable must point to the Java 1.7 JDK
  • The Apache Ant build tool, version 1.8 or later

Environment Setup

ANT must be installed and configured to run with Provar. If Provar is already installed, only the Build.xml file need be configured for Provar and executed from the command prompt. If Provar is not installed, a few additional steps will be required.

ANT with Provar installed

  1. Locate the PROVAR_HOME folder (e.g. C:\ProvarAnt) and within it the 4 .jar files beginning ‘ant-provar’ (ant-provar.jar, ant-provar-bundled.jar, ant-provar-project.jar and ant-provar-sf.jar). Copy these 4 files.
  2. Locate the ANT installation lib folder on your build machine (on Windows this is typically C:\Program Files\apache-ant-\lib).
  3. Copy the 4 .jar files into the ANT installation lib folder.
  4. Create a Build.xml file (refer to Configuring Build.xml below for more information).

If you are using the PROVAR_HOME Environment Variable, make sure it is set to the Provar Installation directory. However it is recommended to avoid using this and use the absolute path. Refer to Configuring Build.xml below for more information.

ANT without Provar installed

  1. Create a PROVAR_HOME folder in a suitable location on your build machine’s hard disk.
  2. Set the Environment Variable PROVAR_HOME to this folder (e.g. C:\ProvarAnt).
  3. Download the ProvarANT.zip file provided by the support team.
  4. Extract the file into the PROVAR_HOME folder. The folder now should contain 3 items: antLib and com.provar.core.lib.selenium-2.46.0_2.46.0.
  5. Create a Build.xml file to run (refer to Configuring Build.xml below for more information)

Make sure that the PROVAR_HOME Environment Variable is used in the Build.xml.

Configuring Build.xml

After the ANT environment has been set up, the next step is to configure the Build.xml file. Refer to the component definitions and examples below to configure your file.
The main components of the file are as follows:
  • xmlns:Provar: Defines the provar:run task (see below)
  • provar.home: Contains the location that the Provar installation was unzipped. On Windows this defaults to C:\Program Files\Provar. ​This attribute is not required if there is a full Provar installation in the default location, or if PROVAR_HOME Environment Variable is set
  • testproject.home: Defines the folder which contains the Test Project’s .testproject file
  • testproject.results: Defines the folder where the Test Run’s results should be written
  • taskdef: Defines the Run-Test-Case and Provar-Compile tasks together with the classpaths
  • provar:compile or Provar-Compile: Compiles the Test Project’s Custom Test APIs, Page Objects and Page Components so that they can be executed. This is necessary since Java .class files are not usually stored in Version Control and need to be generated before Test Cases are executed. Refer to Provar Compile Task below for more information
  • provar:run or Run-Test-Case: The Runner task executes your test cases and produces an execution report in HTML format. (Refer to Provar Runner Task below for more information)

Note that the use of taskdef, Compile and Run tasks differs depending on whether ANT is running with Provar installed or without. This is demonstrated in the examples below.

Example 1: Build.xml with Provar installed

This sample file shows a Build.xml configured with Provar installed.

  • x​mlns:provar= ​defines the p​rovar:run ​task
  • p​rovar.home contains the location where the Provar installation was unzipped to (refer to Environment Setup above). On Windows this defaults to C​:\ProgramFiles\Provar
  • t​estproject.home is the folder that contains the Test Project .​testproject file
  • maxMemory defines the maximum memory that the plug-in can use
  • t​estproject.results is where the test run’s results should be written
  • p​rovar:run runs one or more Test Cases or Test Folders

Note that provarHome is not required if there is a full Provar installation in the default location or if the PROVAR_HOME environment variable is set.

Example 2: Build.xml for ANT without Provar installed

This sample file shows a Build.xml configured without Provar installed.

  • p​rovar.home contains the location where the Provar installation was unzipped to (refer to Environment Setup above). On Windows this defaults to C​:\ProgramFiles\Provar
  • t​estproject.home is the folder that contains the Test Project .​testproject file
  • maxMemory defines the maximum memory that the plug-in can use
  • t​estproject.results is where the test run’s results should be written
  • <​taskdef> ​defines the R​un-­Test-­Case ​task, together with its classpath
  • Run­-Test-­Case runs one or more Test Cases or Test Folders

Note that, while the classpath on <​taskdef>​ allows different Provar versions to be run on the same machine, ANT always looks in its lib folder first. This means that c​lasspath​ entries will be ignored if the same .jar files exist in the lib folder.

Provar Compile Task

The Compile task is a wrapper around ANT’s standard javac task and inherits these properties. The Compile task sets the source, destination and classpath properties for you from the supplied provarHome and projectPath values.

The Compile task properties are as follows:

provarHome

  • Required: No
  • Definition: The fully qualified path of your Provar installation directory
  • Defaulted as follows:
    • The PROVAR_HOME Environment Variable, if set
    • Otherwise: C:\Program File\Provar on Windows
    • Otherwise: /Applications/Provar on Mac

Note that you do not need to specify this attribute if you have a full Provar installation in the default location or if the PROVAR_HOME Environment Variable is set.

projectPath

  • Required: Yes
  • Definition: The fully qualified path of the Test Project containing the tests to be run.  This is the folder that contains the .testproject file

Provar Runner Task

The Runner task properties are as follows:

provarHome

  • As above

projectPath

  • As above

resultsPath

  • Required: Yes
  • Definition: The fully qualified path of the folder to which Provar will write the test results

testEnvironment

  • Required: No
    Definition: The name of the Test Environment that the test run should be executed against. Test Environments are defined in Test Settings
    Defaults to: ”

webBrowser

  • Required: No
  • Definition: The web browser to be used for UI testing. Permissable values are:
    • Chrome
    • Firefox
    • IE
  • Defaults to: The web browser last selected in the Test Project

webBrowserConfiguration

  • Required: No
  • Definition: The web browser window size. Browser configurations are defined in Test Settings
  • Defaults to: The web browser last selected in the Test Project

licensePath

  • Required: No
  • Definition: The fully qualified path to your Provar license file
  • Behavior: If the path points to a file, then that file is used. If the path points to a folder then the first activated license in the folder is used
  • Defaults to: \Provar\.license

testOutputLevel

  • Required: No
  • Definition: Controls the amount of test output logged to the ANT test log. Refer to Logging Levels below for more information
  • Defaults to: WARNING

pluginOutputLevel

  • Required: No
  • Definition: Controls the amount of plugin output logged to the ANT test log. Refer to Logging Levels below for more information
  • Defaults to: WARNING

fileSet

  • Required: Yes
  • Definition: One or more ANT elements defining the .testcase files to be run.  You can specify individual Test Case files, folders containing Test Case files or a combination of both. Refer to FileSet for more information

excludeCallableTestCases

  • Required: No
  • Definition: Indicates whether callable Test Cases should be omitted from execution (true) or included in execution (false)
  • Defaults to: true

salesforceMetadataCache

  • Required: No
    Definition: Controls the Salesforce Metadata usage. Options are:

    • Reuse: reuses existing metadata
    • Refresh: downloads only metadata changes
    • Reload: deletes old metadata files and downloads fresh metadata

projectCachePath

  • Required: No
  • Definition: The fully qualified path of the folder that will be used for storing metadata

pluginProperties

  • Required: No
  • Definition: One or more elements defining settings for Provar’s test plugins. Refer to Plugin Properties below for more information

emailProperties

  • Required: No
  • Definition: One or more elements defining settings for sending email upon ANT execution completion. Refer to Email Properties below for more information

Plugin Properties

Plugin Properties can be nested inside the Runner task to allow customization of the memory and debugging settings for Provar’s plug-ins.

plugin

  • Required: Yes
  • Options are:
    • project: the Test Project’s custom Test APIs
    • bundled: Provar’s bundled Test APIs (excluding UI APIs) and functions
    • sf: Salesforce Test APIs, UI Test APIs and the Test Project’s Page Objects

maxMemory

  • Required: No
    Definition: The maximum amount of memory that the plug-in can use in megabytes. Must be an integer value. Note that this translates the -Xms property for the Java process (where the unit is always ‘m’)

debugPort

  • Required: No
  • Definition: The port number for attaching a Java debugger to the plug-in’s Java process. If ‘0’ then a free port is automatically allocated and displayed in the ANT output

debugSuspend

  • Required: No
  • Definition: Indicates whether the Java process should wait for the Java debugger to connect at start up. Valid values are ‘true’ and ‘false’.

Email Properties

Email Properties can be nested inside the Runner task and allow the sending of emails after ANT execution is completed.

  • This sample file shows an example to send an email after execution
  • This sample file shows an example to send an email to multiple users using a comma-separated list

sendEmail

  • Required: Yes
  • Definition: Indicates whether an email should be sent after ANT execution

primaryRecipients

  • Required: Yes
  • Definition: The email addresses which should receive the email

ccRecipients

  • Required: No
  • Definition: The email addresses which should be CC’d in the email

bccRecipients

  • Required: No
  • Definition: The email addresses which should be BCC’d in the email

Logging Levels

The Logging Level controls the amount of detail logged to the ANT log file during test execution. It applies to the testOutputLevel and pluginOutputLevel attributes (refer to Provar Runner Task above for more information).

The options are as follows:

  • SEVERE: Only error messages are logged
  • WARNING: Error and warning messages are logged
  • INFO: Error, warning and informational messages are logged
  • FINE: Error, warning, informational and high-level debug messages are logged
  • FINER: Error, warning, informational and all debug messages are logged
  • FINEST: All messages are logged