The Story

About 20 years ago I was searching for a testing framework for RPG and stumbled over the project RPGUnit. It was hosted at Sourceforge which was THE software development platform at that time.

RPGUnit was well structured and well documented. It had a very good web site and even a tutorial. So a motivated developer could get started with RPGUnit in mere minutes.

Everything was fine till I tried to integrate unit testing with RPGUnit into one of my side projects — RPG Next Gen Editor, a free RPG and CL editor based on Eclipse. RPGUnit had no programatic interface at that time. One could execute unit tests by calling the command and the result was written to a spooled file. But a spooled file is a really bad medium for exchanging data. I forked RPGUnit for my editor and extended it to write the test results to a user space object. Now any client capable of reading a user space could get the test results in a programatic way.

I tried to contribute my changes back to the original project but never successfully contacted the
original author. Thus I created my own fork of RPGUnit named ILEUnit. It had the option to write the test results to a user space or to a stream file in the IFS. The tests results were written in XML when using the stream file option, compatible with JUnit. This made it very easy to use ILEUnit from Jenkins because Jenkins can read JUnit test results out-of-the-box.

In the meantime Thomas Raddatz contacted me about using RPGUnit in RDi. I could not help him with creating a RDi plugin (as I didn’t have RDi) but he could use the Eclipse plugin I created for my RPG Next Gen Editor as a base as both RPG Next Gen Editor and RDi are based on Eclipse.

Later on the stream file support in ILEUnit was merged into the much more active fork of RPGUnit Thomas Raddatz has started for the RDi plugin.

Installation

Thomas Raddatz has the most active fork of RPGUnit. A compiled version can be downloaded here from the Github repository as a save file. You only need to copy the save file to the IBM i server and restore the library.

Testing in the IDE

Today every modern RPG editor supports unit tests mostly by using RPGUnit (or some fork of it).

  • RDi
  • MiWorkplace
  • VS Code

But RDi has the best implementation. Kudos to Thomas Raddatz who has done a very good job and is still maintaining the RDi plugin and his fork of RPGUnit named iRPGUnit hosted at Github.

Testing with TOBi

TOBi itself does not support the execution of unit tests. It only manages dependencies and builds objects on IBM i. It is a bit like GNU make but for native IBM i objects (… probably because make is running in the background when using TOBi).

I am using TOBi only to build the test suites which really are just service programs bound to the RPGUnit service program RUTESTCASE.

And because the test suites are just service programs which can be also created with the command CRTSRVPGM I can easily build them with TOBi. I don’t have to use the create command supplied with RPGUnit for creating the service programs.

Executing the test suites is done with Jenkins.

Testing in CI/CD

I am using Jenkins for executing my CI/CD pipelines. Jenkins runs perfectly nice on IBM i which makes it a good choice for implementing CI/CD in the software development lifecycle.

The declarative syntax makes creating pipelines in Jenkins really easy so I will be sticking with that. I will not explain Jenkins pipeline syntax here. Jenkins has a very good documentation and step reference. Feel free to check it out.

I am using the shell step sh to execute the PASE command makei for building my project with TOBi.

It can also be using in conjuction with the PASE command system to execute native IBM i commands. So executing the previously built test suites could look like this:

1
sh script : "system \"RUCALLTST MY_LIB/MY_TEST XMLSTMF('build/test-reports/my_test.xml')\"" , returnStatus : true

The test procedures are executed by RPGUnit and the result is written to the stream in JUnit format. Now I can use the junit step to process the test results.

1
junit testResults : "build/test-reports/*.xml" , allowEmptyResults : true

The result will be nicely rendered in the Jenkins job page like this:

RPGUnit test result in Jenkins job page

Things to consider

Though this has worked quite nice so far you probably want to have a pipeline which is more manageable and reusable. Some things you may consider:

  • What is the installation path for TOBi (yum package vs. manual installation)? Should the path to TOBi be made configurable?
  • Same could be said for RPGUnit. It doesn’t always have be installed in the library RPGUNIT.
  • Which test suites should be executed?
  • Do I need to adjust the library list when running the test procedures?

Many things can be made configureable by using environment variables set in the job configuration and then queried in the pipeline script.

Another option is to put some information into the iproj.json file. The file uses the JSON format which doesn’t use a fixed schema. So you can just add additional data to it, f. e. :

1
2
3
4
5
6
7
8
9
{
"description": "Weather Data Demo",
"curlib": "&OBJECT_LIBRARY",
"includePath": ["include", "/home/mihael/include"],
"buildCommand": "makei build",
"compileCommand": "makei compile -f {filename}",
"postUsrlibl": ["&THIRD_PARTY_LIB", "&ILEASTIC_LIB", "&NOXDB_LIB", "RPGUNIT"],
"unitTests": ["WEATHERUT"]
}

The unitTests attribute can be queried with the tool jq, just execute it in a shell step.

Improving RPGUnit

RPGUnit is quite a nice software library but there are some things I am missing like

  • parameterized tests (example for Java at Baeldung)
  • util procedure for reading and comparing stream files

If you have some spare time and would like to jump into the open source development world feel free to contribute to this project.

Wrap up

Using Git, TOBi and RPGUnit in a Jenkins pipeline can be a great thing for small to medium sized projects when you always do a full build of everything. Incremental builds are not so easy to implement with this combo but there may a possible solution to this in the future which includes replacing one of the four components from this stack.

But I will cover that in my next blog post.

Happy testing!

Mihael