Usage

Using RPGUnit is splitted into two parts:

Creating test cases
Running test cases

Creating test cases

In RPG a test case is an exported procedure. Its name must start with test in order to be accepted by the RPGUnit utility. But that also means that you must not export procedures, starting with test, that are not intended to be a test case.

In order to use RPGUnit procedures you need to add copy book TESTCASE to your source member:

 /include qinclude,TESTCASE                  iRPGUnit Test Suite

Test case examples

testGenerateUUID
testUpdateStatus
testGenerateMD5
testGetNextRecord

One or more test cases make a test suite. In RPG we use a service program for that. A test suite (service program) is compiled with command RUCRTRPG.

RUCRTRPG TSTPGM(RPGUNIT/RUPLUGINT1) SRCFILE(RPGUNITT1)

Member QSRC.TEMPLATE is an example of a test suite. It does not do any harm but produces a spooled file with the execution flow.

Note: You need to specify a named source member and compiler option *EVENTF in order to get back your compile result in RDi. Furthermore parameter SRCMBR has to be set to the name of source member to enable RDi to load the compile result. For example:
RPGLE: RUCRTRPG TSTPGM(&O/&N) SRCFILE(&L/&F) SRCMBR(&N) COPTION(*SRCSTMT *EVENTF) DBGVIEW(*LIST) SQLRPGLE: RUCRTRPG TSTPGM(&O/&N) SRCFILE(&L/&F) SRCMBR(&N) POPTION(*EVENTF) COMPILEOPT('DBGVIEW(*LIST)')
It is also recommended to specify *SRCSTMT, to directly jump to the failed source statement, when double-clicking an error in the iRPGUnit view.

Running test cases on a CL command line

Once you have your test suites in place, you can execute them with command RUCALLTST. By default the command executes all test cases of a test suite. If you want to run a single test case you can specify the name of the test case (procedure name) at parameter TSTPRC at the command prompt.

RUCALLTST TSTPGM(RUPLUGINT1)

RUCALLTST TSTPGM(RUPLUGINT1) TSTPRC(TESTALLOK_2)

Running test cases from RDi

From RPi you can use the Remote Systems Explorer to run your test suites. There is a new context menu 'Run RPGUnit Test' that lets you select and run your test suites.

Run RPGUnit Test

The result is shown in view 'iRPGUnit':

Display RPGUnit Test Result

From there you can choose between the following options:

Collapse All
Expand All
Show Failures Only
Rerun All Test Cases
Disable Report
Enable Debug Mode

The following options are available from the context menu:

iRPGUnit Context Menu

Rerun Selected Test Case
Display Report
Edit LPEX (also: mouse double-click)
Remove Selected Test Suite

Header properties:

Runs : Number of last executed test cases / Total number of test cases in view

Errors : Total number of errors in view

Failures : Total number of failed test cases in view

Assertions : Total number of executed assertions in view

Result of a failed unit test:

Display RPGUnit Test Result

Use the properties view to see the properties of a selected line in a grid:

Display RPGUnit Test Result

By default, the execution time is hidden in the properties view. You can display it with the "Show Advanced Properties"

button.

Hint: Disable preference option Show result view to keep the focus on the view where you started a unit test after a test run. The RPGUnit result view displays a green or red icon on the tab of the view to show the result.

Indicates that the unit test finished successfully.

Indicates that the unit test ended with errors. Check the result view for details.

Indicates that all unit tests had been canceled by the user. Check the result view for details.

Unit Tests With Errors

In case that a unit test ended with errors, it may be helpful to see the messages of the job log. Use the preferences or the view menu to set the appropriate message capturing level:

Display RPGUnit Test Result

Do not capture anything - No messages are captured from the job log.

Capture escape messages on unexpected errors - Escape messages are captured from the job log, when a test case ended with errors.

Capture all messages on unexpected errors - All messages of the job log are captured, when a test case ended with errors.

Capture all job log entries - All messages of the job log are captured at any time.

Format job log entries - Specifies whether or not the job log entries are formatted when appended to the Commands Log view.

Captured messages are displayed in the Commands Log view.

Error Messages

The following error dialog is displayed, when a service program is not recognized as a RPGUnit test suite or when a procedure is not recognized as a test case. Check the following rules to identify the problem:

Depending on the preferences service programs must be tagged with 'RPGUNIT' (user defined attribute or description).
Procedure names must start with 'test'.

Error messages when attempting to run a test case

Runs	:	Number of last executed test cases / Total number of test cases in view
Errors	:	Total number of errors in view
Failures	:	Total number of failed test cases in view
Assertions	:	Total number of executed assertions in view

		Indicates that the unit test finished successfully.
		Indicates that the unit test ended with errors. Check the result view for details.
		Indicates that all unit tests had been canceled by the user. Check the result view for details.

Do not capture anything	-	No messages are captured from the job log.
Capture escape messages on unexpected errors	-	Escape messages are captured from the job log, when a test case ended with errors.
Capture all messages on unexpected errors	-	All messages of the job log are captured, when a test case ended with errors.
Capture all job log entries	-	All messages of the job log are captured at any time.
Format job log entries	-	Specifies whether or not the job log entries are formatted when appended to the Commands Log view.