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 offers a Natural Unit Test Ant Wizard which collects all required information (such as the Natural project where the tests are located or the RPC environment to be used) and writes it to an Ant script which is finally 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 in the following topics:
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.
- RPC Environment
You can select the RPC environment which should be used to run the Natural unit tests. An RPC environment can be defined in the RPC Environment monitor of the EntireX perspective. For more information, refer to the EntireX documentation.
The wizard creates all required RPC properties such as Broker ID or Server Address into the test file.
- 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 following components must be installed and accessible:
Apache Ant 1.7.1 or above.
Java Development Kit (JDK) 11 or above.
If you want to use the Ant checkout task of the Natural Unit Test Ant script, the corresponding repository tool has to be installed (either the Subversion command line tool 1.5.2 or above, the CVS command line tool 1.11 or above, or the Git command line tool 1.9.5 or above)
You have to copy the following JAR files, which contain the necessary processing code, from the NaturalONE Eclipse installation to the new directory:
com.softwareag.entirex.core_<version>.jar
com.softwareag.entirex.runtime_<version>.jar
com.softwareag.natural.unittest.ant_<version>.jar
com.softwareag.natural.unittest.core_<version>.jar
com.softwareag.naturalone.natural.auxiliary_<version>.jar
com.softwareag.naturalone.gen.common.logging_<version>.jar
com.thoughtworks.xstream_<version>.jar
org.apache.log4j.api_<version>.jar
org.apache.log4j.core_<version>.jar
Where <version> represents the corresponding version number that is part of the JAR file name.
You have to copy your Natural unit test file which has been created by the Natural Unit Test Ant wizard into the directory which has been specified in the wizard as the root directory (this is the base directory for processing).
When all prerequisites are in place, the Natural unit testing can be started by issuing specific Ant calls. (where the default name unittest.xml is used).
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 versioning 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 sections describe how to run Ant-based Natural unit tests from the command line:
In this example, the folder P:\NatUnit contains the NaturalONE bundles required for Natural unit testing. The path to the Ant binaries must have been set. In addition to the .jar files, the Ant script unittest.xml is also available in this folder.
In order to run the Ant based Natural unit testing script from a specific root folder, to checkout from a specific repository site, or to use a specific project name, the following adjustments are applied in the file unittest.xml:
natural.ant.project.rootdir
value="P:\NatUnit"
natural.ant.project.name value="UnitTests2"
natural.ant.repository.module
value="UnitTests2"
The project UnitTests2 will be checked out from an SVN repository using the following command at the command prompt:
ant -lib P:\NatUnit -buildfile unittest.xml checkout
After the checkout task has been run, the Natural project UnitTests2 is now also available as a subdirectory in the root folder P:\NatUnit.
In the next step, the Ant script is running the tests located in
the UnitTest2 project. It is using an Ant listener to
write a JUnit-style log file in addition to the console output. The
unittest task is not explicitly specified in the command line,
since this task is the default task:
ant -lib P:\NatUnit -buildfile unittest.xml -listener com.softwareag.natural.unittest.ant.framework.NaturalTestingJunitLogger
The console shows the results of the test run. The single test case SECTEST1 has been run successfully.
The file log.xml with the JUnit compatible format has been added to the root folder P:\NatUnit.
The log file is displayed inside Eclipse with the view:
This section describes the Ant properties that the Natural Unit Test
Ant wizard generates into the Natural unit test Ant script. Some properties can
be modified according to specific needs. However, in most cases it will be
sufficient to just adapt the natural.ant.project.rootdir property
since the wizard assigns the Eclipse workspace path to this property.
| Property | Description |
|---|---|
natural.ant.project.rootdir
|
The root folder where 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.name
|
The name of the project containing the tests. Apart from the various test cases like .exttst, .nattst, and .seqtst all Natural sources relevant for constructing the IDL of a calling subprogram must be available. |
natural.testing.ant.rpcpwd |
The encrypted RPC password. |
natural.testing.ant.rpcuid |
The RPC user ID. |
natural.testing.ant.rpcenvname |
The name of the RPC environment. |
natural.testing.ant.srvaddr
|
The RPC address string. |
natural.testing.ant.file.name |
The name of the Ant script. |
natural.testing.ant.brokerid |
The used Broker. |
natural.testing.ant.exxpwd |
The encrypted EntireX password. |
natural.testing.ant.exxuid |
The EntireX user. |
NaturalTestingJunitLogger.file |
The name of the JUnit-style logfile. The default is log.xml. A fully qualified path could also be entered. The log file will only be generated when the ant listener
|
natural.ant.project.steplibs |
The steplib chain. This chain is just used for finding the Natural sources involved in constructing the IDL to be passed to the Broker/RPC environment but will not be used for passing the steplibs to the RPC runtime environment. As a consequence all Natural sources like parameter data areas must be available in the Natural unit test project. |
natural.ant.referenced.projects |
The projects referenced by the Natural unit test project.
The default 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 like a parameter data area in a library of a referenced project. |
natural.testing.ant.logon |
Logon to the broker in order to perform authentication. The default is YES. This is especially mandatory for secured Broker/RPC environments. |
natural.ant.failonerror |
The Ant processing terminates after the first error. The default is NO. |
natural.testing.ant.writehistory |
Writes history files to the fixed folder Testing-History located under the project root. The default is NO. |
natural.ant.project.password.encryption |
Enables repository password encryption. The default is YES. |
natural.ant.repository.version |
The version to check out from the repository. |
natural.ant.repository.type |
The repository type. |
natural.ant.repository.password |
The repository password. |
natural.ant.repository.username |
The repository user. |
natural.ant.repository.access.method |
The repository access method. |
natural.ant.repository.url |
The URL of the repository. |
natural.ant.repository.module |
The name of the project to check out from the repository. |
As of NaturalONE version 9.2.1, Code Generation logging is based on Apache Log4j 2 instead of Apache Log4j.
For this reason, the natural.ant.searchpath property in
Creating Ant
Scripts to Run Unit Tests has been changed. If you create
a new Natural Unit Test Ant Script, the correct
natural.ant.searchpath will be generated. However, if you have
Natural Unit Test Ant scripts in your Natural Projects directory created with
NaturalONE before version 9.2.1, you must migrate these 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) 11 or above
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>