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:

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 setTo create the Ant script

  1. Select New > Other on the File menu.

    The Select a wizard panel is displayed.

  2. Select Software AG > Testing > Natural Unit Test Ant Script.

    For example:

    graphics/natural-unit-test-ant-script.png

  3. 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.

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

  5. 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.

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

  7. Select Finish.

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

    graphics/build-xml-in-navigator.png

    The build.xml file is displayed in the editor view. For example:

    graphics/build-xml-in-editor.png

  8. 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

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

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.