You can use the Natural Unit Test Ant Script wizard to create XML-based Ant scripts to run unit test files (file extension .exttst, .nattst, and .seqtst). You can run the Ant script from within NaturalONE or from the command line.
Note
It is not possible to run business services via the Natural Unit Test Ant Script.
This document covers the following topics:
Using the Natural Unit Test Ant Script Wizard to Run Natural Unit Tests
Running the Natural Unit Test Ant Script from the Command Line
For information on creating unit test files, see:
NaturalONE provides a Natural Unit Test Ant wizard which collects all required information (such as the Natural project in which the tests are located or the connection to be used) and writes it to an Ant script that is then used to run the Natural unit tests. This Ant script makes the testing task highly configurable and repeatable and allows you to run the tests unattended.
This Ant-based Natural unit testing can either be started from within the NaturalONE Eclipse environment or via the Ant command line utility. It provides the following functionality:
Run Natural unit test cases available in a root folder hosting the project.
Check out a Natural project with Natural unit test cases and required Natural sources from a version control system (either CVS, Subversion or Git); this is usually done outside of Eclipse.
The Natural Unit Test Ant Script wizard creates a Natural test file in your project root folder for executing Natural unit tests. This is an Ant script. You can create one or more Natural test files for a project, and you can also load an existing Natural test file and modify the current settings.
To use the Natural Unit Test Ant Script wizard
In the Project Explorer view or in the Natural Navigator view, select the Natural project for which you want to create the test file.
Or:
If you want to load the settings of an existing Natural test file, select this file
in the Project Explorer view or in the Natural
Navigator view.
From the menu or from the context menu, choose .
In the resulting New dialog box, expand the Software AG node, then expand the Testing node, select and finally click the button.
The first page of the wizard (General Settings) appears.
Specify all required information as described individually for each wizard page in the following sections below. Use the button repeatedly to proceed from the first page of the wizard to the last page.
When all required information has been provided, click the button .
The different pages of the Natural Unit Test Ant Script wizard are described below.
On the first page of the wizard, you define general settings for the Natural unit testing.
- Project
The project which contains the Natural unit test cases and required Natural sources.
- Natural Unit test file
The default name for the Natural unit test file is unittest.xml. This name is shown in this text box when an existing Natural test file was not selected while invoking the wizard. However, when an existing Natural test file was selected, the name of the selected file is shown and the settings from this file are automatically loaded.
You can enter any other name for your new test file. It is recommended that your new test file also has the extension .xml.
Notes:
- If you keep the name unittest.xml, the settings from an existing Natural test file with the same name are loaded the next time you select the project and invoke the wizard.
- If you want to load an existing Natural test file, choose the button. A dialog appears, providing for selection of all Natural test files in the current project. Next, you have to choose the button. Otherwise, the settings in this file are not shown in the wizard and may thus be overwritten unintentionally.
- If you want to return to the default settings of the test wizard (this also includes the information that can be specified on the other pages of the wizard), choose the button.
- Connection
You can select the connection to be used to run the Natural unit tests. You can use either Natural Subprogram Server connections or EntireX RPC environments. For information about adding environments to the list, see Define Additional Connections.
The wizard creates all required properties for the selected connection in the Natural unit test file. Different sets of properties and dependencies are created depending on whether the target is a Subprogram Server connection or an EntireX RPC environment.
Note
Because of the different dependencies and properties, an existing Natural unit test file created for an EntireX RPC environment cannot be used with a Subprogram Server connection, and vice versa.- Enable fail-on-error for Ant script
When enabled, the Ant script reports errors and terminates in the case of a build failure.
When disabled, the Ant script still reports errors but does not terminate.
- Root directory
This path should only be changed when you intend to start the Natural unit testing from the command line (that is, when the Natural unit testing is not to be started from Eclipse).
Specify the directory in which the selected project is to be checked out and where the processing takes place. When the testing is supposed to run on a different machine, you can insert the desired root path using copy and paste.
On this page of the wizard, you define all settings related to the versioning repository. This can be either Subversion (SVN), Git or CVS.
- Type
From the Type drop-down list box, select the type of versioning repository that you are using, and then specify all required information. The names of the text boxes and their availability changes according to the selected type.
The wizard usually collects a set of default information as given for the selected project. In most cases, only minor corrections have to be made to the defaults, for example, user ID and password may have to be provided
- Enable password encryption
When enabled, the repository password that is used in the Natural unit test file is stored in an encrypted format.
On this page of the wizard you can write history files or specify a log file for generating a Junit compatible Test Report.
- Write history files
If enabled, a history file is written to the Testing-History folder of the project any time the Natural unit test file is run.
- Log file name
The name of a JUnit-style Test Report. For further information please refer to Generating a JUnit-style Test Report.
Usually, when running the Natural unit test 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 Natural unit test script. 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, the Natural unit test Ant script has to be launched with an Ant listener:
ant ... -listener com.softwareag.natural.unittest.ant.framework.NaturalTestingJunitLogger
The JUnit-style output will then be written to a file named log.xml. The name of the file can be changed.
The resulting file can be used as input, for example in the Publish JUnit test result report post-build action in a Jenkins job.
When you start the Natural unit test Ant script from Eclipse, it is not possible to execute the checkout target of the Ant script since this target would access the versioning repository, and this is not feasible from within an Eclipse environment. If you want to check out a specific revision from the versioning repository, you have to start the Natural unit test Ant script from the command line as described in Running the Natural Unit Test Ant Script from the Command Line.
However, for testing purposes it is helpful to start the Natural unit test Ant script from Eclipse. Since the Natural unit testing file is an Ant script, the built-in Eclipse functionality of starting Ant scripts is used here. The unittest target (which is the default target) of the Ant script will then be executed.
To start the Natural Unit Test Ant script from Eclipse
In the Project Explorer view or in the Natural Navigator view, select your Natural unit test file, invoke the context menu and choose Run As > Ant Build.
The Natural unit test process is started and the output test run is written to the Console view.
Notes:
You can start the Natural unit test Ant script from a Windows command line such as the Command Prompt (cmd.exe) or from a shell command line on a Linux system. When you start the Natural unit tests from the command line or shell, special requirements must be met.
The Natural unit testing can be started by issuing specific Ant calls (the default file name is unittest.xml).
Print the help screen of the Natural Unit Test Ant script:
ant -lib path-to-mylib -buildfile unittest.xml help
Perform an initial checkout of the project containing the Natural unit tests from the version control repository:
ant -lib path-to-mylib -buildfile unittest.xml checkout
Perform Natural unit test run with a Junit-style log file:
ant -lib path-to-mylib -buildfile unittest.xml -listener com.softwareag.natural.unittest.ant.framework.NaturalTestingJunitLogger
The following components must be installed and accessible:
Apache Ant 1.7.1 or later, and the path to the Ant binaries must be configured.
Java Development Kit (JDK) 21 or later.
If you want to use the Ant checkout task of the Natural Unit Test Ant script, the corresponding repository tool must be installed (either the Subversion command-line tool version 1.5.2 or later, the CVS command line-tool version 1.11 or later, or the Git command-line tool version 1.9.5 or later).
Create a new directory in which you can run the unit tests.
Copy the required JAR files, which provide the necessary processing functionality, from the NaturalONE Eclipse installation to the new directory.
Different JAR files must be copied for Natural Subprogram Server connections and EntireX RPC environments.
For Subprogram Server connections you need:
com.softwareag.natural.openapi.parser_*.jar
com.softwareag.natural.openapi.protocol.callnat_*.jar
com.softwareag.natural.unittest.ant_*.jar
com.softwareag.natural.unittest.core_*.jar
com.softwareag.naturalone.gen.common.logging_*.jar
com.softwareag.naturalone.gen.npi.wrapper_*.jar
com.softwareag.naturalone.natural.auxiliary_*.jar
com.softwareag.naturalone.natural.parser_*.jar
com.softwareag.rpc.api_*.jar
com.thoughtworks.xstream_*.jar
io.netty.*_*.jar
io.projectreactor.reactor-core_*.jar
org.apache.logging.log4j.api_*.jar
org.apache.logging.log4j.core_*.jar
reactive-streams_*.jar
slf4j.api_*.jar
slf4j.simple_*.jar
For EntireX RPC environments you need:
com.ibm.entirex.core_*.jar
com.ibm.entirex.runtime_*.jar
com.softwareag.natural.unittest.ant_*.jar
com.softwareag.natural.unittest.core_*.jar
com.softwareag.naturalone.gen.common.logging_*.jar
com.softwareag.naturalone.natural.auxiliary_*.jar
com.softwareag.naturalone.natural.parser_*.jar
com.softwareag.rpc.api_*.jar
com.thoughtworks.xstream_*.jar
org.apache.logging.log4j.api_*.jar
org.apache.logging.log4j.core_*.jar
Copy the Natural unit test file (unittest.xml) created by the Natural Unit Test Ant wizard to the new directory.
Then change the root directory in the unittest.xml file to the new directory:
<property name="natural.ant.project.rootdir" value="<your-new-directory>" />
Checkout your project using the following command:
ant -lib <your-new-directory> -buildfile unittest.xml checkout
After the checkout task has run, the Natural project is also available as a subdirectory in the new directory.
Alternatively, you can copy the Natural project to the new directory.
In the next step, the Ant script runs the tests located in your Natural project. It
uses an Ant listener to write a JUnit-style log file in addition to the console
output. The unittest task is not explicitly specified on the command line
because this it is the default task:
ant -lib <your-new-directory> -buildfile unittest.xml -listener com.softwareag.natural.unittest.ant.framework.NaturalTestingJunitLogger
The console displays the results of the test run.
In addition, the JUnit-style log file log.xml is created in the new directory.
You can open the log.xml file in NaturalONE, and the result of the tests are displayed in the view.
This section describes the Ant properties that the Natural Unit Test Ant wizard generates
in the Natural unit test Ant script. Some properties can be modified to meet specific
requirements. However, in most cases, it is sufficient to adapt only the
natural.ant.project.rootdir property because the wizard assigns the Eclipse
workspace path to this property.
| Property | Connection Type | Description |
|---|---|---|
natural.ant.failonerror |
all |
The Ant processing terminates after the first error. The default value is NO. |
natural.ant.project.name |
all |
The name of the project containing the tests. In addition to the various test cases, such as .exttst, .nattst, and .seqtst, all Natural sources required for the subprogram call must be available. |
natural.ant.project.password.encryption |
all |
Enables repository password encryption. The default value is YES. |
natural.ant.project.rootdir |
all |
The root folder in which the project containing the Natural unit test cases is located. The Natural Unit Test Ant wizard always assigns the Eclipse workspace path to this property. |
natural.ant.project.steplibs |
all |
The steplib chain. |
natural.ant.referenced.projects |
all |
The projects referenced by the Natural unit test project. The default value is
If specified, the referenced projects must also be checked out. Referenced projects are accessed during test case execution to potentially find a required Natural source, such as a parameter data area in a library of a referenced project. |
natural.ant.repository.access.method |
all |
The repository access method. |
natural.ant.repository.module |
all |
The name of the project to check out from the repository. |
natural.ant.repository.password |
all |
The repository password. |
natural.ant.repository.type |
all |
The repository type. |
natural.ant.repository.url |
all |
The URL of the repository. |
natural.ant.repository.username |
all |
The repository user. |
natural.ant.repository.version |
all |
The version to check out from the repository. |
natural.testing.ant.brokerid |
EXX |
The Broker used. |
natural.testing.ant.exxpwd |
EXX |
The encrypted EntireX password. |
natural.testing.ant.exxuid |
EXX |
The EntireX user. |
natural.testing.ant.file.name |
all |
The name of the Ant script. |
natural.testing.ant.hostname |
NPI |
The Subprogram Server host name. |
natural.testing.ant.logon |
EXX |
Logs on to the Broker to perform authentication. The default value is YES. This is especially required for secured EntireX RPC environments. |
natural.testing.ant.npipwd |
NPI |
The encrypted Subprogram Server password. |
natural.testing.ant.npiuid |
NPI |
The Subprogram Server user ID. |
natural.testing.ant.oidc |
NPI |
Authentication of the Subprogram Server is performed using OIDC. The default value is NO. |
natural.testing.ant.portnumber |
NPI |
The Subprogram Server port number. |
natural.testing.ant.rpcenvname |
all |
The name of the connection. |
natural.testing.ant.rpcpwd |
EXX |
The encrypted RPC password. |
natural.testing.ant.rpcuid |
EXX |
The RPC user ID. |
natural.testing.ant.srvaddr |
EXX |
The RPC address string. |
natural.testing.ant.ssl |
NPI |
Uses SSL for the Subprogram Server connection. The default value is NO. |
natural.testing.ant.writehistory |
all |
Writes history files to the fixed Testing-History folder located under the project root. The default value is NO. |
NaturalTestingJunitLogger.file |
all |
The name of the JUnit-style log file. The default is log.xml. A fully qualified path can also be entered. The log file is generated only when the ant listener
|
As of NaturalONE version 9.3.4, new dependencies are necessary for the Testing functionality.
For this reason, the natural.ant.searchpath property described in
Creating Ant Scripts to Run Unit Tests has changed for EntireX RPC
environments. If you create a new Natural Unit Test Ant script, the correct
natural.ant.searchpath value is generated. However, if you have Natural
Unit Test Ant scripts in your Natural Projects directory that were created with a version
of NaturalONE earlier than 9.3.4, you must migrate those scripts to the new format.
To migrate the Natural Unit Test Ant scripts
In the Project Explorer view or in the Natural Navigator view, select the Natural project for which you want to migrate scripts.
Invoke the context menu and choose > .
In the Migrate Natural Unit Test Ant Scripts dialog box, all projects which contain scripts with the old format will be listed. The projects which are selected will be migrated.
Select all projects you want to migrate or select Migrate all to migrate all listed projects. Then click .
The Natural Unit Test Ant scripts will be migrated to the current format and a backup file with the .bck extension will be created for every migrated script (e.g. unittest.xml.bck).
You can start the Natural Unit Test Ant script migration from a Windows command line such as the Command Prompt (cmd.exe) or from a shell command line on a Linux system. When you start the migration from the command line or shell, special requirements must be met.
Java Development Kit (JDK) 21 or later.
Copy the following JAR file, which contains the necessary processing code, from the NaturalONE Eclipse installation to the new directory:
com.softwareag.natural.unittest.ant_<version>.jar
Where <version> represents the corresponding version number that is part of the JAR file name.
When all prerequisites are in place, the Natural Unit Test Ant script migration can be started by issuing specific java calls.
Print the help screen:
java -jar com.softwareag.natural.unittest.ant_<version>.jar
List all scripts with old format on the given path:
java -jar com.softwareag.natural.unittest.ant_<version>.jar findAntUnitScriptsToMigrate <Path_to_search>
Migrate all scripts with old format on the given path:
java -jar com.softwareag.natural.unittest.ant_<version>.jar migrateAntUnitScripts <Path_to_search>
