Command Line BBj Unit Test

As a developer, the Eclipse BBj Unit Test plug-in helps you create and run BBj Unit Tests. For an overview of the BBj Unit Test plug-in and running it in the Eclipse IDE, see the original Advantage article or the more detailed “BBj Unit Test Eclipse Plug-In” help page. As outlined there, the Eclipse plug-in offers a user-friendly model for testing your BBj programs.

But once you are familiar with using the BBj Unit Test plug-in for Eclipse, you may be ready to look at an alternative way to unit test your BBj programs: the command line version of BBj Unit Test, which runs outside of the Eclipse framework.

This model is suitable for environments where test execution is happening without a human present. These situations include regression testing as part of an automated build system with no user interface because there may as well be no user present.

Availability

The command-line version of the BBj Unit Test is available as part of any BBj installation as of BBj 21.00. The two files that you need are:

<BBj Installation>/lib/BBjUnitTest.jar - the .jar library for running unit test classes and methods.
<BBj Installation>/utils/bbjunittest/BBjUnitTest.bbj - the BBj program that launches the unit tests. It uses BBjUnitTest.jar to execute .bbjt files without setting up or using Eclipse.

Reminder: To update your command line version of BBj Unit Test files in the future, you must update your BBj installation.

Configuring BBjServices

To use the BBjUnitTest.jar from a BBj program, you need to create a Session Specific ClassPath (SSCP) in the Enterprise Manager that includes it. Follow these steps:

Create a new SSCP by following the steps outlined in the “Creating a New SSCP” section of this article; for this example, we named our new SSCP unittest.
Add the bbj_internal or the bbj_default pre-defined classpath to the new SSCP unittest. This action ensures that your BBj code can still access all core BBj classes.
Add the BBjUnitTest.jar file to the unittest SSCP, below the pre-defined bbj_internal or bbj_default classpath.
Save your changes in the Enterprise Manager.

At this point, you are ready to run a BBj Unit Test as a BBj program.

Running

You can add any of the following command-line options to affect BBj Unit Test’s execution:

Option	Description
--f	This option forces BBj Unit Test to write the output to the result file even if that file already exists. The -f option causes BBj Unit Test to overwrite any result file that may already exist there. If this option is not specified, BBj Unit Test will report an error rather than overwrite an existing result file.
--q	This option suppresses exceptions, causing the program to continue its execution even after errors occur.
--o<file path>	Add the --o option to specify a path and filename for the result file. This path and filename cannot contain spaces, and the path must already exist before you run. If this option is not specified, the output will be written to <temp>\BBjUnitTest\Result.xml.

Table 1. BBj Unit Test Command-Line Options

Open a command line for your operating system and execute the following command, with each of the blue <text> placeholders replaced with the values for your environment:

<BBj Installation>/bin/BBj.exe -CP<unit test SSCP name>unittest -WD<working directory> <BBj Installation>/utils/bbjunittest/BBjUnitTest.bbj - <BBj Unit Test file.bbjt> --o<result file path and name>

where:

<BBj Installation> is the full path to the location where your BBj is installed. This path cannot contain spaces.
<unit test SSCP name> is the name of your SSCP (in this example, unittest).
<working directory> is BBj’s standard working directory and usually must be the full path to the folder to the .bbjt file below. This path cannot contain spaces.
<BBj Unit Test file.bbjt> is the full path to whatever BBj Unit Test file you wish to run, which must have a .bbjt file extension. This path and filename cannot contain spaces.

Note: This value must be separated from the preceding “-” by a single space character.
<result file path and name> is any location and filename you choose to hold the output or results from executing the .bbjt program. This path and filename cannot contain spaces, and the path must already exist before you run.

Note: Options from Table 1 must appear at the end of the command line (anywhere after the .bbjt file to run).

Console Output

When running the BBjUnitTest.bbj program, you should see a BBj SysConsole window showing the BBj output. If one or more errors occur, the SysConsole contains output such as this:

Some errors occurred while executing the test methods

Executed Test Methods Count: 4
Execution Errors Count: 0
Assertion Errors Count: 1

The following Methods failed:
Class: TestMathOperations Method name: addTest()
Cause: Assert.Equals(16,99)

Code Block 1. Example SysConsole Output When An Error Occurs

The console output concludes with an explicit notification of where to find the result XML file:

The XML result file can be found here: C:\Temp\BBjUnitTest\Result.xml

Code Block 2. SysConsole Output Indicating the Result File Location

This SysConsole output is designed for human readability. It does not contain any information that is not also available in the XML result file (see below).

Results

Running BBj Unit Test from the command line creates an XML format result file designed for programmatic parsing. By opening and parsing the XML it contains, your code can act on the results, notifying other processes or individuals when an error occurs or even simply by gathering metrics about your testing progress over time.

Using the “--o” command-line option (as shown in Table 1 above), you can tell BBj Unit Test to write the result file to a specific location. Without the “--o” command-line option, BBj Unit Test will write the results to <temp>\BBjUnitTest\Result.xml, where <temp> is the default “temp folder” for your OS/Java (in Code Block 2, it was “C:\Temp\”).

The result file will contain XML information similar to Code Block 3:

<BBjUnitTestModules>
  <BBjUnitTestClass name="TestMathOperations"
      filePath="C:\UnitTest\TestMathOperations.bbjt">
   <BBjUnitTestMethod name="setup()" executed="true"
     type="BeforeClass"></BBjUnitTestMethod>
   <BBjUnitTestMethod name="addTest()" executed="true" type="Test" duration="166">
      <BBjUnitTestError type="AssertionError">
        <line>17</line>
        <description>Assert.Equals(16,99)</description>
        </BBjUnitTestError>
      </BBjUnitTestMethod>
      <BBjUnitTestMethod name="multTest()" executed="true"
        type="Test" duration="2"></BBjUnitTestMethod>
      <BBjUnitTestMethod name="subTest()" executed="true"
        type="Test" duration="1"></BBjUnitTestMethod>
      <BBjUnitTestMethod name="divTest()" executed="true"
        type="Test" duration="2"></BBjUnitTestMethod>
    </BBjUnitTestClass>
  </BBjUnitTestModules>

Code Block 3. Example XML Result File

The following definitions explain the XML elements and attributes that may appear in the XML result file:

For the BBjUnitTestClass element:

The name attribute identifies the class for the unit test methods it contains.
The filePath attribute identifies the .bbjt file executed.

For the BBjUnitTestMethod element:

The name attribute identifies the specific unit test method.
The executed attribute tells whether or not this unit test method was executed (it may have been excluded, for example). The valid values are “true” and “false.”
The type attribute indicates what type of unit test method it was. The valid values are Before, BeforeClass, Test, After, AfterClass, and Ignore, as determined by the corresponding Annotation entries in Table 1 of the Examining the Test Results section in the “BBj Unit Test Eclipse Plug-In” help page.
The duration attribute tells how much time elapsed during this method’s execution in milliseconds.

For the BBjUnitTestError element (which only appears inside of BBjUnitTestMethod elements where an error occurred during execution):

The type attribute identifies the specific type of error that occurred. The valid values are ExecutionError and AssertionError (see the Examining the Test Results section in the “BBj Unit Test Eclipse Plug-In” help page for details)
The line sub-element provides the line number where the error occurred in the .bbjt file
The description sub-element provides detailed textual information about what failed on the line specified for the error