Creating Ant Scripts to Run Unit Tests

You can use the Ant script wizard to create XML-based Ant scripts to run unit test files (file extension .bsrvtst, .exttst, .nattst, and .seqtst). You can run the Ant script from within NaturalONE or use the external command file to execute tests via a command line. The wizard generates the following files:

build.xml (contains the Ant script)
run.cmd (contains the DOS command file to run the script)

This document covers the following topics:

Set Up the Environment
Generate the Ant Script and Command Files
Define the testsuite Ant Task
Generating a JUnit-style Test Report

For information on creating unit test files, see:

Set Up the Environment

If you use an RPC environment connection ID, the ID must be setup before running the wizard. For information, refer to the EntireX documentation.

Generate the Ant Script and Command Files

This section describes how to create the build.xml and run.cmd files.

Start of instruction set To create the Ant script

Select New > Other on the File menu.

The Select a wizard panel is displayed.
Select Software AG > Testing > Natural Unit Test Ant Script.

For example:

Select Next.

The Ant information panel is displayed. For example:

graphics/ant-information.png

Using this panel, you can:

Task	Procedure
Change the location of the default root folder in Eclipse.	Select a new folder in Eclipse root.
Change the location of the default workspace folder.	Select a new folder in Workspace root.
Change the Broker connection ID.	Select a new ID in Broker connection ID.
Suppress the generation of the run.cmd file containing the DOS command file that runs the script.	Deselect Generate .cmd file.

Type the name of the Natural project in Output container or select Browse to display a list of available projects for selection.

Select Next.

The Item Selection panel is displayed. For example:

graphics/item-selection.png

Using this panel, you can:

Task	Procedure
Suppress the generation of a sample business service.	Deselect Sample business service.
Suppress the generation of a sample subprogram.	Deselect Sample subprogram.

Select the location of the default fileset folder (the workspace root folder and the output container folder) in Fileset.
Select Finish.

The generated build.xml and run.cmd files are displayed in the Navigator view. For example:

The build.xml file is displayed in the editor view. For example:
Refine the parameters for the testsuite Ant task as desired.

Define the testsuite Ant Task

This section describes the parameters for the testsuite Ant task in the generated build.xml file. The following topics are covered:

Description
Parameters
Parameters Specified as Nested Elements

Description

Represents the set of Natural unit tests to be run.

It is assumed that all necessary resources to run the tests are contained within a NaturalONE project. To run subprogram tests, a local copy of the subprogram file (.nsn file) must be in the correct Natural Library folder. To run business service tests, the folder must contain the domain file, steplib file associated with the domain, and all subprogram file(s) referenced by the business service.

Each testsuite contains a connection node that defines how the tests will connect the Natural server.

There are three ways to run Natural unit tests:

Create the units tests in NaturalONE using one of the Unit test wizards and then add a fileset subnode that will load the generated .bsrvtst, .exttst, or .nattst files
Add a subprogram node to test a specific subprogram
Add a businessService node to test a specific business service

Parameters

Attribute	Description	Required
failureProperty	Name of the Ant property that will be set to "true" when one or more unit tests fail.	No
haltOnFailure	Value indicating whether to halt the Ant script by throwing an Ant build exception upon receiving the first unit test failure. Valid values are "true" (halt the Ant script upon first failure) or "false" (run all unit tests regardless of failure). By default, this option is false.	No
logtests	Value indicating whether to log and save test history to the Testing-History folder. Valid values are "true" (save test history) or "false" (do not save test history). By default, this option is false.	No
name	Name used by the testsuite for output information in the test logs and Ant build log.	No
setProjectSteplibs	Value indicating whether the steplibs from the Natural project are set in the RPC server environment. Note: Keep in mind that the Natural Development Server used by the project must always be accessible when the value is `ON` (or when this property is not specified at all). The Natural Development Server is accessed to check the development mode settings for the steplib consolidation. These steplibs are then passed to the RPC server. In order to be compatible with older build.xml files, the default value is `ON` when not specified.	No

Parameters Specified as Nested Elements

This section describes parameters that are specified as nested elements. The following topics are covered:

connection
fileset
subprogram
businessService
input
validate

connection

Defines the connection settings to use to communicate with the Natural server.

Parameters:

Attribute	Description	Required
address	Broker address (when a broker ID is specified).	Mandatory when brokerID is used
brokerID	Broker ID for the connection.	Either brokerID or environmentName
environmentName	Name of an EntireX RPC connection configured in Eclipse.	Either environmentName or brokerID
logon	Whether a Natural logon is required.	Optional and only when brokerID is used
password	Password for the connection.	No
rpcUserID	RPC user ID for the connection.	Optional (used with secured Natural environments)
rpcPassword	RPC password for the connection.	Optional (used with secured Natural environments)
userID	User ID for the connection.	Mandatory when brokerID is used

fileset

Runs a set of unit test files.

Parameters:

Attribute	Description	Required
dir	Name of the folder/project containing the unit test files.	Yes

Parameters specified as nested elements:

Parameter	Description
include name	Name of the unit test(s) to run. For example, `include name="*/.bsrvtst" /` will run all business service unit tests in the specified folder/project.

subprogram

Runs a single test against a subprogram.

Parameters:

Attribute	Description	Required
project	Name of the Eclipse Natural project containing the subprogram.	Yes
library	Natural library containing the subprogram.	Yes
name	Name of the subprogram to execute, excluding the file extension (.NSN).	Yes

Parameters specified as nested elements:

Parameter	Description
input	See input.
validate	See validate.

businessService

Runs a single test against a business service.

Parameters:

Attribute	Description	Required
project	Name of the Eclipse Natural project containing the business service.	Yes
domain	Name of the domain containing the business service.	Yes
name	Name of the business service to run.	Yes
version	Version of the business service to run.	Yes
method	Name of the method to test.	Yes

Parameters specified as nested elements:

Parameter	Description
input	See input.
validate	See validate.

input

Specifies the value for a field to be used for input.

Parameters:

Attribute	Description	Required
name	Fully qualified field name in the format: [`level one`].[`name`]	Yes
value	Value to assign to the field.	Yes

validate

Specifies the field to be validated when it is returned by the call to the server.

Parameters:

Attribute	Description	Required
name	Fully qualified field name in the format: [`level one`].[`name`]	Yes
type	Type of validator to use (see the following table).	Yes
value	Value to assign to the field.	Yes

Validators:

Type	Description
BooleanValidator	Validates Boolean values. True values are: x, t , true, or 1.
ByteValidator	Compares an array of bytes.
ComparisonValidator	Compares values based on mathematical expressions (for example, ">", "<", "=", "<=", ">=").
DateValidator	Compares dates. The value is in the format: MON DD, YYYY (where MON is a 3-character abbreviation for a month name).
DecimalValidator	Compares decimal values.
IntegerValidator	Compares integer values. Decimals will be truncated.
RegexValidator	Verifies that the value in the field matches a regular expression.
StringValidator	Compares the value in the field against a string.
TimeValidator	Compares the value in the field against a time. Time is in the format: MMM d, yyyy hh:mm:ss.SSS.

Generating a JUnit-style Test Report

Usually, when running the Ant Testing script from within NaturalONE or from the command line, the standard output of the script is sufficient to determine the outcome of the test as well as the errors that might have happened in single test steps during the run. However, when the test is run within a continuous integration tool like Jenkins or Hudson, a different output style might be desirable. It is possible to enable an additional JUnit-style output for the Ant Testing scripts. While the standard console output remains the same, an additional file is written which can then be used for example as the input file for a JUnit post-build action.

To switch on additional JUnit-style output, uncomment the following line in the generated run.cmd script:

set listener=-listener com.softwareag.naturalone.gen.nbs.eclipse.ant.NaturalTestingJunitLogger

The JUnit-style output will then be written to a file named log.xml. The name of the file can be changed by editing the following line in the generated build.xml Ant script:

<property name="NaturalTestingJunitLogger.file" value="log.xml" />

The value log.xml can be exchanged with a name of your choice. Also fully qualified paths can be specified here.

When this has been defined, the resulting file can be used as input, for example in the Publish JUnit test result report post-build action in a Jenkins job.